Git worktree

matcha worktree 管理这些检出。它不会开启对话。/fork 复制对话；只有你要求时才会创建 worktree。

什么时候用 worktree

两个会话（或父助手与子助手）会同时改文件时，用 worktree：

• 一个会话实现功能，另一个留在 main。
• 实验失败也不会弄脏你还开着的目录。
• 工作可用时，像普通分支一样 merge 或 cherry-pick。

只需要第二段对话、文件还是同一批，不带 worktree 的 /fork 就够了——也更省。

在 worktree 里开会话

在欢迎屏（且在 git 仓库里）按 Ctrl+W，打开 New Worktree 对话框，给检出起名，然后从那里开始。

在 TUI 任意处连按两次 Ctrl+N 确认新会话，再选 worktree 选项。

在 shell 里传 --worktree 时要用 =。没有 =，clap 会把下一个词当成 worktree 名，提示就丢了：

matcha --worktree=my-feature "refactor the auth module"

--worktree / -w 也可以当裸标志用（由 Matcha 给检出起名）。--worktree-ref / --ref 把基点钉到分支、标签或提交；默认是源检出当前的 HEAD。

在新的 worktree 里恢复已有会话：

matcha -w -r <session-id>

`/fork` 与 worktree 会话

带 --worktree 的分叉两者都有：复制的历史，加上隔离检出。见分叉会话。

子助手也可以设 isolation: worktree，让子会话改一份私有检出。那仍是当前会话的子级，不是看板上的对等会话。见子助手与角色。

管理检出：`matcha worktree`

这些子命令对着 Matcha 的 worktree 登记表说话。它们不会打开 TUI。

matcha worktree list              # alias: ls
matcha worktree list --json
matcha worktree list --repo <name>
matcha worktree list --type session,fork,subagent
matcha worktree list --all

matcha worktree show <id-or-path>

matcha worktree rm <id-or-path> […]
matcha worktree rm --dry-run <id-or-path>
matcha worktree rm -f <id-or-path>    # force

matcha worktree gc                    # alias: prune
matcha worktree gc --max-age 7d --dry-run
matcha worktree gc --max-age 7d       # then without --dry-run

matcha worktree db stats
matcha worktree db path
matcha worktree db rebuild

--type 按登记种类过滤，例如 session、fork、subagent、manual、ab 和 pool。

没有 --max-age 的 gc 不会过期任何东西。它只访问登记表跟踪的 worktree。未跟踪的目录（matcha du 显示为 untracked）永远不会被 gc；先 --dry-run，再用 matcha worktree rm 删。gc 和 rm 都不会检查未提交或未推送的改动——先读预览。

~/.matcha 的磁盘占用（含 worktree）用 matcha du / matcha disk-usage。worktree 克隆可以与源共享存储，所以报出的总量可能大于实际占用。

配置提示

[hints] fork_worktree_mode 和 [hints] new_session_worktree_mode 控制 /fork 和 /new 要不要问 worktree（ask、always、never）。旧键是 [hints] worktree_mode。这些键未设置时，/fork 默认 **ask**；/new 默认 **never**（不弹窗）。

本构建没有

matcha workspace 是隐藏的 CLI，不是 worktree 管理器。workspace_hub_exposure 已关闭。改用本机会话、/dashboard 和 matcha worktree。不要用仅供测试的环境变量去打开 hub。