Git Worktree 使用教程

Git Worktree 使用教程

• [一、什么是 Git Worktree？](#一、什么是 Git Worktree？)
• • 核心优势
• [二、为什么需要 Worktree？](#二、为什么需要 Worktree？)
• • 适用场景
  • 与传统方式对比
• 三、基本用法
• • [3.1 创建 Worktree](#3.1 创建 Worktree)
  • • [语句一：为指定分支创建新的 worktree](#语句一：为指定分支创建新的 worktree)
    • [语句二：创建新分支并建立 worktree](#语句二：创建新分支并建立 worktree)
  • [3.2 查看所有 Worktree](#3.2 查看所有 Worktree)
  • [3.3 删除 Worktree](#3.3 删除 Worktree)
  • • [语句一：删除 worktree（会自动删除关联目录）](#语句一：删除 worktree（会自动删除关联目录）)
    • 语句二：强制删除（即使有未提交的修改）
• 四、高级技巧
• • [4.1 分离 HEAD 状态](#4.1 分离 HEAD 状态)
  • [4.2 与远程分支同步](#4.2 与远程分支同步)
  • [4.3 清理已删除的 Worktree](#4.3 清理已删除的 Worktree)
• 五、实际场景
• • [5.1 场景一：紧急 Bug 修复](#5.1 场景一：紧急 Bug 修复)
  • • 初始状态
    • [Step 1: 创建紧急修复 worktree](#Step 1: 创建紧急修复 worktree)
    • [Step 2: 进入临时 worktree 并启动项目](#Step 2: 进入临时 worktree 并启动项目)
    • [Step 3: 提交修复](#Step 3: 提交修复)
    • [Step 4: 推送修复并合并（可选）](#Step 4: 推送修复并合并（可选）)
    • [Step 5: 切回主 worktree 继续开发](#Step 5: 切回主 worktree 继续开发)
    • [Step 6: 删除临时 worktree](#Step 6: 删除临时 worktree)
  • [5.2 场景二：并行功能开发](#5.2 场景二：并行功能开发)
  • • [Step 1: 创建多个功能 worktree](#Step 1: 创建多个功能 worktree)
    • [Step 2: 同时开发多个功能](#Step 2: 同时开发多个功能)
    • [Step 3: 查看所有 worktree 状态](#Step 3: 查看所有 worktree 状态)
  • [5.3 场景三：代码审查](#5.3 场景三：代码审查)
  • • [Step 1: 为特定提交创建 worktree](#Step 1: 为特定提交创建 worktree)
• 六、目录结构变化总结
• 七、注意事项

一、什么是 Git Worktree？

Git Worktree 是 Git 提供的一个强大功能，允许你同时检出多个分支，每个分支都有独立的工作目录，就像为你的仓库创建了多个"分身"。

核心优势

• 无需切换分支：在不中断当前工作的情况下处理其他任务
• 节省磁盘空间：所有 worktree 共享同一个 .git 目录
• 并行开发：同时处理多个功能或 bug 修复
• 代码审查：在不影响当前工作的情况下查看其他分支的代码

二、为什么需要 Worktree？

适用场景

1. 紧急修复：正在开发新功能时，突然需要修复生产环境的 bug
2. 并行开发：同时开发多个不相关的功能
3. 代码审查：查看同事的代码而不影响当前工作
4. 版本对比：同时打开两个版本的代码进行比较

与传统方式对比

操作	传统方式	Worktree 方式
切换分支	git checkout + git stash	直接进入对应目录
并行开发	需要克隆多个仓库	一个仓库，多个工作区
磁盘空间	每个克隆都是完整副本	共享 .git，节省空间
同步更新	需要分别 pull	所有 worktree 同步更新

三、基本用法

3.1 创建 Worktree

语句一：为指定分支创建新的 worktree

git worktree add ../feature-branch feature/awesome

使用场景：分支已存在时使用

参数解释：

• add：创建新的 worktree
• ../feature-branch：新 worktree 的目录路径（相对于主仓库）
• feature/awesome：要检出的分支名

语句二：创建新分支并建立 worktree

git worktree add -b hotfix ../hotfix-branch

使用场景：需要创建新分支时使用

参数解释：

• add：创建新的 worktree
• -b：创建新分支并检出到 worktree
• hotfix：新创建的分支名
• ../hotfix-branch：新 worktree 的目录路径（相对于主仓库）

3.2 查看所有 Worktree

git worktree list

输出示例：

/path/to/main      abc123 [main]
/path/to/feature   def456 [feature/awesome]
/path/to/hotfix    ghi789 [hotfix]

3.3 删除 Worktree

语句一：删除 worktree（会自动删除关联目录）

git worktree remove ../feature-branch

参数解释：

• remove：删除指定的 worktree
• ../feature-branch：要删除的 worktree 目录路径

语句二：强制删除（即使有未提交的修改）

git worktree remove -f ../feature-branch

参数解释：

• remove：删除指定的 worktree
• -f：强制删除，即使 worktree 中有未提交的修改
• ../feature-branch：要删除的 worktree 目录路径

四、高级技巧

4.1 分离 HEAD 状态

# 为特定提交创建 worktree
git worktree add --detach ../review abc123def

参数解释：

• --detach：创建分离 HEAD 状态的 worktree
• ../review：新 worktree 的目录路径
• abc123def：特定提交的哈希值

这在代码审查时特别有用，可以查看特定提交的代码而不影响其他工作。

4.2 与远程分支同步

# 创建 tracking 远程分支的 worktree
git worktree add --track -b feature/remote ../remote-feature origin/feature/remote

参数解释：

• --track：设置跟踪远程分支
• -b feature/remote：创建并检出新分支
• ../remote-feature：新 worktree 的目录路径
• origin/feature/remote：要跟踪的远程分支

4.3 清理已删除的 Worktree

# 如果手动删除了 worktree 目录，需要清理
git worktree prune

参数解释：

• prune：清理不再存在的 worktree 的引用

五、实际场景

5.1 场景一：紧急 Bug 修复

初始状态

目录结构：

~/code/
└── my-project/          # 主 worktree（唯一工作目录）
    ├── .git/            # 完整Git仓库（含对象、分支等）
    │   ├── objects/      # 存储所有Git对象
    │   ├── refs/         # 分支和标签引用
    │   └── config        # 仓库配置
    ├── src/             # 开发中的代码
    ├── tests/           # 测试文件
    └── package.json     # 项目配置

当前状态：

• 正在 main 分支上开发新功能
• 工作目录中有未提交的修改
• 突然收到紧急 bug 修复请求

Step 1: 创建紧急修复 worktree

命令：

git worktree add -b hotfix/login-bug ../my-project-hotfix main

执行后目录结构：

~/code/
├── my-project/                  # 主 worktree
│   ├──── .git/
│   │   ├── worktrees/          # 新增：存储临时 worktree 元数据
│   │   │    └── my-project-hotfix/  # 对应临时 worktree 的配置
│   │   ├── objects/            # 共享对象库（提交历史等）
│   │   ├── refs/               # 共享分支引用
│   │   └── config
│   ├── src/                     # 主分支的代码（包含未提交修改）
│   ├── tests/
│   └── package.json
└── my-project-hotfix/          # 新增：临时 worktree 目录
    ├── .git                     # 文件：指向主仓库的元数据路径
    │   # 内容示例：gitdir: /home/user/code/my-project/.git/worktrees/my-project-hotfix
    ├── src/                     # 从main分支检出的干净代码副本
    ├── tests/
    └── package.json

状态变化：

• 主 worktree 保持不变，仍有未提交修改
• 新创建了 hotfix/login-bug 分支
• 新 worktree 从 main 分支检出了干净的代码

Step 2: 进入临时 worktree 并启动项目

命令：

cd ../my-project-hotfix

执行后目录结构：

~/code/
├── my-project/
│   └── ... 
└── my-project-hotfix/          # 当前所在目录
    ├── .git
    ├── src/                     # 在此修改代码修复bug
    ├── tests/
    └── package.json

操作：

1. 启动项目 ：在 worktree 中启动项目，复现线上问题

   # 示例：Node.js 项目
   npm install
   npm run dev
   
   # 示例：Java 项目
   mvn clean install
   mvn spring-boot:run
   
   # 示例：Python 项目
   pip install -r requirements.txt
   python app.py

2. 复现问题：在启动的项目中复现线上bug，确认问题现象

3. 调试定位：使用调试工具定位问题根源

4. 修复代码：修复发现的问题

5. 测试验证：运行测试确保修复有效

6. 提交修复

Step 3: 提交修复

命令：

git add src/login.js
git commit -m "修复登录功能的认证 bug"

执行后状态：

• hotfix/login-bug 分支有了新的提交
• 主 worktree 中的 main 分支不受影响

Step 4: 推送修复并合并（可选）

方式一：手动合并（推荐团队使用）

# 1. 推送分支到远程
git push origin hotfix/login-bug

# 2. 在 GitHub/GitLab 上创建 PR 并合并到 main
#    - 打开仓库页面
#    - 点击 "New Pull Request"
#    - 选择 hotfix/login-bug → main
#    - 填写描述，创建PR
#    - 等待审查和合并

方式二：自动合并（适合个人项目）

# 1. 切换到主分支
git checkout main

# 2. 拉取最新代码
git pull origin main

# 3. 合并hotfix分支
git merge hotfix/login-bug

# 4. 推送合并结果
git push origin main

选择建议：

• 团队项目：使用方式一（手动合并），便于代码审查
• 个人项目：使用方式二（自动合并），快速直接
• 紧急修复：根据项目情况选择

Step 5: 切回主 worktree 继续开发

命令：

cd ~/code/my-project

执行后目录结构：

~/code/
├── my-project/                  # 当前所在目录
│   ├── .git/
│   │   ├── worktrees/
│   │   │    └── my-project-hotfix/
│   │   └── ...
│   ├── src/                     # 仍保留之前的未提交修改
│   ├── tests/
│   └── package.json
└── my-project-hotfix/
    └── ...

状态变化：

• 回到主 worktree，之前的未提交修改仍然存在
• 可以继续之前的开发工作

Step 6: 删除临时 worktree

命令：

git worktree remove ../my-project-hotfix

执行后目录结构：

~/code/
└── my-project/                  # 恢复到初始状态
     ├── .git/
    │   ├── worktrees/          # 已清空临时 worktree 元数据
    │   ├── objects/
    │   ├── refs/
    │   └── config
    ├── src/                     # 继续开发中的代码
    ├── tests/
    └── package.json

状态变化：

• 临时 worktree 目录被删除
• 主仓库中的 worktrees 目录被清理
• hotfix/login-bug 分支仍然存在（如果需要可以手动删除）

5.2 场景二：并行功能开发

Step 1: 创建多个功能 worktree

命令：

git worktree add ../feature-auth auth-overhaul
git worktree add ../feature-ui    ui-redesign
git worktree add ../docs-update   update-docs

执行后目录结构：

~/code/
├── my-project/                  # 主 worktree
│   ├── .git/
│   │   ├── worktrees/          # 包含三个 worktree 的元数据
│   │   │    ├── feature-auth/
│   │   │    ├── feature-ui/
│   │   │    └── docs-update/
│   │   └── ...
│   └── ...
├── feature-auth/               # 认证功能开发 worktree
│   ├── .git
│   └── ...
├── feature-ui/                 # UI 重设计 worktree
│   ├── .git
│   └── ...
└── docs-update/                # 文档更新 worktree
    ├── .git
    └── ...

状态变化：

• 创建了三个独立的 worktree
• 每个 worktree 对应不同的分支
• 主仓库的 worktrees 目录记录了所有 worktree 的信息

Step 2: 同时开发多个功能

• 在 feature-auth 目录中开发认证系统
• 在 feature-ui 目录中进行界面重设计
• 在 docs-update 目录中更新文档
• 在主 worktree 中处理核心功能

Step 3: 查看所有 worktree 状态

命令：

git worktree list

输出示例：

~/code/my-project      abc123 [main]
~/code/feature-auth    def456 [auth-overhaul]
~/code/feature-ui      ghi789 [ui-redesign]
~/code/docs-update     jkl012 [update-docs]

5.3 场景三：代码审查

Step 1: 为特定提交创建 worktree

命令：

git worktree add --detach ../review abc123def

执行后目录结构：

~/code/
├── my-project/
│   ├── .git/
│   │   ├── worktrees/
│   │   │    └── review/        # 代码审查 worktree 的元数据
│   │   └── ...
│   └── ...
└── review/                     # 代码审查 worktree
    ├── .git
    └── ...                     # 特定提交的代码

状态变化：

• 创建了一个分离 HEAD 状态的 worktree
• worktree 中的代码是特定提交的快照
• 可以安全地查看和分析代码，不会影响其他分支

六、目录结构变化总结

操作	目录结构变化
初始状态	只有主 worktree 目录
创建 worktree	新增 worktree 目录，主仓库增加 worktrees 子目录
在 worktree 中工作	worktree 目录内容被修改
删除 worktree	worktree 目录被删除，主仓库 worktrees 目录被清理

七、注意事项

1. 目录位置：新的 worktree 必须放在不同的目录，不能是主仓库的子目录
2. 分支限制：同一个分支不能同时被多个 worktree 检出（除非使用 --detach）
3. 性能：所有 worktree 共享同一个 .git 目录，所以创建很快，不占太多空间
4. IDE 支持：大多数现代 IDE（VSCode、IntelliJ）都能很好地处理 worktree

参考文章

【1】Git Worktree 使用教程