TTama
Docs/CLI reference

CLI reference

tama worktrees

Opens the command group that reports and removes the linked git worktrees under roots you name, because a linked worktree is a second checkout of a repository you already have.

Opens the command group that reports and removes the linked git worktrees under roots you name, because a linked worktree is a second checkout of a repository you already have.

#Invocation

tama worktrees <command>

Commands:
  list   [--root <PATH>]... [--json]                                          Every linked git worktree under the roots
  remove [--root <PATH>]... [--except <PATH>]... [--apply] [--force] [--json]  Remove them; previews unless --apply

<command> is required and must be one of the two linked leaves below.

#Command tree

#--except is a remove option only

--except is repeatable and takes the path of one linked worktree to leave completely alone: it is not removed, it is not counted as removable, and it never produces a refusal. It exists because the refusal is the whole pass — on the machine it was written for, 39 worktrees could not be removed because a fortieth was being written by a live agent session, and root selection could not separate them because a root selects owning repositories. An --except value that matches no worktree the pass would otherwise consider is a usage error, exit 2, so a mistyped path cannot silently remove the thing it meant to keep.

list has no --except. It removes nothing, so it has nothing to exempt, and only the remove document carries the excepted array.

#--root has no default, deliberately

--root is repeatable and required at least once on both leaves. There is no machine-wide default and no implicit home-directory scan. Omitting it is a usage error, not a full-machine walk:

tama worktrees needs at least one --root; a machine-wide default would walk directories Tama does not own.

The reason is scope, not caution for its own sake. A default root would have to be your home directory, and a home directory contains checkouts Tama did not install, was never pointed at, and must not enumerate — on the machine this command was written for, one project tree alone holds 519 GB across sub-trees of 72 GB, 68 GB, 50 GB and 47 GB, and one agent scratch root (~/.stado/work) holds 1568 entries and 178 GB. Walking that by default would make a read-only inventory command a device-wide filesystem scan, and it would make remove --apply a device-wide deletion command. You name the roots; Tama stays inside them.

#A linked worktree, not a repository copy

These two look alike in a file browser and are not the same object:

  • A linked worktree is a checkout whose .git is a file holding a gitdir: pointer into the owning repository's .git/worktrees/<name> directory. Git manages it, so git can list and remove it.
  • A repository copy is a second full clone with its own .git directory. No repository owns it, so no git worktree command knows about it.

The first kind looks like this:

$ cat Wisent/.worktrees/<name>/.git
gitdir: ~/Documents/CodingProjects/Wisent/<repo>/.git/worktrees/<name>

and the second kind, a full .git directory rather than a file. tama worktrees handles the first kind, because that is the noun git itself manages; the second is tama copies's, which finds it by walking the tree and proves its history exists elsewhere before deleting it. Both kinds are refused at creation time by the block-repository-copies hook, whose three refusal sentences are in the runbook.

#Discovery and authority

tama_violations::repo_discovery's discover_repos(root) finds the owning repositories under each root. Git is then the authority on worktrees: git -C <repo> worktree list --porcelain. The repository's own main worktree is never reported and never removed. A worktree is dirty when git -C <worktree> status --porcelain prints anything.

#Output and state

The group itself performs no action and takes no options. list and a bare remove mutate nothing; only remove --apply deletes anything. Both leaves print a text report by default and an exact JSON document under --json, and both are also answered by tama request worktrees/list and tama request worktrees/remove (tama request).

#Refusals and failures

Exit 0 is success, exit 1 is an operational failure or a refusal, and exit 2 is a usage error — a missing or unknown leaf, or a leaf invoked without --root. Each leaf page carries its own exact refusal sentences.

Return to the complete CLI command tree.