Getting Started

Option A: Use as npm Package (recommended)

The fastest way to deploy a gitmode server. No WASM build needed — the pre-built binaries are included.

Prerequisites

• Node.js 22+
• A Cloudflare account with Workers, R2, and Durable Objects

Scaffold and Deploy

npx gitmode init     # Creates worker/index.ts + wrangler.jsonc
npm install
npx gitmode deploy   # Deploys to Cloudflare Workers

Import into an Existing Worker

import { RepoStore, PackWorkerDO, createHandler } from "gitmode";
export { RepoStore, PackWorkerDO };

// Minimal — all git protocol + REST API routes handled automatically
export default { fetch: createHandler() };

With custom auth:

import { RepoStore, PackWorkerDO, createHandler } from "gitmode";
export { RepoStore, PackWorkerDO };
const gitmode = createHandler();
export default {
  fetch(req, env) {
    if (!authorize(req)) return new Response("Unauthorized", { status: 401 });
    return gitmode(req, env);
  }
};

Client-Only Usage

For client-side git primitives (SHA-1, zlib, delta) without any server dependencies:

import { WasmEngineCore } from "gitmode/client";
const engine = await WasmEngineCore.create();
// Use engine.sha1Hash(), engine.zlibInflate(), etc.

---

Option B: Clone and Develop

For contributing or customizing gitmode itself.

Prerequisites

• Node.js 22+
• pnpm
• Zig 0.15+ (for WASM builds)
• Binaryen (wasm-opt, wasm-metadce)
• A Cloudflare account with Workers, R2, and Durable Objects

Setup

git clone https://github.com/teamchong/gitmode.git
cd gitmode
pnpm install

Build WASM

The Zig WASM module provides SHA-1, zlib, packfile parsing, and delta encoding. You must build the WASM module before running the dev server or tests.

pnpm run build:wasm

This compiles the Zig code, runs wasm-metadce to remove unused exports, and optimizes with wasm-opt -Oz.

Development

Start a local dev server:

pnpm run dev

Then use git against the local server:

# Initialize a repo via REST API
curl -X POST http://localhost:8787/api/repos/myuser/myrepo/init

# Commit files via REST API
curl -X POST http://localhost:8787/api/repos/myuser/myrepo/commits \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "main",
    "message": "initial commit",
    "author": "Your Name",
    "email": "you@example.com",
    "files": [{"path": "README.md", "content": "# My Repo"}]
  }'

# Clone over HTTP
git clone http://localhost:8787/myuser/myrepo.git

SSH Transport

gitmode includes an SSH-to-HTTP proxy for git clone ssh://... support. Start it alongside the dev server:

# Terminal 1: dev server
pnpm run dev

# Terminal 2: SSH proxy (translates SSH → HTTP)
pnpm run ssh:proxy

Then use SSH URLs:

git clone ssh://git@localhost:2222/myuser/myrepo.git
git push  # works over SSH too

The proxy accepts all SSH connections without authentication (development mode). See Git Protocol for protocol details.

Testing

# Unit + integration tests (vitest with miniflare, 87 tests)
pnpm test

# HTTP conformance tests with real git CLI
pnpm run test:conformance

# SSH conformance tests (clone, push, fetch, branches, tags, binary files)
pnpm run test:ssh

Deploy

pnpm run deploy

Ensure your wrangler.jsonc has the R2 bucket and Durable Object bindings configured. See Deployment for details.