Skip to content

One branch, one worktree, at a path derived from git

A branch's worktree is where git says it is, never where somebody chose to put it, and a misplaced one is a diagnostic with a remedy rather than a mystery.

status
feature status: stable
domain
Coordination
on the homepage
featured

What it does

Given the repository and a branch name there is exactly one path, and every surface derives it the same way: majordomus worktree create <branch> makes the branch from the trunk and the worktree at that path, worktree path prints it for a shell to cd into, worktree alone says where the current session is and whether that is where it belongs, and worktree migrate brings a misplaced worktree home with its modified, staged and untracked files intact. Nothing registers a path: git's own common directory, its worktree list and its refs are the registry.

The pre-commit hook asks worktree guard and refuses a feature branch committed from the primary checkout or from a worktree that is not the branch's own. The topology is one capability module, so the same typed answer — every worktree with its standing, every diagnostic with its code and remedy — is on the command line, over MCP and HTTP, and on the Cockpit's worktrees page.

What it does not do

It never deletes a branch, never overwrites a destination that exists, and never moves a detached worktree or a session's scratch checkout unless asked. It does not decide what a branch is for; the issue a branch names is read from its name when it names one.

Why it exists

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

How it works

The capability modules of the executable this feature names, each with the capabilities it composes. The interfaces each one reaches are listed under Interfaces below: they are projections of one declaration, not separate registrations.

Worktree topology worktree behaviorally verified

Where every linked git worktree of this repository belongs and where each one is. The container is the primary checkout's sibling named with `-wt`, the path under it is the branch name with its hierarchy kept, and both are derived from git's own identity — the common directory, the registered worktrees, the branches — never from a registry, a configuration or the current directory. A worktree somewhere else is a typed diagnostic with a remedy; the migration that repairs it is a command-line operation of the same service.

Convergence convergence behaviorally verified

Whether every unit of work in this repository is somewhere another worker could find it. A holding is anything that can hold work — a work tree with uncommitted files, a branch with commits, a stash — and each carries a disposition read from git: integrated (the trunk reaches it), published (a remote-tracking ref reaches it), local_only (committed on this disk and nowhere else) or uncommitted. The last two are at risk: they are invisible to every other worker, and a worker that stops is not a rollback. Measured offline, from this checkout alone; whether a pull request exists for a branch is a question for the forge and is not asked here.

Where it sits

domain
Coordination — Every worker declares the paths it will touch, sees who else is working and where, and hears about a collision before it is committed.
areas of work
coordinationwork-tracking
names
CoordinationContinuity
named by
CoordinationPlanning

Interfaces

Each capability behind it, on every interface it is projected onto. A link goes to this site's reference for that interface; an HTTP route and an MCP tool are answered by a running majordomus serve, not by this site.

The capabilities behind this feature, by interface
capabilitycommand lineHTTPMCP tool
worktree.inspect majordomus worktree inspect GET /api/v1/worktrees/inspect majordomus_worktree_inspect
worktree.migration_plan majordomus worktree migrate GET /api/v1/worktrees/migration majordomus_worktree_migration_plan
worktree.status majordomus worktree status GET /api/v1/worktrees/status majordomus_worktree_status
worktree.topology majordomus worktree topology GET /api/v1/worktrees majordomus_worktrees
worktree.trunk majordomus worktree trunk GET /api/v1/worktrees/trunk majordomus_worktree_trunk
worktree.uncommitted majordomus worktree uncommitted GET /api/v1/worktrees/uncommitted majordomus_worktree_uncommitted
convergence.report majordomus convergence GET /api/v1/convergence majordomus_convergence
in the Cockpit, of a running server
/cockpit/worktrees Worktrees

Evidence

What is guaranteed

Each claim this feature names, with the status its row declares, the verdict the recorded runs support, and the test that settles it.

Executable use cases

The rules that hold it

  • blocking A branch's worktree is at <repo>-wt/<branch>, derived from git, never registeredproject.worktree-topology
  • blocking Nothing this repository commits names a path of the machine it was written onproject.no-machine-paths

The decisions behind it

Using it

From the executable's command line

The synopsis of each, as the executable's own help prints it.

  • majordomus worktree status [OPTIONS]

    Where this call is — branch, worktree, canonical or not, uncommitted work — and how many errors the whole topology carries; exit 10 when this worktree is out of place

  • majordomus worktree topology [OPTIONS]

    The whole topology: repository, container, trunk, every worktree, every branch without a worktree, every diagnostic; exit 10 when it has an error

  • majordomus worktree inspect [OPTIONS] <BRANCH>

    One branch: its canonical path, whether it exists, what occupies the path, the worktree holding it, and what stands in the way

  • majordomus worktree migrate [OPTIONS]

    Bring every misplaced worktree to its canonical path, dirty state included, with a fingerprint taken before and after each move; --plan shows the steps and changes nothing

  • majordomus worktree uncommitted [OPTIONS]

    Every linked worktree holding uncommitted work: how many paths, how old the oldest change, what holds it (an active task, an open episode, a process inside) and whether it is abandoned, with the command that would put it on a remote ref. Reads every worktree and writes none

  • majordomus worktree trunk [OPTIONS]

    How far this checkout and the local trunk are from the remote trunk, as of the last fetch, judged against the policy's checkout.trunk_distance: current, lagging, stale, unjudged or unmeasured, with the commands that bring it current. Fetches nothing; exit 10 when stale

  • majordomus convergence [OPTIONS]

    Is any of this repository's work held where it can be lost? Every holding — a work tree with uncommitted files, a branch with commits, a stash — with the disposition read from git, and one verdict over them

Where this page comes from

the file
.ai/repo/features/worktrees.md
the same answer
majordomus product show worktrees
read further

Worktrees

Searches the titles and descriptions of every page this site publishes.