Workspace Example

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.

Run it

Set the project up as Installation describes and run the file. It needs Git and nothing else:

Terminal

npx tsx workspace.ts

Output

{"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

examples/workspace.ts

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:

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

Next steps

Workspace contract: scoped capture, leases, the fork failure kinds and where child worktrees live.
Workspace: isolated(), the step wrapper that runs this cycle and lands the work back on pass.

Start

Concepts

Patterns

Examples

Evals and Gates

Recording Runs

Driving Runs

Surfaces and Hosts

Writing Workflow Shapes

Memory

Workspace

Compare

FAQ

API Reference

Workspace Example

Run it

The file

Next steps

​Run it

​The file

​Next steps

Run it

The file

Next steps