tama worktrees list

Reports every linked git worktree under the roots you name, with its branch, head, dirty, locked and prunable state, and mutates nothing.

#Invocation

tama worktrees list [--root <PATH>]... [--json]

#Inputs and options

No other input is accepted, and no argument selects a single worktree: the command reports every linked worktree it finds under the given roots.

#Discovery

The deep repository walk includes ignored dependency and build directories; only Git's .git metadata is pruned. Git supplies the registered worktrees through git -C <repo> worktree list --porcelain. Its first record identifies the primary repository even when the walk reached a linked checkout. Each primary repository is counted once, and its own main checkout is never offered for removal. A worktree is dirty when git status --porcelain reports changes; locked and prunable come from Git's registration.

Only linked worktrees appear — a checkout whose .git is a file holding a gitdir: pointer into <owner>/.git/worktrees/<name>. A second full clone with its own .git directory is a repository copy that no repository owns, so git never lists it and neither does this command (the worktrees group).

#Output document

Under --json, exactly:

{"schemaVersion":1,"roots":[String],"repositories":[{"repository":String,"worktrees":[{"path":String,"branch":String|null,"head":String,"dirty":Boolean,"locked":Boolean,"prunable":Boolean}]}],"worktreeCount":Number,"unreadable":[String],"unreadableDirectories":[{"path":String,"reason":String}]}

roots echoes the roots you passed, in order. repositories carries one entry per owning repository that has at least one linked worktree, and branch is null for a detached head. worktreeCount is the total across every repository, so an empty machine answers "worktreeCount":0 with an empty repositories array. The same document is the answer of tama request worktrees/list with body {"roots":[String]}, the operation Tama Desktop runs (tama request).

unreadable names every candidate the walk found a .git for and git then refused to answer for as a repository. It is reported rather than dropped, because silence would be the pass claiming it read a checkout it never read.

unreadableDirectories names every directory the walk asked the operating system for and did not get, each with the reason it gave — Permission denied, Operation not permitted, No such file or directory. A pass carrying one of these cannot say the roots hold no worktrees, only that it saw none where it could look, so it exits 1 and prints could not read <path>: <reason> to stderr in both output modes. A walk that swallowed that error would return an empty list for a root whose every directory refused to be listed, and that answer would read as proof that the machine holds no second checkouts.

This document carries no excepted array, because list has no --except: that option belongs to tama worktrees remove, which is the only leaf with anything to exempt.

#State effect

None. The command runs git worktree list and git status, both read-only; it never removes, prunes, locks, unlocks or checks out anything. It is the safe first command when a hook has just refused a repository copy.

#Refusal boundary

Passing no --root is a usage error, exit 2:

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

A root that does not exist or cannot be read is reported in unreadableDirectories with the operating system's own reason, and the command exits 1. A repository whose git worktree list fails is reported as the failure it is rather than silently omitted. Otherwise the command exits 0, including when it finds nothing — an empty inventory is an answer, not an error. This leaf has no other refusal: it never asks about dirty or locked state, which is tama worktrees remove's boundary.

Return to the worktrees command group or the complete CLI tree.