Module worktree 

The branch-to-worktree topology: where every linked worktree of a repository belongs, derived from git and from nothing else, and everything that follows from it.

The invariant

<parent>/<repo>                       the primary checkout, which hosts the trunk
<parent>/<repo>-wt/                   the container, derived: parent + name + "-wt"
<parent>/<repo>-wt/<branch name>      the one worktree of every non-trunk branch

The branch name is the relative path: feature/providers/openai-streaming lives at <repo>-wt/feature/providers/openai-streaming, hierarchy preserved, nothing flattened, nothing hashed, nothing registered. Git is the registry: the identity comes from the common git directory, the worktrees from git worktree list --porcelain, the branches from for-each-ref, and this module interprets them into one typed RepositoryTopology that every surface renders.

The architecture

  git (common dir, worktree list, for-each-ref, status)
        ↓
  RepositoryIdentity            primary, current, container, trunk — from anywhere inside
        ↓
  path::expected_path()         container / branch name, proved to stay inside the container
        ↓
  WorktreeService               topology, status, guard, inspect, create, migrate, repair
     ↙      ↓       ↘
   CLI   capability   git hooks → MCP, HTTP, OpenAPI, Swagger, the Cockpit, docs

Every surface is an adapter. Nothing outside this module derives a path, decides a standing, or judges whether a move is safe; a second implementation of any of those is the defect this module exists to prevent.

Safety

Nothing here deletes a directory because its name looks right, and nothing here resets, stashes, cleans or checks out anything. A migration moves a worktree with git worktree move, dirty state included, and proves with a fingerprint::WorktreeFingerprint taken before and after that the branch, the commit, the index, the staged and unstaged changes and the untracked files are the same on the other side. Every mutation holds one repository-scoped lock::WorktreeLock, so two agents cannot half-register one path.

Re-exports

pub use fingerprint::WorktreeFingerprint;

pub use model::Severity;

pub use uncommitted::OpenEpisode;

pub use uncommitted::Threshold;

pub use uncommitted::UncommittedReport;

pub use uncommitted::UncommittedTallies;

pub use uncommitted::UncommittedWorktree;

pub use uncommitted::WorkStanding;

Modules

fingerprint

The proof that a move lost nothing.

state

What git says about the state of a work tree and of every branch: uncommitted work from status --porcelain, and every local branch with its upstream, its distance from it and the work tree holding it from one for-each-ref. Nothing here fetches.

uncommitted

Uncommitted work in the linked work trees, and whether anything still holds it (I1995).

Structs

BranchName

A branch name git would accept for refs/heads/, whose components are therefore safe directory names.

BranchState

One local branch, with or without a work tree.

BranchTrace

One branch that names an issue, with the commits it holds.

CommitAttribution

One commit and the contract it served, or the fact that none can be found.

CommitRef

One commit, exactly as git names it. Nothing here is stored anywhere: the whole record is re-read from the object database on every call.

ContainerView

The container, as the topology reports it.

CreateReport

What a create did.

CreateRequest

What to create.

DirtyState

Uncommitted work in a work tree, counted from git status --porcelain. Untracked content counts: it is exactly what a careless move loses.

GuardVerdict

What the guard decided, for a hook or a mutation that must not proceed out of place.

InspectReport

One branch, inspected: where its work tree belongs and what is there.

IssueTrace

Everything git knows about one issue’s realisation.

MigrationOptions

What an apply may do beyond a rename.

MigrationPlan

A migration, planned or applied.

MigrationStep

One worktree to bring home.

RemoveReport

What a remove did.

RepairReport

What a repair did.

RepositoryIdentity

The repository a command is operating on, and every work tree git has registered for it.

RepositoryTopology

The whole topology: what worktree list, the MCP resource, the HTTP route and the Cockpit all read.

RepositoryView

The repository’s identity, as the topology reports it.

ResolvedPath

A path as git names it and as the filesystem resolves it.

StatusReport

The answer to “where am I, and is that where I belong”.

TopologyDiagnostic

One thing wrong with, or worth knowing about, the topology.

TopologyTallies

How many work trees and branches are in each state.

TraceReport

The whole traceability answer: every issue git can say something about, and every commit of a stretch of the trunk with the contract it served or the fact that it has none.

TraceTallies

The counts of one report.

Tracer

The reader. Opened from anywhere inside the repository; every question is answered by running git again, because the history changes outside this process.

Trunk

The trunk branch and how it was decided. Discovered state, never domain logic: master here is a fact about this repository and main would be one about another.

TrunkView

The trunk, as the topology reports it.

UpstreamState

A branch’s upstream and how far the two have moved apart, from for-each-ref in one subprocess for every branch, never a fetch.

WorktreeLock

The held lock. Dropping it releases it; a panic or an early return therefore cannot leave the repository locked.

WorktreeRecord

One work tree as git registered it.

WorktreeService

The repository’s worktrees, decided once.

WorktreeState

One work tree, as the topology sees it.

Enums

Attribution

What is known about the contract one commit served.

Detail

How much of each work tree’s state a topology reads.

DiagnosticCode

The stable machine name of everything that can be wrong with the topology. One code per condition, reused by the command line, the API, MCP, the Cockpit, the tests and the documentation; the prose beside a code is rendered from the typed state.

EnvrcApproval

What became of the .envrc of a worktree that was just created, found, or moved.

HooksPath

What became of the hooks directory of a worktree that was just created, found or moved.

Integration

How a branch stands to the trunk, which is what decides which commits are its own.

MigrationAction

How a step moves its worktree.

Standing

Where a work tree stands against the topology.

StartPoint

Where a new branch started, and why there.

StepOutcome

What became of a step.

TrunkSource

Where the trunk was learned from, in the order it is looked for.

WorktreeError

Everything that stops a worktree operation.

WorktreeKind

Whether a work tree is the repository’s own checkout or one linked to it.

Constants

CONTAINER_SUFFIX

What is appended to the primary checkout’s directory name to name the container. The one place the convention is written; every path, document and message derives from it.

EXIT_INTERNAL

The exit code when git itself failed, or the topology cannot be read at all.

EXIT_MISSING

The exit code when the thing asked for does not exist.

EXIT_REFUSED

The exit code of a refusal: the operation is well-formed and the state of the tree says no. The executable’s contract already spends 10 on “contract unmet”.

SCHEMA

The schema every topology document carries.

Functions

carry_hooks_path

Bind worktree to the hooks directory of its own tree, when the repository tracks one and git would otherwise run another worktree’s.

container_root

The container of a repository whose primary checkout is primary: the checkout’s sibling, named after it with CONTAINER_SUFFIX appended. Never read from anywhere, never configured.

detached_label

The label a detached worktree is shown under. Display only: a detached HEAD has no branch and therefore no canonical path, and nothing ever moves a worktree under this name.

expected_path

Where the worktree of branch belongs: the branch’s components under the container.

first_merge

The first merge commit of a rev-list --parents --reverse --ancestry-path listing, with its first parent. A listing whose first entry has one parent is a branch that reached the trunk without a merge of its own.

parse_commit

Parse one commit line of FORMAT. A line with fewer fields is not a commit.

parse_issue_refs

The refs of text that name one of ids, local branches first, each remote-tracking ref dropped when a local branch already stands for the same name.

parse_porcelain

Parse porcelain records from attribute lines. The separator is the caller’s: \n for --porcelain, \0 for --porcelain -z. A blank attribute ends a record.

parse_porcelain_nul

The same, from the NUL-separated form, where a path may contain a newline.

Type Aliases

Result

The result of every worktree operation.