git/land

Source: src/git/land.ts

Putting the work of several copies back into one tree.

A copy per piece of work hands back a patch each. Two patches that each apply cleanly on their own can still be wrong together: one renames what the other calls, both add the same helper under two names, or the second simply overlaps the first.

So they go in one at a time, and the first that does not fit stops the rest. Which patch broke the landing is then a fact rather than a bisection.

Nothing is undone. A patch that does not fit is refused before it touches anything. What already landed stays landed: rolling back would mean discarding work, and every patch here was expensive to produce. The caller is left with a tree it can read, a list of what went in, and the name of what did not.

land

function

export async function land(
	repo: string,
	landings: readonly Landing[],
	options: { requireCleanTree?: boolean } = {},
): Promise<Landed> { /* … */ }

Applies each patch in turn.

The tree must be clean to start with. Landing onto work somebody else is in the middle of would make “which patch broke this” unanswerable, which is the one question this function exists to answer.

requireCleanTree: false is for the caller that put those changes there itself, which is the only one that can tell them from somebody else’s. A flow lands each block’s copies onto a tree holding what earlier blocks landed: it knows exactly what it is adding to, and refusing it would make a second round of work impossible.

Order matters and is the caller’s: these are applied as given.

Landed

type

export type Landed = {
	/** Labels that went in, in the order they did. */
	applied: string[];
	/** The one that stopped it. Absent when everything went in. */
	rejected?: string;
	/** Everything landed. */
	ok: boolean;
	/** Set if and only if `ok` is false. */
	error?: string;
};

What reached the tree, and what did not.

Landing

type

export type Landing = {
	/** How this patch is named when something goes wrong with it. */
	label: string;
	/** The diff, as the copy gave it back. An empty one is skipped. */
	patch: string;
};

One piece of work, and something to call it in the report.