# How to Use the Built-In Git Client with isomorphic-git for Workspace Repositories

> Learn how to use the built-in git client with isomorphic-git for workspace repositories. Perform Git operations directly on the virtual filesystem without external binaries.

- Repository: [Cloudflare/computer](https://github.com/cloudflare/computer)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Cloudflare Computer bundles isomorphic-git as a built-in client that operates directly on the workspace's virtual filesystem, enabling Git operations without external binaries.**

The `cloudflare/computer` repository ships with a lightweight Git client built on top of isomorphic-git that is automatically available on every `Workspace` instance. This client allows you to perform version control operations—such as cloning, committing, and diffing—directly within the workspace's SQLite-backed virtual filesystem, regardless of whether your runtime uses container FUSE, isolate-shell, or isolate-JS backends.

## Where the Git Client Lives in the Source

The built-in Git client is implemented across several TypeScript files in the `packages/computer/src` directory:

- **[`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts)** – The `Workspace` class holds a `gitClient` field and lazily instantiates the client via dynamic import of `isomorphic-git`. It passes the `VirtualFileSystem` so that Git operations work directly on the workspace's in-memory filesystem.
- **[`packages/computer/src/git/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/index.ts)** – Defines the `IsomorphicGitCache` object that is shared across all Git calls to store pack-file indexes and other expensive structures.
- **[`packages/computer/src/git/init.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/init.ts)** – Exports `initWith()`, the wrapper used when initializing a new repository.
- **[`packages/computer/src/git/status.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/status.ts)** – Exports `statusMatrix()`, which mirrors the isomorphic-git status API.
- **[`packages/computer/src/git/diff.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/diff.ts)** – Exports `diffWith()` for generating patches between commits or the working tree.
- **[`packages/computer/src/git/commit.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/commit.ts)** – Exports `commitWith()` for creating new commits.
- **[`packages/computer/src/git/clone.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/clone.ts)** – Exports `cloneWith()` for fetching remote repositories.
- **[`packages/computer/src/git/pako-zlib-shim.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/pako-zlib-shim.ts)** – Supplies a minimal `pako` implementation required by isomorphic-git when running in the Workers runtime.
- **[`packages/computer/src/git/network.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/network.ts)** – Defines the authentication shape expected by `isomorphic-git/http/web` and forwards HTTP-basic credentials.
- **[`packages/computer/src/git/errors.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/errors.ts)** – Normalizes isomorphic-git errors into the project's `GitError` hierarchy.

## How the Built-In Client Works

### Lazy Dynamic Imports

When you first access Git functionality on a `Workspace` instance, [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts) executes `await import('isomorphic-git')`. This dynamic import keeps the initial bundle size small for workers that never need Git operations.

### Virtual Filesystem Binding

The client binds to the **virtual filesystem** (`VirtualFileSystem`) that backs the workspace. Because isomorphic-git accepts any Node.js `fs`-compatible API, the same Git operations run identically across container FUSE mounts, isolate-shell environments, and pure-JS workers. Any changes made through the Git API instantly appear in the workspace file view, and vice versa.

### Shared Cache Strategy

Every Git call receives the same `IsomorphicGitCache` instance created in [`packages/computer/src/git/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/index.ts). This cache holds the pack-file index and other computed structures, making repeated `status` and `diff` calls inexpensive.

### Error Translation

Errors thrown by the underlying isomorphic-git library are caught in [`packages/computer/src/git/errors.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/errors.ts) and converted into the project's own `GitError` types, providing consistent error handling across the Computer stack.

## Using the Git Client in Practice

The `Workspace` object exposes a `git` property that delegates to the wrappers in `packages/computer/src/git/`. Below are runnable examples assuming you have a `Workspace` instance named `ws`.

### Initializing a Repository

To create a new Git repository inside the workspace:

```typescript
// Creates a .git directory using the wrapper in git/init.ts
await ws.git.init();

// Write a file using the virtual filesystem
await ws.fs.writeFile('README.md', '# Hello\n');

// Stage and commit using the wrappers in git/commit.ts
await ws.git.add(['README.md']);
await ws.git.commit({
  message: 'Initial commit',
  author: { name: 'Alice', email: 'alice@example.com' },
});

```

### Checking Repository Status

Retrieve a status matrix identical to `isomorphic-git`'s output:

```typescript
// Delegates to statusMatrix() in git/status.ts
const status = await ws.git.statusMatrix();
for (const [path, head, stage, workdir] of status) {
  console.log(`${head ? '✓' : ' '} ${path}`);
}

```

### Generating Diffs

Compute patches between HEAD and the working tree:

```typescript
// Uses diffWith() from git/diff.ts
const diffs = await ws.git.diffWith({});
for (const d of diffs) {
  console.log(`--- ${d.path}`);
  console.log(d.patch);
}

```

### Cloning Remote Repositories

Fetch a remote repository into the workspace:

```typescript
// Uses cloneWith() from git/clone.ts
await ws.git.cloneWith({
  url: 'https://github.com/example/repo.git',
  ref: 'main',      // branch or tag to checkout
  depth: 1,         // shallow clone for speed
});

```

### Pushing Changes

Push commits back to a remote using HTTP basic authentication:

```typescript
// Authentication handled via network.ts
await ws.git.push({
  remote: 'origin',
  url: 'https://github.com/example/repo.git',
  auth: { 
    username: 'x-token-auth', 
    password: process.env.GH_TOKEN! 
  },
});

```

## Summary

- The **built-in Git client** in `cloudflare/computer` is built on isomorphic-git and exposed via the `Workspace` class in [`packages/computer/src/workspace.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/workspace.ts).
- It operates directly on the **virtual filesystem**, making it runtime-agnostic across container and isolate backends.
- The client uses **lazy dynamic imports** to minimize bundle size, loading isomorphic-git only when Git methods are first called.
- An **`IsomorphicGitCache`** shared across calls in [`packages/computer/src/git/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/index.ts) ensures repeated operations remain performant.
- All Git errors are normalized in [`packages/computer/src/git/errors.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/errors.ts) to provide consistent exception handling.
- You can perform standard workflows—init, status, diff, commit, clone, and push—through the `ws.git` API without external Git binaries.

## Frequently Asked Questions

### Which runtimes support the built-in Git client?

The Git client works across all Computer backends: **container FUSE**, **isolate-shell**, and **isolate-JS**. Because it relies on isomorphic-git operating against the virtual filesystem abstraction rather than shelling out to a binary, it functions identically in environments with or without a traditional file system.

### How does authentication work for private repositories?

Authentication is handled in [`packages/computer/src/git/network.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/network.ts), which forwards HTTP-basic credentials to `isomorphic-git/http/web`. When cloning or pushing, pass an `auth` object containing `username` and `password` (or token) to the respective method, and the network layer will include these in the request headers.

### Can I use standard git commands instead of the JavaScript API?

No. The built-in client does not shell out to a system `git` binary. Instead, it uses the pure-JavaScript isomorphic-git implementation. This design ensures compatibility with the Workers runtime and allows Git operations to work on the virtual filesystem, but it means only the operations exposed by the `ws.git` API (and the underlying `*With` wrappers) are available.

### How does the client handle large pack files?

Large pack files are managed through the **`IsomorphicGitCache`** defined in [`packages/computer/src/git/index.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/index.ts). This cache stores pack indexes and other expensive structures in memory, while the actual pack data resides on the virtual filesystem. Additionally, [`packages/computer/src/git/pako-zlib-shim.ts`](https://github.com/cloudflare/computer/blob/main/packages/computer/src/git/pako-zlib-shim.ts) provides the necessary zlib compression routines required by isomorphic-git to process pack files within the Workers environment.