# Git Operations in Cloudflare Computer: How Clone, Commit, Push, and Pull Work Inside the Workspace

> Discover how Git operations like clone, commit, push, and pull function in Cloudflare Computer. Learn about the isomorphic-git library powering this JavaScript-based Git implementation.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: internals
- Published: 2026-08-07

---

**The Cloudflare Computer workspace runs a complete Git implementation powered by isomorphic‑git, a pure‑JavaScript Git library that operates entirely within the sandboxed environment—no native Git binary required.**

All Git functionality in the Cloudflare Computer project is exposed through the `Workspace.git` API, which provides familiar CLI-equivalent commands for clone, commit, push, pull, and more. Because the implementation runs against an in‑memory virtual file‑system (VFS), repositories persist across runtime invocations while remaining fully sandboxed and deterministic.

This article explains how each Git operation is implemented, walks through the source code architecture, and provides runnable examples you can use in your own Computer scripts.

---

## Core Architecture: Git Inside the VFS

The Git stack in Cloudflare Computer is layered on top of three foundational components:

- **isomorphic‑git** – A pure‑JavaScript Git implementation that handles all Git protocol logic, object parsing, and DAG operations.
- **Virtual File‑System (VFS)** – The workspace's persistent in‑memory filesystem where all repository data lives.
- **Custom FS Adapter** – A bridge that translates between isomorphic‑git's expected `fs` API and the workspace VFS.

According to the Cloudflare Computer source code, this design allows Git operations to behave identically to native Git while remaining entirely within the sandboxed runtime environment.

---

## How Clone Works: [`src/git/clone.ts`](https://github.com/cloudflare/computer/blob/main/src/git/clone.ts)

The `clone` operation initializes a new repository by downloading objects from a remote URL and writing them into the VFS.

In [`packages/computer/src/git/clone.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/clone.ts), the implementation calls `isomorphicGit.clone` with two critical customizations:

- A **custom `fs` implementation** that redirects all file operations to the workspace VFS
- A **network handler** (from [`network.ts`](https://github.com/cloudflare/computer/blob/main/network.ts)) that performs HTTPS requests through the Computer runtime

```typescript
// Clone a repository into the workspace VFS
await workspace.git.clone('https://github.com/example/repo.git', {
  dir: '/repo',           // Target location in virtual filesystem
  singleBranch: true,     // Shallow clone: single branch only
  depth: 1,               // Shallow clone: latest commit only
});

```

The clone module handles ref advertisement, packfile negotiation, and object storage entirely within the VFS at the specified `dir` path.

---

## Staging and Status: [`src/git/staging.ts`](https://github.com/cloudflare/computer/blob/main/src/git/staging.ts) and [`src/git/status.ts`](https://github.com/cloudflare/computer/blob/main/src/git/status.ts)

Once a repository exists in the VFS, you interact with the index through the staging and status modules.

### Adding Files to the Index

[`packages/computer/src/git/staging.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/staging.ts) wraps `isomorphicGit.add` and `isomorphicGit.remove`:

```typescript
// Stage a file for commit
await workspace.git.add({ dir: '/repo', filepath: 'README.md' });

// Remove a file from the index
await workspace.git.remove({ dir: '/repo', filepath: 'old-file.txt' });

```

### Checking Repository Status

[`packages/computer/src/git/status.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/status.ts) compares the VFS index against the working tree:

```typescript
const status = await workspace.git.status({ dir: '/repo' });
console.log(status);
// Returns: { staged: [...], modified: [...], deleted: [...], untracked: [...] }

```

The status module uses `isomorphicGit.status` internally but ensures all path resolutions happen within the workspace VFS boundary.

---

## Creating Commits: [`src/git/commit.ts`](https://github.com/cloudflare/computer/blob/main/src/git/commit.ts)

The commit module in [`packages/computer/src/git/commit.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/commit.ts) constructs commit objects with proper Git semantics—tree objects, parent references, author/committer metadata, and timestamps—then writes them to the VFS‑backed object store.

```typescript
await workspace.git.commit({
  dir: '/repo',
  message: 'Update README with installation instructions',
  author: {
    name: 'Alice',
    email: 'alice@example.com'
  }
});

```

This creates a complete Git commit that includes:

- A tree object representing the entire staged directory structure
- Parent commit reference(s) linking to the previous HEAD
- GPG‑free author verification (standard for isomorphic‑git)
- Object storage in `.git/objects` within the VFS

---

## Network Operations: Push and Pull in [`src/git/network.ts`](https://github.com/cloudflare/computer/blob/main/src/git/network.ts)

The `push` and `pull` commands require HTTP transport implementation. The [`packages/computer/src/git/network.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/network.ts) module provides this by implementing the Git smart HTTP protocol:

| Protocol feature | Implementation |
|-----------------|----------------|
| `git-upload-pack` | Used for fetch/clone operations |
| `git-receive-pack` | Used for push operations |
| HTTPS transport | Forwarded through Computer runtime fetch |

### Pull: Fetch and Merge

```typescript
// Fetch and merge remote changes into current branch
await workspace.git.pull({
  dir: '/repo',
  remote: 'origin',
  ref: 'main'
});

```

### Push: Upload Local Commits

```typescript
// Push current branch to remote
await workspace.git.push({
  dir: '/repo',
  remote: 'origin',
  ref: 'main'
});

```

The network module handles authentication headers, packfile generation, and ref update negotiation according to the Git HTTP protocol specification.

---

## Worktree and Checkout: [`src/git/worktree.ts`](https://github.com/cloudflare/computer/blob/main/src/git/worktree.ts)

The worktree module provides branch‑switching capabilities by manipulating the VFS contents to match a target commit:

```typescript
// Checkout a specific branch or commit
await workspace.git.checkout({
  dir: '/repo',
  ref: 'feature-branch'
});

```

This updates the working directory in the VFS to reflect the tree at the specified ref, modifying files, creating directories, and removing paths as needed while preserving uncommitted changes when possible.

---

## The FS Adapter: Bridging Libraries in [`src/git/adapter.ts`](https://github.com/cloudflare/computer/blob/main/src/git/adapter.ts)

All Git modules rely on [`packages/computer/src/git/adapter.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/adapter.ts), which implements the Node‑style `fs` API that isomorphic‑git expects:

```typescript
// Pseudo‑code representation of the adapter interface
interface GitFSAdapter {
  readFile(path: string): Promise<Buffer>;
  writeFile(path: string, data: Buffer): Promise<void>;
  readdir(path: string): Promise<string[]>;
  mkdir(path: string): Promise<void>;
  stat(path: string): Promise<Stats>;
  // ... additional fs methods
}

```

Every call is translated into an operation against `workspace.fs`, the Computer runtime's virtual filesystem. This is the key abstraction that makes Git operations persistent, sandboxed, and exportable.

---

## CLI Interface: [`src/git/cli.ts`](https://github.com/cloudflare/computer/blob/main/src/git/cli.ts)

The [`packages/computer/src/git/cli.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/cli.ts) module parses command‑line arguments and dispatches to the appropriate implementation module. When you invoke `workspace.git.clone(...)`, you are calling through this façade:

1. **Parse** – Tokenize arguments (`clone`, `https://...`, `--depth`, `1`)
2. **Validate** – Check required parameters and workspace permissions
3. **Adapt** – Create FS adapter bound to current workspace
4. **Dispatch** – Call [`clone.ts`](https://github.com/cloudflare/computer/blob/main/clone.ts) with configured dependencies
5. **Return** – Resolve with operation result or reject with GitError

---

## Complete Workflow Example

Here's a full sequence showing repository initialization through push:

```typescript
// 1. Clone remote repository
await workspace.git.clone('https://github.com/myorg/project.git', {
  dir: '/workspace/project',
  singleBranch: true
});

// 2. Make changes via workspace.fs
await workspace.fs.write('/workspace/project/config.json', JSON.stringify({
  apiUrl: 'https://api.example.com'
}));

// 3. Stage and commit
await workspace.git.add({ dir: '/workspace/project', filepath: 'config.json' });
await workspace.git.commit({
  dir: '/workspace/project',
  message: 'Add API configuration',
  author: { name: 'Runtime Bot', email: 'bot@computer.cloudflare' }
});

// 4. Push to remote
await workspace.git.push({
  dir: '/workspace/project',
  remote: 'origin',
  ref: 'main'
});

```

Because the VFS persists, subsequent invocations of the Computer runtime can resume work on this repository without re‑cloning.

---

## Summary

- **isomorphic‑git** provides the core Git implementation entirely in JavaScript, eliminating native binary dependencies.
- **Custom FS adapter** ([`src/git/adapter.ts`](https://github.com/cloudflare/computer/blob/main/src/git/adapter.ts)) bridges isomorphic‑git to the Computer workspace VFS for persistent, sandboxed storage.
- **Modular architecture** splits Git concepts across focused modules: [`clone.ts`](https://github.com/cloudflare/computer/blob/main/clone.ts), [`commit.ts`](https://github.com/cloudflare/computer/blob/main/commit.ts), [`network.ts`](https://github.com/cloudflare/computer/blob/main/network.ts), [`staging.ts`](https://github.com/cloudflare/computer/blob/main/staging.ts), [`status.ts`](https://github.com/cloudflare/computer/blob/main/status.ts), [`worktree.ts`](https://github.com/cloudflare/computer/blob/main/worktree.ts), and [`cli.ts`](https://github.com/cloudflare/computer/blob/main/cli.ts).
- **Network operations** use HTTP transport implemented in [`network.ts`](https://github.com/cloudflare/computer/blob/main/network.ts) to support push, pull, and clone over HTTPS.
- **Full CLI surface** via `workspace.git` enables familiar Git workflows from Computer scripts or interactive sessions.

---

## Frequently Asked Questions

### Does Cloudflare Computer require a native Git installation?

No. The Cloudflare Computer implementation uses **isomorphic‑git**, a pure‑JavaScript Git library. All operations run through `workspace.git` using the virtual filesystem—no system Git binary is invoked or required.

### Where is repository data stored?

All repository data lives in the **workspace virtual filesystem (VFS)**. Objects, refs, and the index are written to paths like `/repo/.git/objects` within the VFS. This data persists across Computer runtime invocations and can be exported via `workspace.fs.export`.

### Can I use SSH authentication for Git operations?

The current implementation in [`src/git/network.ts`](https://github.com/cloudflare/computer/blob/main/src/git/network.ts) supports **HTTPS transport** via the Computer runtime's fetch capabilities. SSH authentication would require additional credential handling not present in the core modules analyzed.

### How does `git status` work without a working directory on disk?

The status module ([`src/git/status.ts`](https://github.com/cloudflare/computer/blob/main/src/git/status.ts)) calls `isomorphicGit.status` with the custom FS adapter. The adapter presents the VFS as a standard filesystem, so isomorphic‑git performs its normal index‑to‑worktree comparison against the in‑memory file structures.