git worktree

文章目录

• 1.简介
• 2.格式
• 3.常用选项
• 4.示例
• • [4.1 为现有分支创建 worktree](#4.1 为现有分支创建 worktree)
  • [4.2 创建新分支并同时创建 worktree](#4.2 创建新分支并同时创建 worktree)
  • [4.3 查看所有 worktree](#4.3 查看所有 worktree)
  • [4.4 移除不再需要的 worktree](#4.4 移除不再需要的 worktree)
  • [4.5 锁定 worktree（防止在 `prune` 时被清除）](#4.5 锁定 worktree（防止在 prune 时被清除）)
  • [4.6 清理已删除的 worktree 引用](#4.6 清理已删除的 worktree 引用)
• 5.小结
• 参考文献

1.简介

git worktree 是 Git 提供的多工作区管理命令，允许你一个仓库拥有多个并存的、相互独立的工作目录，每个工作区可以检出不同的分支。

这些目录共享同一个 Git 仓库（即共享 .git 目录），因此你可以在不影响主工作区的情况下，并行处理多个分支的任务。

2.格式

git worktree add [-f] [--detach] [--checkout] [--lock [--reason <string>]]
		 [--orphan] [(-b | -B) <new-branch>] <path> [<commit-ish>]
git worktree list [-v | --porcelain [-z]]
git worktree lock [--reason <string>] <worktree>
git worktree move <worktree> <new-path>
git worktree prune [-n] [-v] [--expire <expire>]
git worktree remove [-f] <worktree>
git worktree repair [<path>...​]
git worktree unlock <worktree>

3.常用选项

选项	说明
add	在指定路径创建一个新的 worktree，并基于指定分支检出代码。
-b <新分支>	结合 add 使用，创建并检出新的分支作为 worktree。
-B <新分支>	类似 -b，但会强制重置已存在的分支。
--detach	让 worktree 处于"分离头指针"状态，不关联任何分支。
list	列出当前所有 worktree 及其路径、分支、提交信息。
--porcelain	以脚本可读的格式输出 list 信息，适合编程解析。
remove	删除指定的 worktree（同时删除对应的目录）。
prune	清理已被删除但仍残留记录的 worktree 引用。
lock / unlock	锁定或解锁 worktree，防止被误删除或 prune。
move	将 worktree 移动到新目录。
repair	修复 worktree 的元数据，例如迁移仓库路径后。

4.示例

4.1 为现有分支创建 worktree

# 为 main 分支创建一个 worktree，存放在 ../project-main 目录
git worktree add ../project-main main

4.2 创建新分支并同时创建 worktree

# 创建新分支 feature/new-dashboard，并以此创建 worktree
git worktree add -b feature/new-dashboard ../project-dashboard main

4.3 查看所有 worktree

git worktree list

输出示例：

/path/to/main-project     abc1234 [main]
/path/to/project-dashboard  def5678 [feature/new-dashboard]

4.4 移除不再需要的 worktree

git worktree remove ../project-feature

4.5 锁定 worktree（防止在 prune 时被清除）

git worktree lock ../project-security --reason "正在进行安全审计"

4.6 清理已删除的 worktree 引用

git worktree prune

5.小结

git worktree 非常适合并行开发、紧急修复、快速切换分支等场景。它与 git clone 不同：所有 worktree 共享同一个 .git 目录，节省磁盘空间，且保持引用一致。

---

参考文献

Git - git-worktree Documentation