git worktree 让同一仓库在多个目录同时检出不同分支,互不干扰、共享 .git 数据库,省去多仓库克隆与频繁切换分支。
一、核心概念
- 主工作树:原仓库目录(含
.git 文件夹)。
- 关联工作树:用
worktree add 创建的额外目录,共享主仓库对象库。
- 限制:同一分支不能同时在多个工作树检出(除非
--force)。
二、常用命令(速查)
# 1. 列出所有工作树
git worktree list [-v]
# 2. 创建工作树(关键)
git worktree add <path> <branch> # 已有分支
git worktree add -b <new-br> <path> <base> # 新建分支+工作树
git worktree add --detach <path> <commit> # 分离头指针(临时)
# 3. 删除工作树
git worktree remove <path> [--force]
# 4. 移动工作树
git worktree move <old-path> <new-path>
# 5. 清理失效记录
git worktree prune
三、场景化示例
1)为已有分支新建工作树
# 在 ../hotfix 目录检出 main 分支
git worktree add ../hotfix main
cd ../hotfix
# 独立修改、提交、推送,不影响原目录
2)新建分支并关联工作树(最常用)
# 基于 main 新建 feature/pay,放在 ../feature-pay
git worktree add -b feature/pay ../feature-pay main
3)基于远程分支创建(推荐)
# 跟踪远程 origin/dev,本地同名分支,目录 ../dev
git worktree add --track -b dev ../dev origin/dev
4)临时检出某个 commit(分离头)
git worktree add --detach ../temp a1b2c3d
5)查看工作树状态
git worktree list
# 输出:路径 + commit + 分支
# /path/main a1b2c3d [main]
# /path/hotfix d4e5f6g [hotfix]
6)删除工作树
# 干净目录直接删
git worktree remove ../hotfix
# 有未提交改动,强制删(谨慎)
git worktree remove --force ../hotfix
7)移动工作树
git worktree move ../feature-pay ../new-feature-pay
四、典型使用场景
- 多分支并行开发:一边写 feature,一边改 bug,互不干扰。
- 紧急修复不中断当前工作:不用 stash,直接开新工作树改 hotfix。
- 多环境并行运行:同时跑
main(生产)、dev(开发)、test(测试)。
- 代码对比/调试:不同分支目录直接对比文件差异。
五、注意事项
- 同一分支不可多检出:默认禁止,防止冲突。
- 共享对象库:所有工作树共用
.git,节省空间,同步快。
- 主工作树不可移动:只能移动关联工作树。
- 手动删目录后要 prune:否则
list 仍显示失效记录。
六、常见错误与解决
fatal: 'xxx' is already checked out:该分支已在其他工作树检出,换分支或删旧工作树。
fatal: working tree has modifications:工作树有改动,先提交或 --force。
要不要我给你一份可直接复制的常用命令速查表(含示例),方便你随时查阅?