Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tidying

A place lasts as long as its work. flume tidies a place once its work lands or its launch is dropped, and its agent has stopped (teams.1). It removes the worktree, and deletes the branch unless the branch holds work its target lacks.

When a place’s work is over

  • Landed: sluice’s record shows the place’s branch landed on its target.
  • Dropped: the caller dropped the launch, as sounding’s drop does for a sounding, or the operator did.

flume tidies a place when it reads that its work is over, and flume tidy runs the same pass on demand. When flume cannot read whether a place’s work is over, it removes nothing (plan.9).

What flume removes

flume removes only places it made: worktrees directly under <repository>/places/, each on the branch of a launch flume made (plan.9). It never removes:

  • the repository’s main checkout;
  • a worktree made by hand, or by another tool;
  • a locked worktree;
  • a worktree with modified files, or untracked files that are not ignored.

A place kept for one of these reasons stays in status, named with the reason (Status and live state).

Through the repository’s own tool

flume removes a place through the repository’s own worktree tool, such as worktrunk’s wt remove, so the repository’s remove hooks run. Whatever the repository stood up for that worktree goes with it: a database, a dev server, a test service (plan.9). A hook that fails keeps the worktree, and flume names it.

The branch

When the worktree goes, flume judges its branch against its target with git cherry (plan.10):

  • a branch holding a commit whose patch the target lacks is kept and named;
  • a branch holding nothing beyond its target is deleted.

git cherry compares patches, so a commit that reached the target under another id, as a rebase gives it, counts as landed, and a patch found nowhere in the target keeps the branch. A branch kept by mistake costs a deletion by hand; a branch deleted by mistake loses the work.

the worktree Work over landed or dropped, its agent stopped flume made it under places/, on a launch's branch Clean, unlocked no modified or untracked files Removed by the repository's tool, its hooks run if not: still running if not: never touched if not Kept, named in status a hook fails its branch git cherry against its target Kept, named holds a patch its target lacks Deleted holds nothing beyond its target
Each gate that does not hold leaves the place where it is. A place flume made, whose work is over and whose tree is clean, goes through the repository's own tool, and its branch goes only when it holds nothing its target lacks.

A launch dropped part way

A launch dropped before its work lands leaves a branch with the commits its stages made: a construct’s change, a code stage’s work. Tidying keeps that branch and names it, so the work stays reachable until someone deletes the branch by hand.