侧边栏壁纸
  • 累计撰写 113 篇文章
  • 累计创建 48 个标签
  • 累计收到 6 条评论

目 录CONTENT

文章目录

Git 裸库 + worktree 教程:一个仓库检出多个目录

无尤
2026-11-17 / 0 评论 / 0 点赞 / 7 阅读 / 0 字

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-apifeature/a已转换24 个未暂存、51 个未跟踪,改动前后一致
项目B/code/app-api-bfeature/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 只是示例,目标目录已有内容时不要硬建。
0

评论区