ait worktree — Complete Reference

ait worktree
ait worktree status
ait worktree restore
ait worktree show
ait worktree path
ait worktree doctor
ait worktree cleanup-candidates
ait worktree cleanup
ait worktree prune-stale
ait worktree list
ait worktree sync
ait worktree recreate
ait worktree recover-task
ait worktree restore-owned-head
ait worktree rebase
ait worktree remove

Inspect and maintain isolated worktrees that share repository .ait authority while carrying their own materialized content, current Line, and optional Task/Change binding. Normal Task worktrees are created by task start. Cleanup, prune-stale, and remove require --yes when applied; use --dry-run to preview destructive removal.

Usage: ait worktree <COMMAND>

Commands:
  status              Compare one checkout with a Line head or exact Snapshot.
  restore             Restore all or selected checkout content from a Line head or Snapshot.
  show                Show one registered worktree and its refreshed live status.
  path                Print one worktree path or a shell command that enters it. [alias: open]
  doctor              Summarize registered worktree health and cleanup classification.
  cleanup-candidates  Inspect policy-selected cleanup candidates without removing them.
  cleanup             Preview or remove policy-selected safe worktrees.
  prune-stale         Preview or prune missing and detached worktree registrations.
  list                List every registered worktree.
  sync                Synchronize one or all worktrees to their selected Line heads.
  recreate            Recreate a missing registered Task worktree.
  recover-task        Recover a local authoring worktree for an existing remote Task and Change.
  restore-owned-head  Restore the last contiguous Snapshot head owned by a bound Task worktree.
  rebase              Replay a worktree's feature delta onto a target base Line.
  remove              Preview or explicitly remove registered worktrees.
  help                Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Report modified, missing, and untracked paths in the selected checkout without restoring content or moving a Line head. NAME selects a registered worktree; when omitted, inspect the current checkout. --snapshot and --line are mutually exclusive, and omission of both compares with the current Line head.

Usage: ait worktree status [OPTIONS] [NAME]

Arguments:
  [NAME]
          Registered worktree name; omit it to inspect the current checkout

Options:
      --snapshot <SNAPSHOT_ID>
          Compare with this exact local Snapshot instead of a Line head

      --line <LINE_NAME>
          Compare with this local Line head instead of the current Line head

      --verbose
          Show baseline and workspace-root detail in text output

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Restore the selected registered worktree, or the current checkout when NAME is omitted. With no source option, restore the whole checkout from its current Line head. --snapshot and --line are mutually exclusive. Every --path is an exact workspace-relative path and requires an explicit --snapshot or --line; selected-path restore does not switch the current Line. Unsaved changes require --force, while --dry-run only reports the restore plan.

Usage: ait worktree restore [OPTIONS] [NAME]

Arguments:
  [NAME]
          Registered worktree name; omit it to restore the current checkout

Options:
      --snapshot <SNAPSHOT_ID>
          Restore from this exact local Snapshot; mutually exclusive with --line

      --line <LINE_NAME>
          Restore from this local Line head; a whole-checkout restore also switches the current Line

      --path <PATH>
          Restore one exact workspace-relative path; repeat for more paths and supply --snapshot or --line

      --force
          Overwrite unsaved changes in the selected restore scope

      --dry-run
          Report writes, removals, and overwritten changes without restoring content

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Show registered and current Line identity, materialized status, Task/Change binding, cleanup classification, and rebase or merge state for one worktree. NAME may be omitted only when the current runtime context resolves a worktree binding.

Usage: ait worktree show [OPTIONS] [NAME]

Arguments:
  [NAME]
          Registered worktree name; omit it to use the current runtime worktree binding

Options:
      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Print the managed alias path when available, otherwise the registered physical path. This command refreshes live status and records worktree use. --shell prints a command that changes directory and exports managed Cargo paths when enabled; the visible alias `open` has identical print-only behavior.

Usage: ait worktree path [OPTIONS] [NAME]

Arguments:
  [NAME]
          Registered worktree name; omit it to use the current runtime worktree binding

Options:
      --shell
          Print a shell command that enters the worktree and exports managed Cargo paths

      --json
          Emit machine-readable path, command, status, and managed runtime fields

  -h, --help
          Print help (see a summary with '-h')

Summarize current, clean, dirty, missing, detached, protected, and cleanup-candidate worktrees. The default uses metadata and cached status without a full content scan. --refresh verifies live content and may refresh derived runtime layout and status caches.

Usage: ait worktree doctor [OPTIONS]

Options:
      --refresh
          Verify each worktree's live content and refresh derived runtime status before reporting

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Refresh and classify registered worktrees without removing paths or registrations. Filter by cleanup policy or idle age, opt clean manual-only worktrees into review, and optionally include protected rows with their exact reasons. Missing or detached registrations remain stale rather than cleanup candidates.

Usage: ait worktree cleanup-candidates [OPTIONS]

Options:
      --older-than <DURATION>
          Idle threshold for after_idle policy, written as integer days, hours, or minutes (for example 7d, 12h, or 30m)
          
          [default: 7d]

      --policy <POLICY>
          Filter by cleanup policy: manual_only, after_remote_land, after_task_complete, after_idle, or never

      --allow-manual-only
          Classify otherwise-safe clean manual_only worktrees as explicit cleanup candidates

      --include-protected
          Include protected worktree rows and their reasons without making them removable

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Select safe cleanup candidates using the same policy rules as cleanup-candidates. --dry-run previews the exact ordered removal plan without requiring confirmation. Applied cleanup deletes selected worktree paths, managed aliases, registrations, and managed Task Cargo build caches and therefore requires --yes.

Usage: ait worktree cleanup [OPTIONS]

Options:
      --older-than <DURATION>
          Idle threshold for after_idle policy, written as integer days, hours, or minutes (for example 7d, 12h, or 30m)
          
          [default: 7d]

      --policy <POLICY>
          Filter by cleanup policy: manual_only, after_remote_land, after_task_complete, after_idle, or never

      --allow-manual-only
          Permit otherwise-safe clean manual_only worktrees to be selected for removal

      --limit <COUNT>
          Remove at most this many ordered candidates

      --dry-run
          Preview the exact ordered removals without changing paths or registrations

      --yes
          Confirm and apply cleanup removal; required unless --dry-run is supplied

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Select registrations whose path is missing or whose worktree runtime layout is detached. Pruning removes stale registration and alias state without deleting surviving checkout content. --dry-run previews the exact rows; applied pruning requires --yes.

Usage: ait worktree prune-stale [OPTIONS]

Options:
      --dry-run
          Preview missing and detached registrations without pruning them

      --yes
          Confirm and apply stale-registration pruning; required unless --dry-run is supplied

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

List registered paths, current Lines, cached workspace status, cleanup classification, and current-context identity. --refresh verifies live content and may refresh derived runtime layout and status caches.

Usage: ait worktree list [OPTIONS]

Options:
      --json
          Emit the complete stable machine-readable JSON array

      --refresh
          Verify live content and refresh derived runtime status for every worktree

  -h, --help
          Print help (see a summary with '-h')

Restore a complete registered worktree to a Line head and update its materialized Snapshot, current Line, and runtime metadata. NAME selects one worktree; --all selects every live worktree and uses each one's current Line. --all cannot be combined with NAME or --line. Dirty content requires --force, and --dry-run previews without applying the restore.

Usage: ait worktree sync [OPTIONS] [NAME]

Arguments:
  [NAME]
          Registered worktree name; omit it to use the current runtime worktree binding

Options:
      --all
          Synchronize every live worktree to its own current Line; cannot be combined with NAME or --line

      --line <LINE_NAME>
          Synchronize one worktree to this Line head and make that Line current

      --force
          Overwrite unsaved changes while synchronizing

      --dry-run
          Preview complete restore plans without synchronizing content or metadata

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Recreate the recorded path and alias of a Task-bound worktree whose registered path is missing. Recovery selects the first locally available current-Line head, fork Snapshot, or selected remote Patchset revision. A present or unbound worktree is rejected; --dry-run validates and reports the candidate without materializing it.

Usage: ait worktree recreate [OPTIONS] [NAME]

Arguments:
  [NAME]
          Missing registered Task worktree name; omit it to use the current runtime binding

Options:
      --dry-run
          Validate recovery candidates, path, and alias without recreating the worktree

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Run from the authoritative repository root to validate an active or draft remote Task and its draft or review Change, then recreate their local feature Line and Task-bound worktree. This command does not create remote Task or Change authority. If a registration already exists but its path is missing, use worktree recreate instead.

Usage: ait worktree recover-task [OPTIONS] --change <CHANGE> <TASK_ID>

Arguments:
  <TASK_ID>
          Existing remote Task ID to recover

Options:
      --change <CHANGE>
          Existing remote Change ID or Task-scoped Change reference

      --remote <REMOTE>
          Configured remote name; omit it to use the effective default remote

      --dry-run
          Validate remote identity, local Snapshots, and placement without creating a worktree

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Inspect first-parent history after the registered fork and retain the last contiguous Snapshot owned by the bound Task, Change, and worktree. Any first foreign Snapshot and its descendants are dropped from the Line head. The worktree must be Task-bound, clean, and outside a conflicted rebase; --dry-run reports the ownership decision without changing content or the head.

Usage: ait worktree restore-owned-head [OPTIONS] [NAME]

Arguments:
  [NAME]
          Task-bound worktree name; omit it to use the current runtime worktree binding

Options:
      --dry-run
          Report the retained owned head and dropped foreign Snapshots without restoring

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Rebase the current feature Line from its registered fork onto --onto or the recorded target base Line. Starting an applied rebase requires a clean worktree. --dry-run previews ancestry, writes, removals, and conflicts. A conflicted rebase must later use exactly one of --continue or --abort; neither continuation mode accepts --dry-run.

Usage: ait worktree rebase [OPTIONS] [NAME]

Arguments:
  [NAME]
          Registered worktree name; omit it to use the current runtime worktree binding

Options:
      --onto <LINE_NAME>
          Target base Line for a new rebase; omit it to use recorded target metadata

      --continue
          Snapshot the resolved conflicted workspace and complete its rebase

      --abort
          Discard conflicted workspace resolution and restore the original head

      --dry-run
          Preview a new rebase plan; cannot be combined with --continue or --abort

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')

Remove one or more named worktree registrations, managed aliases, and runtime identity files, leaving ordinary checkout content unless --delete-path is supplied. --all-stale performs the same stale-registration pruning as prune-stale and cannot be combined with names, --delete-path, or --force. --dry-run previews the exact plan; every applied removal requires --yes.

Usage: ait worktree remove [OPTIONS] [NAME]...

Arguments:
  [NAME]...
          One or more registered worktree names; mutually exclusive with --all-stale

Options:
      --all-stale
          Prune every missing or detached registration; cannot be combined with names, --delete-path, or --force

      --delete-path
          Also delete each physical worktree path and managed Task Cargo build cache

      --force
          Permit explicit removal of dirty worktrees; does not bypass other safety checks

      --dry-run
          Preview exact removals without changing paths, aliases, or registrations

      --yes
          Confirm and apply worktree removal; required unless --dry-run is supplied

      --json
          Emit the complete stable machine-readable JSON payload

  -h, --help
          Print help (see a summary with '-h')