仓库维护与大型项目管理

开场:仓库为什么会变成问题

小项目里,git clone 几秒钟,git status 瞬间返回,你感觉不到仓库的存在。但项目长大后,会出现这些症状:

  • clone 要等十几分钟,甚至失败;

  • git status 卡好几秒;

  • .git 目录比代码本身还大好几倍;

  • 多个功能要同时开发,来回切分支把工作区搞乱;

  • 一个项目要复用另一个项目的代码,复制粘贴又难同步。

这一课就回答这些问题。先记住一个总原则:

仓库的问题分三层,不同层用不同工具

对象库太大 → 打包、清理、LFS;历史太长 → 浅克隆、部分克隆、限制 log 范围; 工作区太乱 → worktree、submodule、subtree。不要一上来就 git gc,先定位是哪一层的问题。

仓库为什么只增不减

要解决什么:项目用久了,.git 越来越大,想知道它到底装了什么、能不能清理。

第六课讲过,Git 是内容寻址的文件系统。每次 commit、add,都会往 .git/objects 里写对象。 Git 几乎不自动删对象,因为对象可能还被某个提交、某个分支、某个 reflog 引用着。

查看仓库大小和对象数量:

du -sh .git git count-objects -v
count: 120
size: 480
in-pack: 3400
packs: 1
size-pack: 20480
prune-packable: 0
garbage: 0
size-garbage: 0

字段

含义

count

松散对象数(一个对象一个文件)

size

松散对象占用的磁盘空间(KB)

in-pack

已经打包进 packfile 的对象数

size-pack

packfile 的大小(KB)

松散对象与 packfile

每次提交,Git 先把对象写成松散对象:一个对象一个文件,放在 .git/objects/ab/cdef... 下。 对象多了以后,Git 会把它们打包成 packfile,放在 .git/objects/pack/ 下, 压缩存储、检索更快。packfile 里还做了 delta 压缩:相似的内容只存差异。

手动触发打包:

git gc

gc 是 garbage collection,做四件事:

  1. 把松散对象打包成 packfile;

  2. 合并多个小 packfile;

  3. 清理不可达对象(没有被任何引用或 reflog 指向的);

  4. 清理过期的 reflog。

日常不需要频繁手动 gc,Git 会在对象积累到一定数量时自动触发。仓库很大时,手动跑一次能明显减小体积、提升速度。

prune:真正删除不可达对象

gc 默认会保留一段时间内的不可达对象(默认两周),防止误删。想立即清理:

git gc --prune=now
# 或单独用
git prune

prune 是危险操作,执行前先确认

不可达对象里可能有你还没用 reflog 找回的提交。执行前先看:

git reflog
git fsck --lost-found

没有需要找回的东西,再 prune。

一个常见误解

git gc 不会删除已提交的历史。它只清理“没有引用指向”的对象。 你正常提交的内容,永远在历史里,gc 动不了它。要删历史,得用 filter-repo,那是上一课的内容。

浅克隆:只要最近的历史

要解决什么:git clone 默认拉取完整历史。一个跑了五年的项目,历史可能有几万个提交,克隆下来几个 GB。但很多时候你只需要最近几个月的代码。

# 只拉最近 1 个提交
git clone --depth 1 git@github.com:用户名/仓库名.git # 只拉最近 50 个提交
git clone --depth 50 git@github.com:用户名/仓库名.git

浅克隆的仓库,git log 只能看到浅克隆范围内的提交。超出范围的,Git 不知道,也不去拉。

加深浅克隆

后来需要更多历史:

# 再拉 100 个提交的历史
git fetch --deepen=100 # 或者直接取消浅克隆,拉完整历史
git fetch --unshallow

浅克隆的边界

  • 不能 push 到浅克隆之外的提交。基于浅克隆做提交,推回去没问题;但不能把历史“补全”后推上去,Git 会拒绝。

  • rebase、merge 可能因为缺少共同祖先而失败。浅克隆的提交没有完整父链,三方合并找不到共同祖先。

  • git log --graph 可能显示不完整。

所以浅克隆适合:CI/CD 环境、只需要最新代码的部署场景、临时查看代码。不适合需要完整历史的开发仓库。

部分克隆:只拉需要的对象

Git 2.19 之后支持部分克隆(partial clone),只拉提交和树,不拉文件内容(blob):

git clone --filter=blob:none git@github.com:用户名/仓库名.git

--filter=blob:none 表示“不拉 blob,需要时再拉”。适合大仓库、历史里有很多大文件但你只需要当前版本的情况。 需要某个文件时,Git 会自动去远程拉对应 blob,叫“懒加载”。

这个特性需要服务器支持。GitHub、GitLab 都支持,自建 Git 服务器要看版本。

大仓库的性能瓶颈

要解决什么:仓库慢,但不知道慢在哪。先定位,再对症。

症状一:git status 慢

原因通常是工作区文件太多,Git 要逐个检查文件状态。诊断:

time git status

优化三件事:

  1. 确认 .gitignore 写对了,别让 node_modules、build/ 这类目录进工作区;

  2. 开启文件系统监控:

    git config core.fsmonitor true

    Git 会记录文件变化,status 时不用全量扫描。Git 2.37 之后内置支持,之前需要装 fsmonitor--daemon。

  3. 开启 untracked cache:

    git config core.untrackedCache true

    缓存未跟踪文件列表,减少重复扫描。

症状二:git log 慢

原因通常是历史太长,或者历史里有大量 merge commit。优化:

# 限制输出条数
git log --oneline -20 # 只看主干,跳过合并进来的分支历史
git log --oneline --first-parent

--first-parent 只沿每个合并提交的第一个父提交走,也就是主线。分支内部的提交不显示,历史短很多。

症状三:clone 慢

原因通常是仓库太大,或者网络慢。优化:

# 浅克隆
git clone --depth 1 <地址> # 部分克隆
git clone --filter=blob:none <地址> # 只拉一个分支,不拉其他分支的引用
git clone --single-branch --branch main <地址>

默认 clone 会拉所有分支的引用,--single-branch 只拉指定分支。

症状四:.git 目录巨大

原因通常是历史里提交过大文件,比如视频、数据集、编译产物。诊断:

git rev-list --objects --all \ | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' \ | sort -k3 -n -r \ | head -20

列出历史中最大的 20 个对象。如果发现大文件,处理方式两条:

  • 文件还需要 → 用 Git LFS 管理(本节后面讲);

  • 文件不需要了 → 用 filter-repo 从历史中删除(上一课讲过了)。

worktree:一个仓库,多个工作区

要解决什么:你正在 feature-a 上开发,突然要修一个紧急 bug。 传统做法是 stash 或 commit 当前改动,切分支,修完再切回来。麻烦,而且容易忘。

git worktree 允许你在同一个仓库上,同时检出多个工作区,每个工作区在不同分支上。

基本用法

# 在 ../hotfix-branch 目录创建一个工作区,检出 hotfix 分支
git worktree add ../hotfix-branch hotfix # 查看所有 worktree
git worktree list
/path/to/main-repo a1b2c3d [main]
/path/to/hotfix-branch d4e5f6a [hotfix]

在 hotfix-branch 目录里改代码、提交,和普通仓库一样。 两个工作区共享同一个 .git 对象库,但工作区和 HEAD 是独立的。

基于已有分支创建 worktree

git worktree add ../review-branch origin/feature-x

这会创建一个新分支(默认和远程分支同名),检出到新工作区。

删除 worktree

git worktree remove ../hotfix-branch # 或者手动删目录后清理记录
git worktree prune

worktree 的边界

  • 同一个分支不能同时在两个 worktree 上检出。防止两个工作区同时改同一个分支,状态混乱。

  • worktree 共享对象库。在一个 worktree 上执行 gc、fetch,对所有 worktree 生效。

  • worktree 不是“复制仓库”。它没有独立的 .git 目录,只有一个 .git 文件指向主仓库。

适用场景:紧急修 bug 不想打断当前工作、同时 review 多个 PR、跑长测试时另一个 worktree 继续开发。

submodule:在一个仓库里引用另一个仓库

要解决什么:你的项目依赖另一个独立维护的库。你不想复制粘贴代码,希望“引用”它,并且能锁定版本。

添加子模块

git submodule add git@github.com:用户名/库名.git libs/库名

这会在 libs/库名 目录克隆那个仓库,并在主仓库里创建 .gitmodules 文件,记录子模块的 URL 和路径:

[submodule "libs/库名"] path = libs/库名 url = git@github.com:用户名/库名.git

主仓库不存子模块的文件内容,只存一个指向子模块某个提交的引用。 git status 会显示子模块的提交哈希。

克隆带子模块的仓库

普通 clone 不会自动拉子模块内容:

git clone git@github.com:用户名/主仓库.git
cd 主仓库
git submodule init
git submodule update # 或一步到位
git clone --recurse-submodules git@github.com:用户名/主仓库.git

更新子模块

子模块指向的提交是锁定的。上游子模块更新了,主仓库不会自动跟着变。要手动更新:

cd libs/库名
git fetch
git switch main
git pull
cd ../..
git add libs/库名
git commit -m "chore: 更新子模块到最新"

主仓库记录新的子模块提交哈希,提交后别人 submodule update 才会拉到新版本。

submodule 的痛点

  • 容易忘。clone 后不 init + update,子模块目录是空的;

  • 切分支时子模块状态可能不一致。需要 git submodule update 同步;

  • 提交子模块更新容易漏。子模块目录里的改动,要在主仓库里 add + commit 才算数;

  • 删除子模块很麻烦。要改 .gitmodules、.git/config、删目录、git rm --cached,步骤多。

所以 submodule 适合:依赖版本稳定、不需要频繁改动、团队都熟悉 submodule 流程的场景。

subtree:把另一个仓库嵌进来

要解决什么:submodule 操作太麻烦,想要一个更简单的方案,代价是代码真正复制进主仓库。

git subtree 把另一个仓库的代码真正复制进主仓库,但保留“这是从哪个仓库来的”信息,方便以后同步。

添加 subtree

git subtree add --prefix=libs/库名 git@github.com:用户名/库名.git main --squash

--prefix 是放到哪个目录,后面是仓库地址和分支。 --squash 表示把子仓库的历史压成一条提交,不把完整历史带进来。

拉取上游更新

git subtree pull --prefix=libs/库名 git@github.com:用户名/库名.git main --squash

推送本地修改回上游

git subtree push --prefix=libs/库名 git@github.com:用户名/库名.git main

submodule vs subtree

submodule

subtree

代码是否在主仓库

否,只存引用

是,真实复制进来

克隆后是否直接可用

否,要 init + update

是,直接就在

历史

主仓库不包含子模块历史

可以选择是否包含

更新方式

submodule update

subtree pull

删除难度

麻烦

相对简单

适合场景

依赖独立、版本锁定

想简化协作、不介意代码复制

一句话:submodule 是“链接”,subtree 是“嵌入”。submodule 更干净,但操作复杂;subtree 更简单,但代码在主仓库里,历史可能变臃肿。

Git LFS:大文件管理

要解决什么:Git 不适合存大文件。每次修改一个 100MB 的视频,Git 都会存一个新版本,仓库迅速膨胀。 而且 clone 时要把所有历史版本都拉下来。

Git LFS(Large File Storage)解决这个问题:大文件的实际内容存在单独的文件服务器上,Git 仓库里只存一个指针文件。

安装与初始化

先装 Git LFS 客户端(官网或包管理器)。然后在仓库里初始化:

git lfs install git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "datasets/**"

这会修改 .gitattributes,记录哪些文件走 LFS:

*.psd filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

提交 .gitattributes:

git add .gitattributes
git commit -m "chore: 配置 Git LFS"

之后 git add 这些文件,Git 会把内容传给 LFS 服务器,仓库里只存指针。

克隆带 LFS 的仓库

git lfs install
git clone git@github.com:用户名/仓库名.git # 如果 LFS 文件没自动拉
git lfs pull

查看 LFS 状态

git lfs ls-files
git lfs status

LFS 的边界

  • 需要服务器支持。GitHub、GitLab 支持,但有存储和流量配额。自建服务器要装 git-lfs 服务端。

  • LFS 不是万能的。它适合“大但改动不频繁”的文件,比如设计稿、视频、数据集。频繁改的大文件,LFS 也会积累很多版本。

  • 已经提交进普通 Git 的大文件,转 LFS 要用 filter-repo 重写历史,不是 git lfs track 就完事。

  • LFS 指针文件很小,但 clone 时如果没装 LFS,会得到一个指针文本,不是真实文件。

这一课把“仓库变大变慢”拆成三层:对象库、历史、工作区。对象库用 gc 和 LFS,历史用浅克隆和部分克隆, 工作区用 worktree、submodule、subtree。每一样都不是日常必用,遇到对应症状再取用。