git worktree 速查表：所有命令和示例

创建

要做什么	命令
从 main 新建分支	git worktree add -b feat/search ../app-search main
从当前 commit 新建分支	git worktree add -b feat/search ../app-search
检出本地已有分支	git worktree add ../app-login fix/login
只在远端存在的分支	git fetch && git worktree add ../app-pr feat/remote-only
把已有分支重置到新的起点	git worktree add -B feat/search ../app-search origin/main
不建分支（detached HEAD），只是看看	git worktree add --detach ../app-v2 v2.0.0
创建时直接锁定	git worktree add --lock --reason "agent" -b feat/x ../app-x

分支只在一个远端存在时，git 会像 git switch 那样新建一个跟踪它的本地分支。用 -b 时，路径写在起点前面；不用时，路径写在分支名前面。

查看

要做什么	命令
列出所有 worktree	git worktree list
同时显示被锁定和可清理的，以及原因	git worktree list -v
给脚本用的机器可读格式	git worktree list --porcelain
不 cd 就看另一个 worktree 的状态	git -C ../app-search status --short
某个 worktree 里没 push 的 commit	git -C ../app-search log @{upstream}..HEAD --oneline

切换

没有 git worktree switch 这个命令。每个 worktree 就是一个目录，切换就是换目录：cd ../app-search。在另一个 worktree 里执行 git switch feat/search 会报 fatal: 'feat/search' is already used by worktree at '…'，因为一个分支同时只能在一个 worktree 里检出。

维护

要做什么	命令
防止被 prune 和 remove	git worktree lock --reason "在移动硬盘上" ../app-search
解锁	git worktree unlock ../app-search
移动到别的目录	git worktree move ../app-search ~/work/app-search
手动移动仓库后修复关联	git worktree repair

删除

要做什么	命令
删除干净的 worktree	git worktree remove ../app-search
有未提交文件也删（这些文件会丢）	git worktree remove --force ../app-search
清理手动删掉的目录的记录	git worktree prune -v
预览 prune 会做什么	git worktree prune --dry-run -v
之后删除分支	git branch -d feat/search

遇到报错？看如何删除 git worktree 以及常见报错。

有用的设置

• git config worktree.guessRemote true：执行 git worktree add <路径> 不写分支名时，git 会用目录名作为新分支名。开了这个设置后，如果远端有同名分支，就检出它，而不是从 HEAD 新建。
• git config --global fetch.prune true：每次 fetch 时清掉远端已删除的分支，避免过期的 origin/* 和 worktree 堆在一起。

一个省事的命名习惯

把目录建在主目录旁边，并以分支命名：~/code/app、~/code/app-search、~/code/app-fix-login。这样你总知道哪个目录对应哪个分支，编辑器的最近项目列表也一目了然。

worktree 多起来以后，可以交给 Orchard 来管。它列出你 Mac 上所有项目的所有 worktree，显示每个里面有什么没提交、没 push，哪个 AI agent 在哪里工作，以及哪些已经进了 main。

常见问题