> ## Documentation Index
> Fetch the complete documentation index at: https://obversa.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace Example

> Capture, verify, lease and fork a temporary Git repository, then read the child back.

Try the Git workspace provider without touching a repository you care
about: the file makes its own temporary repository, forks a child worktree
from it, checks the child, and deletes both at the end. Use it to see the
whole cycle once before you wire the provider into a run. The API and its
limits are on the [workspace contract](/docs/workspace/contract).

## Run it

Set the project up as [Installation](/docs/get-started/installation) describes
and run the file. It needs Git and nothing else:

```bash Terminal theme={null}
npx tsx workspace.ts
```

```json Output theme={null}
{"revision":"8f90610ab0110e48db8af969bb943a4b35c12d4d","anchor":"429bfc13ff3c6337385d1eea32d580acc7cb1d7cf038d3c8ada19eb28af9fe36","branch":"refs/heads/obversa/example-child"}
```

`revision` is the `HEAD` read from the child worktree, `anchor` the digest
of the captured anchor the lease covered, and `branch` the Git ref of the
child branch.

## The file

```ts examples/workspace.ts theme={null}
import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { createGitWorktreeProvider } from '@obversa/runtime';

const runGit = promisify(execFile);

const root = await mkdtemp(join(tmpdir(), 'obversa-workspace-example-'));
const directory = join(root, 'repository');
try {
  await mkdir(directory);
  await runGit('git', ['init', '-q', '-b', 'main'], { cwd: directory });
  await writeFile(join(directory, 'README.md'), '# workspace\n');
  await runGit('git', ['add', 'README.md'], { cwd: directory });
  await runGit('git', ['-c', 'user.name=Example', '-c', 'user.email=example@example.com', 'commit', '-qm', 'initial'], { cwd: directory });
  const workspace = createGitWorktreeProvider({ repositoryPath: directory });
  const anchor = await workspace.capture();
  const verified = await workspace.verify(anchor);
  if (!verified.ok) throw new Error('workspace changed before fork');
  const lease = await workspace.acquireLease('example', 'workspace-example', anchor);
  if (!lease.ok) throw new Error('lease was not acquired');
  const fork = await workspace.fork(anchor, 'example-child', lease.token);
  await workspace.releaseLease(lease.token);
  if (!fork.ok) throw new Error(`fork failed: ${fork.kind}`);
  const childHead = (await runGit('git', ['rev-parse', 'HEAD'], { cwd: fork.worktreePath })).stdout.trim();
  if (childHead !== anchor.head) throw new Error('child worktree has the wrong revision');
  if (await readFile(join(fork.worktreePath, 'README.md'), 'utf8') !== '# workspace\n') {
    throw new Error('child worktree has the wrong contents');
  }
  const report = { revision: childHead, anchor: lease.anchorDigest, branch: fork.branchRef };
  console.log(JSON.stringify(report));
} finally {
  await rm(root, { recursive: true, force: true });
}
```

The file checks five things, and throws at the first that fails:

1. **Repository.** It creates a Git repository with a committed
   `README.md`.
2. **Anchor.** It captures the repository and verifies the anchor before
   use.
3. **Lease and fork.** It acquires one writer lease and creates a child
   worktree from the captured revision.
4. **Child state.** It reads the child `HEAD` and `README.md`, and throws if
   the revision or the file contents differ from the captured repository.
5. **Cleanup.** A `finally` block removes the temporary root, which holds
   both the repository and its sibling worktree directory.

## Next steps

* [Workspace contract](/docs/workspace/contract): scoped capture, leases, the
  fork failure kinds and where child worktrees live.
* [Workspace](/docs/concepts/workspace): `isolated()`, the step wrapper that
  runs this cycle and lands the work back on pass.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.