文档站点

主题

2026-05-19
1152
4.7m

git-worktree 工作树 ​

git worktree 是 Git 官方提供的多分支并行工作神器，核心作用：不用频繁切换分支，同时在多个独立目录里操作不同分支，适合同时开发多个功能、修复紧急 bug、对比分支代码。

worktree 相当于可以在一个仓库中切换出多个分支(同一个分支只能切一次)

在不同的分支中(worktree)执行git命令返回的数据相同，体验就和在一个仓库中是一样的，可以同时打开多个分支编辑

前置准备 ​

先创建一个测试仓库

bash
# 1. 创建测试文件夹并初始化Git
mkdir git-worktree-demo && cd git-worktree-demo
git init

# 2. 创建一个初始文件并提交
echo "main分支初始代码" > README.md
git add .
git commit -m "init: 初始化项目"

常规操作 ​

2.1. 查看当前工作树（基础查询） ​

bash
git worktree list
  • 作用：查看所有已创建的工作树、对应分支、路径
  • 初始状态：只会显示主仓库（默认分支：main/master）

2.2. 创建新工作树 ​

语法 ​

分支不存在 → 必须加 -b，分支已存在 → 直接关联分支名

bash
git worktree add <目录名> <分支名>

示例 1：基于现有分支创建

bash
# 创建目录 feature-login，绑定 feature-login 分支
git worktree add feature-login -b feature-login #当前仓库中没有这个分支名
git worktree add feature-login feature-login #分支名称已经存在

执行后效果：

  • 自动生成 feature-login 独立文件夹
  • 该文件夹直接对应 feature-login 分支，和主仓库完全隔离

CAUTION

  1. 只能worktree同一个分支，绑定一个目录

    bash
    $ git worktree add feature-login feature-login
Preparing worktree (checking out 'feature-login')
fatal: 'feature-login' is already checked out at '/code/temp/feature-log'

  2. worktree可以创建在任意磁盘位置

    bash
    $ git worktree add ../feature-log feature-login # 创建和当前项目同级的
$ git worktree add /code/path/feature-log feature-login #也可以指定目录
$ git worktree list
/code/temp/git-worktree-demo  b0f3b89 [master]
/code/temp/feature-log        b0f3b89 [feature-login] #和主项目同级

  3. 在worktree的任意仓库中都可以执行完整的git命令，返回都是一样的

2.3. 进入工作树正常开发 ​

创建后直接进入目录，和普通 Git 仓库一样操作：

bash
cd feature-login
echo "登录功能代码" > login.js
git add .
git commit -m "feat: 完成登录功能"

2.4.代码合并 ​

worktree的代码合并和使用分支合并是一样的，使用merge或rebase。claude code等工具使用的是 rebase

管理工作树 ​

3.1. 锁定工作树（防止误删） ​

如果工作树很重要，防止被意外删除：

CAUTION

git worktree lock 只能防 git worktree remove，完全防不住 rm -rf！

bash
# 锁定 feature-login 工作树
git worktree lock feature-login

# 查看锁定状态（list会显示 locked）
git worktree list

3.2. 解锁工作树 ​

bash
git worktree unlock feature-login

3.3. 删除工作树（2 种方式） ​

方式 1：安全删除（推荐，Git 自动清理）

bash
# 先退出工作树目录，再执行删除
cd ..
git worktree remove feature-login

方式 2：手动删除文件夹 + 清理

bash
# 先手动删文件夹
rm -rf bugfix-pay

# 再让Git清理无效工作树
git worktree prune

3.4. 移动 / 重命名工作树 ​

bash
git worktree move <旧目录> <新目录>

# 示例：把 feature-login 重命名为 feature-user-login
git worktree move feature-login feature-user-login

高级用法 ​

4.1. 基于任意提交 / 标签创建工作树 ​

不用新建分支，直接基于历史版本调试：

bash
# 基于某次commit创建临时工作树
git worktree add temp-debug 提交哈希值

# 基于标签创建工作树
git worktree add v1.0-fix v1.0

4.2. 裸仓库 + worktree（服务器 / 多项目部署专用） ​

适合服务器上只存代码，不保留工作区：

bash
# 1. 创建裸仓库
git clone --bare 仓库地址 project.git

# 2. 为不同环境创建工作树
cd project.git
git worktree add ../prod main        # 生产环境
git worktree add ../test develop     # 测试环境

✅ 一个裸仓库，同时维护生产 / 测试代码，无冗余文件

4.3. 批量管理工作树脚本 ​

bash
# 一次性查看+统计所有工作树
git worktree list | wc -l

完整命令速查表 ​

命令作用
git worktree list查看所有工作树
git worktree add <目录> <分支>创建工作树
git worktree add <目录> -b <新分支>创建新分支 + 工作树
git worktree lock <目录>锁定工作树
git worktree unlock <目录>解锁工作树
git worktree remove <目录>删除工作树
git worktree prune清理无效工作树
git worktree move <旧> <新>移动 / 重命名工作树
最近更新