仓库维护与大型项目管理
开场:仓库为什么会变成问题
小项目里,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字段 | 含义 |
|---|---|
| 松散对象数(一个对象一个文件) |
| 松散对象占用的磁盘空间(KB) |
| 已经打包进 packfile 的对象数 |
| packfile 的大小(KB) |
松散对象与 packfile
每次提交,Git 先把对象写成松散对象:一个对象一个文件,放在 .git/objects/ab/cdef... 下。 对象多了以后,Git 会把它们打包成 packfile,放在 .git/objects/pack/ 下, 压缩存储、检索更快。packfile 里还做了 delta 压缩:相似的内容只存差异。
手动触发打包:
git gcgc 是 garbage collection,做四件事:
把松散对象打包成 packfile;
合并多个小 packfile;
清理不可达对象(没有被任何引用或 reflog 指向的);
清理过期的 reflog。
日常不需要频繁手动 gc,Git 会在对象积累到一定数量时自动触发。仓库很大时,手动跑一次能明显减小体积、提升速度。
prune:真正删除不可达对象
gc 默认会保留一段时间内的不可达对象(默认两周),防止误删。想立即清理:
git gc --prune=now
# 或单独用
git pruneprune 是危险操作,执行前先确认
不可达对象里可能有你还没用 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优化三件事:
确认
.gitignore写对了,别让node_modules、build/这类目录进工作区;开启文件系统监控:
git config core.fsmonitor trueGit 会记录文件变化,status 时不用全量扫描。Git 2.37 之后内置支持,之前需要装
fsmonitor--daemon。开启 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 pruneworktree 的边界
同一个分支不能同时在两个 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 mainsubmodule vs subtree
submodule | subtree | |
|---|---|---|
代码是否在主仓库 | 否,只存引用 | 是,真实复制进来 |
克隆后是否直接可用 | 否,要 | 是,直接就在 |
历史 | 主仓库不包含子模块历史 | 可以选择是否包含 |
更新方式 |
|
|
删除难度 | 麻烦 | 相对简单 |
适合场景 | 依赖独立、版本锁定 | 想简化协作、不介意代码复制 |
一句话: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 statusLFS 的边界
需要服务器支持。GitHub、GitLab 支持,但有存储和流量配额。自建服务器要装
git-lfs服务端。LFS 不是万能的。它适合“大但改动不频繁”的文件,比如设计稿、视频、数据集。频繁改的大文件,LFS 也会积累很多版本。
已经提交进普通 Git 的大文件,转 LFS 要用
filter-repo重写历史,不是git lfs track就完事。LFS 指针文件很小,但 clone 时如果没装 LFS,会得到一个指针文本,不是真实文件。
这一课把“仓库变大变慢”拆成三层:对象库、历史、工作区。对象库用 gc 和 LFS,历史用浅克隆和部分克隆, 工作区用 worktree、submodule、subtree。每一样都不是日常必用,遇到对应症状再取用。