Git 裸库 + worktree 教程:一个仓库检出多个目录
同一个 Git 仓库常常需要在多个目录同时检出不同分支:一个现场一个目录,或者一个分支一个目录。常见做法是每个目录 git clone 一次,代价是每个目录都存一份完整历史,彼此不互通,新建一个就要重新下载一遍。
用“裸库 + worktree”可以做到:历史只存一份,多个目录共享,新建目录不再 clone。这篇教程讲三件事:怎么从已有目录再开一个 worktree,裸库怎么建出来,以及怎么让 agent 把一整个目录的仓库批量转成这种结构。
先记住三件事
裸库:只有历史和配置、没有工作文件的仓库目录。通常以 .git 结尾,例如 .bare/app-api.git。它长这样:
.bare/app-api.git/
├── HEAD
├── config
├── objects/
├── refs/
├── hooks/
├── info/
├── logs/
└── worktrees/
没有项目源码。git --git-dir=/path/projects/.bare/app-api.git rev-parse --is-bare-repository 输出 true。
worktree:同一个仓库的另一个检出目录。每个 worktree 有自己的工作文件和当前分支,共用裸库里的对象和分支。项目目录里的 .git 不再是目录,而是一个文件,内容是指向裸库管理目录的路径:
gitdir: /path/projects/.bare/app-api.git/worktrees/app-api
新建目录不是 clone:git clone 会再下载一份历史;git worktree add 只是在共享仓库里多开一个检出目录。
一、从已有目录新建一个 worktree
下面以从项目A 的 app-api 新建项目B 的 app-api-b 为例(同一个仓库的两个检出目录)。路径、分支名换成你自己的。
所有命令在同一个终端里逐条执行,变量才会一直保留。需要 Git 2.22 以上(worktree 从 2.5 开始提供,branch --show-current 要 2.22)。
第 1 步:设两个路径变量
src=/path/projects/项目A/code/app-api
dst=/path/projects/项目B/code/app-api-b
确认一下:
echo "$src"
echo "$dst"
应该输出两个完整路径。git -C 路径 的意思是“在指定目录里执行 git”,不用先 cd。
第 2 步:确认源目录当前分支
git -C "$src" branch --show-current
应该输出:
feature/a
如果输出别的分支,先停下,确认要从哪条分支建项目B。
第 3 步:建目标父目录
mkdir -p "$(dirname "$dst")"
-p 的意思是父目录不存在就一起建,已经存在也不报错。这条命令没有输出。
确认:
ls -ld "$(dirname "$dst")"
应该看到一个目录。
第 4 步:新建分支并创建 worktree
git -C "$src" worktree add -b feature/b "$dst" feature/a
三个参数的含义:
-b feature/b:新建一条本地分支"$dst":新目录feature/a:新分支从源目录当前提交开始
应该看到类似:
Preparing worktree (new branch 'feature/b')
HEAD is now at 74c6ec5d2 docs: 补充项目B部署文档
为什么不能直接用 feature/a:同一个分支不能在两个 worktree 同时检出。源目录已经检出了它,所以新目录要新建一条分支。
第 5 步:看新目录和 .git
ls -la "$dst"
cat "$dst/.git"
新目录里有项目文件,.git 是一个文件,内容类似:
gitdir: /path/projects/.bare/app-api.git/worktrees/app-api-b
它不是目录,只是指向共享裸库里的管理目录。
第 6 步:先看一个“坑”
git -C "$dst" rev-parse --is-bare-repository
如果源目录属于共享裸库,这里很可能输出:
true
这是正常的,不是建错了。先确认共享裸库开了“每个 worktree 读自己的配置”($src 是同一个共享仓库的 worktree,读到的是共享配置):
git -C "$src" config --get extensions.worktreeConfig
- 输出
true:新 worktree 还没有自己的config.worktree,于是继承了裸库的core.bare=true,下一步修。 - 输出为空:没有开启这个机制,
is-bare正常就是false,直接跳到第 8 步。
第 7 步:复制源目录的 worktree 配置
先让 Git 告诉你两个配置文件的路径:
src_cfg=$(git -C "$src" rev-parse --git-path config.worktree)
dst_cfg=$(git -C "$dst" rev-parse --git-path config.worktree)
echo "$src_cfg"
echo "$dst_cfg"
然后复制:
cp "$src_cfg" "$dst_cfg"
源目录的 config.worktree 里通常有 core.bare=false、core.autocrlf=input、core.filemode=true 这些设置,复制过来最省事。
如果 cp 报找不到文件,说明源目录没有 config.worktree,写一个最小的也能用:
printf '[core]\n\tbare = false\n' > "$dst_cfg"
core.bare=false 是必须的;源目录还设置了 core.autocrlf、core.filemode 时,新目录也要补成一样的值(用 git -C "$src" config --get core.autocrlf 查源目录的值),否则换行或可执行位会被当成改动,git status 会多出一堆修改。
可以看一眼:
cat "$dst_cfg"
应该能看到:
[core]
bare = false
...
第 8 步:验证
git -C "$dst" rev-parse --is-bare-repository
现在应该输出:
false
再看状态和最新提交:
git -C "$dst" status --short --branch
git -C "$dst" log -1 --oneline
应该看到:
## feature/b
74c6ec5d2 docs: 补充项目B部署文档
如果 status 报 fatal: this operation must be run in a work tree,说明第 7 步没复制成功,回到第 7 步检查路径。
第 9 步:看同组所有 worktree
git -C "$dst" -c core.quotePath=false worktree list
你会看到裸库本身和这一组的所有 worktree,项目B 那行后面是 [feature/b]。第一行是裸库,它可能显示 (bare),也可能显示某个分支名,取决于裸库的 HEAD 指向哪里,两种情况都正常。
-c core.quotePath=false 只是让中文路径显示成正常汉字,不加也能用。
第 10 步:可选,设置上游分支
如果远端已经有 feature/b,可以设置跟踪:
git -C "$dst" branch --set-upstream-to=origin/feature/b feature/b
远端没有这条分支就不用执行,也不要为了这个去 push。
二、建错了怎么撤回
先确认新目录里没有你要保留的改动,然后:
git -C "$src" worktree remove "$dst"
git -C "$src" branch -d feature/b
如果目录里有未提交改动或未跟踪文件,worktree remove 会拒绝;分支没合并、或者还被裸库的 HEAD 指着时,branch -d 也会拒绝。不要随便加 --force 或 -D,那会丢改动。
三、常见报错
fatal: '<dst>' already exists:目标目录已经存在。先看里面有没有内容,不要直接删。fatal: a branch named 'feature/b' already exists:分支已存在。去掉-b feature/b,改成git -C "$src" worktree add "$dst" feature/b;如果这条分支已经被别的 worktree 检出,Git 会拒绝。fatal: invalid reference: feature/a:起始分支名不对,回到第 2 步确认。cp: cannot stat ...:源目录没有config.worktree(按第 7 步写一个最小的),或者src_cfg路径不对(echo "$src_cfg"看它指向哪里)。status报fatal: this operation must be run in a work tree:第 7 步的配置没复制成功。
四、裸库是怎么建出来的
裸库不是把某个项目的 .git 改个名,而是新建一个只有历史、没有工作文件的仓库,再把各个克隆的历史导进去。
情况 A:只有一个干净克隆
最简单,先把地址和路径放进变量:
origin=git@example.com:team/app-api.git
bare=/path/projects/.bare/app-api.git
git clone --bare "$origin" "$bare"
git clone --bare 会把远端的分支和对象复制过去,并设置 core.bare=true。
clone --bare 只设置 remote.origin.url,不会设置从远端更新分支的 refspec。后面要用这个裸库 git fetch 拉新提交的话,补一条:
git --git-dir="$bare" config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
如果是从一个本地克隆做:
git clone --bare /path/to/你的克隆 "$bare"
git --git-dir="$bare" remote set-url origin "$origin"
注意:
clone --bare只带提交历史、分支、标签,不带未提交修改、未跟踪文件、stash。这些留在原目录,后面转 worktree 时保留。- 如果其他克隆还有本地分支或未推送提交,
clone --bare这一个克隆是看不到的。
情况 B:同一个 origin 有多个克隆
一个远端仓库被克隆了十几份、各自检出一条分支时,要逐个导入。
1. 建空裸库
bare=/path/projects/.bare/app-api.git
mkdir -p "$(dirname "$bare")"
git init --bare "$bare"
应该输出:
Initialized empty Git repository in /path/projects/.bare/app-api.git/
如果输出 Reinitialized existing Git repository,说明这个裸库已经存在,先停下,不要覆盖。
2. 配置 origin 和 gc
clone=/path/to/任意一个克隆
origin=$(git -C "$clone" remote get-url origin)
echo "$origin"
git --git-dir="$bare" config gc.auto 0
git --git-dir="$bare" config remote.origin.url "$origin"
git --git-dir="$bare" config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
gc.auto=0 是避免迁移过程中自动 gc。
3. 逐个克隆导入
以项目A 为例:
clone=/path/projects/项目A/code/app-api
id=a
git --git-dir="$bare" fetch --no-tags "$clone" "+refs/*:refs/backup/$id/refs/*"
branch=$(git -C "$clone" branch --show-current)
echo "$branch"
git --git-dir="$bare" update-ref "refs/heads/$branch" "$(git -C "$clone" rev-parse HEAD)"
fetch把这个克隆的对象和所有 refs 复制到refs/backup/<id>/refs/*,用命名空间避免和其他克隆的分支重名。update-ref在当前分支名下建一条真正的本地分支,以后 worktree 检出它。- 换下一个克隆,把
clone和id换掉,重复。 - 如果两个克隆在同一个分支上,不要建两次;重复分支的仓库先跳过。
- 如果
branch输出为空,说明源目录是 detached HEAD,先在源目录git checkout -b feature/a建一条分支,再重新执行本节。
4. 暂存区、stash、旧 worktree 也要导入
普通 fetch 只带分支上的提交。暂存区里的新文件、stash 里的改动可能不在任何分支上,需要先做成临时 ref:
sha=$(git -C "$clone" stash create "migration snapshot")
[ -n "$sha" ] && git -C "$clone" update-ref refs/worktree-migration/snapshot "$sha"
stash create 不会改动工作区,只在有改动时返回一个提交号;没有改动时输出为空,update-ref 跳过。
已有 stash 逐条写,编号和 stash@{0}、stash@{1} 一一对应:
i=0
for sha in $(git -C "$clone" stash list --format='%H'); do
git -C "$clone" update-ref "refs/worktree-migration/stash/$i" "$sha"
i=$((i+1))
done
旧 worktree 的 HEAD 同样处理,写成 refs/worktree-migration/old-worktrees/<名字>,再用同样的 fetch 命令一起导入。
再把临时 ref 导入裸库:
git --git-dir="$bare" fetch --no-tags "$clone" \
"+refs/worktree-migration/*:refs/backup/$id/migration/*"
5. 校验
git --git-dir="$bare" show-ref --heads
git --git-dir="$bare" fsck --full --no-dangling
show-ref --heads应该看到每个克隆的当前分支,例如refs/heads/feature/a、refs/heads/release/b。fsck应该没有错误。- 如果索引里的对象缺失,从克隆的
.git/objects复制到裸库的objects,已存在的文件不要覆盖,再跑一次fsck。
6. 裸库建好之后
裸库只负责历史。接下来把每个项目目录变成 worktree,顺序是:备份旧 .git 到 _backup、在原路径建出检出目录、把原有工作区文件放回、复制索引、写该 worktree 的 config.worktree、逐项核对 status 和 diff。转换已有目录比新建目录多一步“保留工作区内容”,做完一个就先核对一个,不一致就回退,别带着问题往下走。
为什么不能只 git clone --bare 其中一个
- 它只复制那一个克隆的本地分支和对象。
- 其他克隆可能有自己的部署分支、未推送提交、stash,这些不在第一个克隆里。
- 十几个克隆各自检出一条分支,要把每个都导入,
refs/heads才完整。
不要对已经建好的裸库重复执行
裸库建好、所有 worktree 都指向它之后,不要对它再跑 git init --bare。它不会清空,但没有必要,容易误操作。
想练手的话,在 /var/tmp 下造两个临时克隆,按上面的步骤建一个临时裸库,不要动现有的 .bare 和 _backup。
五、交给 agent 批量转换
要让 agent 把某个目录下的所有仓库都转成这种结构,把本文链接、目标目录和这句话一起发过去:
按文章第五节的流程,把
<目录>下的所有 Git 仓库转换成裸库 + worktree。先出盘点报告,我确认后再动手。
下面是 agent 要执行的流程。命令都在带暂存区、未跟踪文件、已删除文件、stash、自定义 hooks 的仓库上实测过。
硬性规则
- 先只读盘点,输出报告,等用户确认后再写任何东西。
- 一次只转一个仓库,转完立刻核对;对不上就回退,不要带着问题继续。
- 不提交、不推送、不改远端。
- 不跑
git gc、git prune、git worktree prune。 - 不删
_backup,不删refs/backup/*。 - 不 kill 用户进程;目录被占用就跳过并报告。
- 拿不准的仓库(子模块、浅克隆、进行中的合并、detached HEAD)跳过并写明原因。
- 每个仓库的第 3 到 6 步在同一个 shell 里顺序执行(不要每块单独
bash一次),$bare、$br、before_*这些变量才不会丢。 - 不要
cd进仓库目录,所有命令用绝对路径和git -C。目录被改名后,shell 的当前目录会跟着搬走,后面的相对路径全会跑偏。
第 1 步:盘点(只读)
ROOT=/path/projects
find "$ROOT" -maxdepth 6 \
\( -name node_modules -o -name .venv -o -name venv -o -name dist -o -name build \) -prune \
-o -name .git -print
对每个仓库记录这些信息:
repo=/path/to/repo
[ -d "$repo/.git" ] && echo dir || echo file
git -C "$repo" branch --show-current # 当前分支,空表示 detached HEAD
git -C "$repo" rev-parse HEAD
git -C "$repo" remote get-url origin 2>/dev/null || true
git -C "$repo" status --porcelain=v1 | cut -c1-2 | sort | uniq -c
git -C "$repo" stash list --format='%H'
git -C "$repo" rev-parse --is-shallow-repository
git -C "$repo" submodule status
git -C "$repo" worktree list
git -C "$repo" config --local --get-regexp '^core\.(hooksPath|worktree|fsmonitor)$' || true
ls "$repo/.git" | grep -E 'MERGE_HEAD|REBASE_HEAD|CHERRY_PICK_HEAD|rebase-apply|rebase-merge' || true
按 origin 分组,origin 完全一致的算一组;没有 origin 的单独成组。只有一个仓库的组也照转,只是没有共享收益。
以下情况跳过,不转换:
.git是文件:已经是某个裸库的 worktree- 没有任何提交
- 浅克隆(
is-shallow-repository为 true) - 有真实子模块
- 有进行中的 merge、rebase、cherry-pick、am
- 存在
.git/index.lock - detached HEAD(
branch --show-current为空) - 同组里同一条分支已经被另一个仓库检出
- 有进程的当前目录在仓库里
- 目录里还嵌套着另一个 Git 仓库(
find "$repo" -mindepth 2 -name .git有输出) - 仓库路径本身是符号链接
- 仓库自己还有别的 worktree(
worktree list多于一行) - 仓库本地配置里设了
core.hooksPath、core.worktree或core.fsmonitor(迁移后会失效,先跳过)
嵌套仓库一定要先跳过:转换外层时 tar --exclude=.git 会把里层的 .git 排除,收尾的 rm -rf 又会删掉旧目录,里层的提交历史就没了。先处理里层,或者单独报告给用户。
进程检查:
for pid in /proc/[0-9]*; do
cwd=$(readlink -f "$pid/cwd" 2>/dev/null) || continue
case "$cwd/" in "$repo"/*) echo "$pid $cwd";; esac
done
有输出就跳过这个仓库,让用户自己关掉占用它的终端或 IDE,不要 kill。
这一节的命令按 Linux 写。macOS 上没有 /proc,readlink -f 也不一样,进程检查换成 lsof +D "$repo",其余命令通用。
第 2 步:建裸库(每组一次)
group=app-api
repo=/path/to/组里任意一个仓库
bare="$ROOT/.bare/$group.git"
origin=$(git -C "$repo" remote get-url origin 2>/dev/null || true)
git init --bare "$bare"
git --git-dir="$bare" config gc.auto 0
git --git-dir="$bare" config extensions.worktreeConfig true
git --git-dir="$bare" config remote.origin.url "$origin"
git --git-dir="$bare" config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
如果 git init --bare 输出 Reinitialized existing Git repository,说明裸库已经存在(上次跑过)。先核对三项:remote.origin.url 和本次一致、extensions.worktreeConfig 是 true、gc.auto 是 0。三项都对就跳过第 2 步继续导入;有一项不对就停下报告,不要覆盖。没有 origin 的组跳过最后两条配置。
第 3 步:导入并记录基线(每个仓库)
P=/path/to/repo
id=a
git --git-dir="$bare" fetch --no-tags "$P" "+refs/*:refs/backup/$id/refs/*"
br=$(git -C "$P" branch --show-current)
git --git-dir="$bare" update-ref "refs/heads/$br" "$(git -C "$P" rev-parse HEAD)"
sha=$(git -C "$P" stash create "migration snapshot")
if [ -n "$sha" ]; then
git -C "$P" update-ref refs/worktree-migration/snapshot "$sha"
fi
i=0
for s in $(git -C "$P" stash list --format='%H'); do
git -C "$P" update-ref "refs/worktree-migration/stash/$i" "$s"
i=$((i+1))
done
git --git-dir="$bare" fetch --no-tags "$P" "+refs/worktree-migration/*:refs/backup/$id/migration/*"
stash_count=$(git -C "$P" stash list | wc -l)
id 是备份用的短名,组内不要重复,后面的 refs/backup/$id 和 _backup/$group-$id.git 都靠它区分。组名用仓库名或 origin 最后一段,不要带 /。
导入完立刻记基线,转换后用它核对:
before_head=$(git -C "$P" rev-parse HEAD)
before_index=$(git -C "$P" ls-files -s | sha256sum)
before_status=$(git -C "$P" status --porcelain=v1 | sort | sha256sum)
第 4 步:转换(每个仓库)
if [ -e "$P.migrating" ]; then
echo "STOP: $P.migrating 已存在,先确认上次转换的结果"
exit 1
fi
mv "$P" "$P.migrating"
git -C "$bare" worktree add --no-checkout "$P" "$br"
admin=$(git -C "$P" rev-parse --git-dir)
tar -C "$P.migrating" --exclude=.git -cf - . | tar -C "$P" -xf -
cp "$P.migrating/.git/index" "$admin/index"
{
printf '[core]\n\tbare = false\n'
for key in core.autocrlf core.filemode core.ignorecase; do
val=$(git --git-dir="$P.migrating/.git" config --get "$key" || true)
if [ -n "$val" ]; then
printf '\t%s = %s\n' "${key#core.}" "$val"
fi
done
if grep -qvE '^#|^$' "$P.migrating/.git/info/exclude"; then
cp "$P.migrating/.git/info/exclude" "$admin/exclude"
printf '\texcludesFile = %s\n' "$admin/exclude"
fi
if ls -A "$P.migrating/.git/hooks" | grep -qv '\.sample$'; then
cp -a "$P.migrating/.git/hooks" "$admin/hooks"
printf '\thooksPath = %s\n' "$admin/hooks"
fi
} > "$admin/config.worktree"
--no-checkout 是关键:不让 Git 先检出文件,直接把旧工作区原样搬过来。这样未跟踪文件、被删除但没提交的文件都能保留,索引再单独复制。
第 5 步:核对
fail=""
[ "$(git -C "$P" rev-parse HEAD)" = "$before_head" ] || fail="$fail head"
[ "$(git -C "$P" ls-files -s | sha256sum)" = "$before_index" ] || fail="$fail index"
[ "$(git -C "$P" status --porcelain=v1 | sort | sha256sum)" = "$before_status" ] || fail="$fail status"
[ "$(git -C "$P" rev-parse --is-bare-repository)" = "false" ] || fail="$fail bare"
[ -f "$P/.git" ] || fail="$fail gitfile"
for n in $(seq 0 $((stash_count-1))); do
git --git-dir="$bare" cat-file -e "refs/backup/$id/migration/stash/$n" || fail="$fail stash-$n"
done
if [ -z "$fail" ]; then
echo "OK $P"
else
echo "FAIL $P:$fail"
fi
四项都对上才算通过。对不上就回退,不要先修再试。
第 6 步:收尾或回退
通过:
mkdir -p "$ROOT/.bare/_backup"
if [ -e "$ROOT/.bare/_backup/$group-$id.git" ]; then
echo "STOP: 备份 $group-$id.git 已存在,先确认"
exit 1
fi
mv "$P.migrating/.git" "$ROOT/.bare/_backup/$group-$id.git"
rm -rf "$P.migrating"
失败:
if git -C "$bare" worktree list --porcelain | grep -qF "worktree $P"; then
git -C "$bare" worktree remove --force "$P"
fi
if [ -e "$P" ]; then
echo "STOP: $P 还在,先手动确认,再把 $P.migrating 改回来"
exit 1
fi
mv "$P.migrating" "$P"
回退后再跑一次第 5 步的核对,确认回到转换前的状态。
第 7 步:报告
全部处理完,输出一张表:
| 仓库 | 分支 | 结果 | 说明 |
|---|---|---|---|
| 项目A/code/app-api | feature/a | 已转换 | 24 个未暂存、51 个未跟踪,改动前后一致 |
| 项目B/code/app-api-b | feature/b | 已跳过 | 被 zsh 占用,先关掉终端 |
再附上:
- 每个裸库的
git -C "$bare" fsck --full --no-dangling结果 - stash 引用位置:
refs/backup/<id>/migration/stash/<n>,用git show <sha>查看 _backup路径:$ROOT/.bare/_backup/- 提醒:
.git现在是文件,单独拷走项目要连.bare一起
建议先拿一个 2 到 5 个仓库的小组试,确认报告和用户预期一致,再处理剩下的组。
六、注意事项
.git现在是文件:单独备份或拷走某个项目目录时,要连.bare一起带走,历史不在项目目录里。- 共享裸库是单点:误删分支会影响同组所有 worktree,远端 origin 还在,可以从远端恢复。
worktree add只检出提交:源目录里的未暂存修改和未跟踪文件不会被复制到新目录,新目录是干净的。- 新分支是本地分支:不会自动推送,要推得自己执行
git push。 - 先别对裸库跑
git gc --prune:迁移初期保留_backup,确认没问题再说。 - 自定义 hooks 会留在旧
.git里:仓库装过 husky、Yorkie 这类钩子时,把旧.git/hooks复制到该 worktree 的管理目录,再在它的config.worktree里写core.hooksPath,否则提交前检查不再执行。 - 分支名和目录名按你们的命名规范确认:教程里的
feature/b只是示例,目标目录已有内容时不要硬建。
评论区