git/scratch

Source: src/git/scratch.ts

A working copy with a lifetime: made for one piece of work, and released when that work is done.

worktree.ts holds the primitives; this holds the one shape every caller wants from them. Making a copy, taking its patch and removing it are three calls that only ever happen together, and the order they go in is the whole safety of the thing.

Scratch

type

export type Scratch = {
	/** Where it is. This is what a subagent gets as its working directory. */
	readonly path: string;
	/** The branch it holds. Named after the work, so `git branch` reads. */
	readonly branch: string;
	/** The commit it started from, which its patch is taken against. */
	readonly base: string;
	/**
	 * Takes the patch, then removes the copy and the directory holding it.
	 *
	 * Idempotent, and safe to call in a `finally`: a second call gives back the
	 * patch the first one took, not an empty one, so a caller that releases
	 * explicitly and again in a `finally` cannot lose it. A patch that could not
	 * be taken leaves everything where it is - the caller gets the error and the
	 * work stays on disk, which is the only order these two can go in.
	 */
	release(): Promise<GitResult<string>>;
};

A copy made for one piece of work, and the way to get the work back out.

scratchWorktree

function

export async function scratchWorktree(repo: string, label: string, from?: string): Promise<GitResult<Scratch>> { /* … */ }

A copy of repo for one piece of work, outside the repository.

Outside on purpose: a copy inside the tree its own patch is taken against would show up in that patch. It lives under the system’s temporary directory and is removed by {@link Scratch.release}.

The base is resolved to a commit rather than kept as a branch name, so the patch is against what the work actually started from even if the branch has moved since. from is that commit when the caller has one, a snapshot of the tree as it stands; otherwise it is HEAD.