版本控制与协作 / 知识点
Git 命令速查手册
手册条目
git reset [--soft|--mixed|--hard] HEAD~1移动当前分支指针并选择是否保留提交中的修改。
回退最近提交
需要撤销当前分支最近一次提交时使用 git reset HEAD~1。选择 --soft、默认的 --mixed 或 --hard,决定提交被移除后,修改继续保留在暂存区、只保留在工作区,还是一起丢弃。
基本语法
git reset [--soft|--mixed|--hard] HEAD~1HEAD~1 表示当前提交的父提交;不写模式时等同于 --mixed。

模式选择
| 模式 | 分支指针 | 暂存区 | 工作区 | 典型用途 |
|---|---|---|---|---|
--soft |
回退 | 保留 | 保留 | 重新组织或补充最近一次提交 |
--mixed |
回退 | 重置 | 保留 | 重新选择要暂存的文件 |
--hard |
回退 | 重置 | 重置 | 明确丢弃最近提交及对应修改 |
高频用法
保留修改并保持暂存状态:
git reset --soft HEAD~1
git status --short预期输出示例:
M <PATH>首列状态表示修改仍在暂存区。
保留文件修改但取消暂存:
git reset HEAD~1
git status --short预期输出示例:
M <PATH>第二列状态表示修改只留在工作区。
风险与恢复
--hard 会覆盖暂存区和工作区。只有确认内容可丢弃时才执行;更安全的做法是先创建保护分支 git branch backup-before-reset,或优先使用 --soft、--mixed。
已经推送到共享分支时,优先用 git revert HEAD 生成反向提交,而不是 reset 后强制推送。误回退后先停止进一步清理,执行 git reflog 找到原提交 <ID>,再用 git branch rescue <ID> 保存它。
git reflog [--date=local] [-n <数量>]
git branch <新分支名> <提交哈希>通过引用日志查找并恢复丢失的提交或分支。
恢复误删提交
用于找回因 reset、删除分支或变基而从普通提交历史中消失的提交。核心做法是先从本地引用日志定位原提交哈希,再创建分支或移动当前分支恢复。
查找丢失提交
git reflog --date=local -10预期输出:
a1b2c3d HEAD@{0}: reset: moving to HEAD~1
d4e5f6a HEAD@{1}: commit: add payment validation找到误操作之前的记录。示例中要恢复的提交是 d4e5f6a;实际哈希、时间和说明会不同。
安全恢复方式
先创建临时分支,不立即改动当前分支:
git branch recover-work d4e5f6a
git log -1 --oneline recover-work预期输出:
d4e5f6a add payment validation确认内容正确后,可切换到恢复分支继续工作,或将该提交摘取到当前分支:
git cherry-pick d4e5f6a预期结果:
[<BRANCH> <NEW_HASH>] add payment validation
1 file changed, <N> insertions(+), <N> deletions(-)新提交哈希通常与原哈希不同,因为父提交可能已经变化。
若当前分支本就应回到该提交,并且不需要保留当前位置之后的修改,可执行:
git reset --hard d4e5f6a
git log -1 --oneline预期输出:
d4e5f6a add payment validation风险与边界
git reset --hard <HASH> 会覆盖当前工作区和暂存区。触发条件是存在未提交修改,后果是这些修改被丢弃;安全替代是先创建备份分支,并使用 git stash push -u -m "before recovery" 保存现场。
reflog 主要记录当前仓库本地发生过的引用移动,不是远程备份。记录可能因过期或 git gc 被清理,其他克隆也未必拥有同一条记录,因此发现误删后应尽快恢复并创建正式引用。
排障清单
若 reflog 找不到目标,尝试扫描尚未被清理的悬空对象:
git fsck --full --no-reflogs --unreachable预期输出:
unreachable commit <HASH>对候选哈希执行 git show <HASH> 核对内容,再用 git branch recover-work <HASH> 固定引用。若对象已被垃圾回收,只能从远程仓库、其他开发者克隆或备份中找回。
git bisect start <坏提交> <好提交>
git bisect good|bad
git bisect run <检测命令>
git bisect reset使用二分定位方式找出首次引入故障的提交。
用 git bisect 查找首次引入问题的提交
当一个已知历史版本正常、当前版本稳定复现故障时,用 git bisect 在好提交与坏提交之间不断二分,最终定位“第一个坏提交”。
使用前提
准备一个确定的坏提交、一个确定的好提交,以及能稳定判断当前版本“好/坏”的测试方法。二分期间 Git 会频繁切换提交,开始前最好让工作区保持干净。

可运行示例
下面创建临时仓库并自动定位首次把 status=ok 改成 status=broken 的提交:
tmp_dir=$(mktemp -d)
cd "$tmp_dir"
git init -q
git config user.name "Bisect Demo"
git config user.email "demo@example.com"
printf 'status=ok\n' > app.conf
git add app.conf
git commit -qm "initial good"
good_commit=$(git rev-parse HEAD)
printf 'status=ok\nfeature=a\n' > app.conf
git commit -qam "add feature"
printf 'status=broken\nfeature=a\n' > app.conf
git commit -qam "introduce bug"
printf 'status=broken\nfeature=a\nnote=x\n' > app.conf
git commit -qam "later change"
git bisect start
git bisect bad HEAD
git bisect good "$good_commit"
git bisect run sh -c "grep -q '^status=ok$' app.conf"
git bisect reset预期输出节选:
Bisecting: <N> revisions left to test after this
<COMMIT> is the first bad commit
commit <COMMIT>
introduce bug重点读取 <COMMIT> is the first bad commit;提交哈希和剩余测试次数会随仓库而不同。
自动判定规则
git bisect run <COMMAND> 通过命令退出码判断结果:0 表示 good;1~127 中除 125 外表示 bad;125 表示当前提交无法测试并跳过。测试脚本本身若不稳定,会直接污染二分结论。
风险与恢复
若问题由外部环境、数据变化或多个提交组合触发,可能不存在唯一的“第一个坏提交”。先固定依赖、配置和测试数据,再解释二分结果。
结束后始终执行 git bisect reset 返回原分支。工作区有未提交修改时,先提交到临时分支或用 git stash push -u 保存现场,避免切换提交时被阻塞。
git blame [选项] -- <FILE>
git blame -L <START>,<END> -- <FILE>查看文件每一行最后由哪个提交和作者修改。
用 git blame 追踪代码修改来源
需要确认文件某一行最后由谁、在哪个提交中修改时,使用 git blame。它适合定位改动入口,再结合提交详情判断修改原因。
基本语法
git blame [选项] -- <FILE>
git blame -L <START>,<END> -- <FILE>-- 用来分隔选项与文件名,文件名以短横线开头时尤其重要。
可运行示例
下面创建一个临时仓库,由两名作者分别提交,再查看每行归属。
tmp_dir=$(mktemp -d)
cd "$tmp_dir"
git init -q
git config user.name "Alice"
git config user.email "alice@example.com"
printf 'alpha\nbeta\ngamma\n' > app.txt
git add app.txt
git commit -qm "add initial lines"
git config user.name "Bob"
git config user.email "bob@example.com"
sed -i.bak 's/^beta$/beta-v2/' app.txt
rm -f app.txt.bak
git commit -qam "update beta"
git blame -L 1,3 -- app.txt预期输出
<COMMIT1> (Alice <DATE> 1) alpha
<COMMIT2> (Bob <DATE> 2) beta-v2
<COMMIT1> (Alice <DATE> 3) gamma第二行对应 Bob 的提交;提交哈希、日期和列宽会随环境变化。取得哈希后可执行 git show <COMMIT2> -- app.txt 查看完整差异和提交说明。
常用参数
-L 20,40:只查看第 20~40 行,排查大文件时优先使用。-w:忽略纯空白变更,减少格式化提交干扰。-M:识别同一文件内移动过的代码行。-C:继续尝试识别从其他文件复制或移动来的代码;可重复使用以增强检测,但速度更慢。--show-email:显示作者邮箱,便于在多人仓库中区分同名作者。--line-porcelain:输出稳定的逐行机器格式,适合脚本解析。
输出字段说明
默认每行依次显示提交哈希、作者、提交时间、当前行号和源码。行首带 ^ 的哈希表示该行可追溯到当前历史边界的根提交,不能据此断言它是代码最早来源。
风险与边界
git blame 只指出“最后一次改动该行”的提交,不等于真正引入业务逻辑的人。格式化、批量重命名和代码搬迁会覆盖原归属;优先加 -w、-M 或 -C,并继续查看提交上下文。
文件若经过浅克隆、历史裁剪或未拉取完整分支,结果可能止于当前可见历史。需要完整追踪时先补全历史,再结合 git log -L <START>,<END>:<FILE> 查看该行段的演变。
git log [<提交范围>] [<过滤条件>] [--] [<路径>]按提交说明、作者、日期或代码变化搜索历史记录。
搜索提交内容
在仓库中按提交说明、作者、日期或代码变化定位历史提交。优先缩小分支、时间和路径范围,再决定是否展开补丁,避免在大型仓库中产生大量输出。
基本语法
git log 的过滤条件通常可以组合;多数不同类型条件会继续收窄结果。未写 --all 时,只搜索当前分支可达的历史。
git log [<提交范围>] [<过滤条件>] [--] [<路径>]这是语法模板,不可直接运行。-- 用于明确分隔提交范围与文件路径,路径或关键字含空格时应加引号。
按说明、作者和日期搜索
下面同时限制提交说明、作者和日期,并把结果压缩为一行。-i 忽略提交说明的大小写。
git log --all \
--grep='refund' \
--author='Alice' \
--since='2026-07-01' \
--until='2026-07-31 23:59:59' \
-i \
--pretty=format:'%h %ad %an %s' \
--date=short预期输出
<HASH> 2026-07-18 Alice fix: handle refund timeout
<HASH> 2026-07-09 Alice refactor: simplify refund validation<HASH> 和提交内容以实际仓库为准。没有匹配项时通常不输出内容,不代表命令执行失败。
按代码变化搜索
-S 适合查某个字符串的出现次数在哪次提交中发生变化,常用于追踪函数、常量或字段的引入与删除。
git log --all -S'processRefund' --oneline -- src/预期输出
<HASH> feat: add refund processing
<HASH> refactor: rename refund handler-G 按补丁中新增或删除行的正则表达式匹配,更适合查“哪些提交改过这种代码形态”。
git log -G'paymentStatus[[:space:]]*=' --oneline -- src/预期输出
<HASH> fix: update payment status
<HASH> refactor: centralize status assignment<HASH> 和提交说明会随仓库变化。确认候选提交后,可执行 git show <HASH> 查看完整补丁。
输出字段说明
| 占位符 | 含义 |
|---|---|
%h |
短提交哈希 |
%ad |
作者日期,格式由 --date 控制 |
%an |
作者姓名 |
%s |
提交说明首行 |
风险与边界
- 多个不同过滤条件通常按“同时满足”收窄结果;多个
--grep默认匹配任意一个,要求全部匹配时增加--all-match。 -S判断字符串出现次数是否变化,-G判断补丁行是否匹配正则;选错会漏掉目标提交,无法确认时先分别执行两种搜索。--all -p -G可能扫描大量历史并输出完整补丁。大型仓库应先加日期、提交范围或-- <路径>,确认候选提交后再用git show <HASH>查看详情。- 搜索模式应使用引号,避免空格、星号或括号被 Shell 提前解释。路径可能与分支名重名时必须保留
--。
git clean -n [-d] [-x|-X]
git clean -f [-d] [-x|-X]预览并删除工作区中未被版本控制的文件。
清理未跟踪文件
使用 git clean 预览并删除未被 Git 跟踪的文件或目录。生产排障中始终先执行预览,再把 -n 改为 -f,因为删除后的未跟踪文件通常无法从 Git 恢复。
安全清理流程
先用 git status --short 确认对象确实显示为 ??,再预览并执行删除。-d 表示包含未跟踪目录。
git status --short
git clean -nd
git clean -fd
git status --short预期输出
?? build/
?? debug.log
Would remove build/
Would remove debug.log
Removing build/
Removing debug.log最后一次 git status --short 没有输出,表示工作区已无未跟踪项;实际文件名可能不同。已跟踪文件的修改不会被 git clean 删除。
常用参数
| 参数 | 作用 |
|---|---|
-n、--dry-run |
只预览,不删除 |
-f、--force |
确认执行删除 |
-d |
同时处理未跟踪目录 |
-i |
交互选择要删除的对象 |
-x |
连 .gitignore 中的忽略文件也删除 |
-X |
只删除被忽略的文件 |
-e <模式> |
额外排除匹配对象 |
高频用法
只清理被忽略的构建产物,同时保留普通未跟踪文件:
git clean -ndX
git clean -fdX预期输出
Would remove dist/
Would remove target/
Removing dist/
Removing target/彻底清理未跟踪和被忽略内容前,应先检查 .env、本地证书和调试数据是否也会被删除:
git clean -ndx
git clean -fdx预期输出
Would remove .env
Would remove build/
Would remove notes.tmp
Removing .env
Removing build/
Removing notes.tmp只清理指定目录,并通过 -- 避免路径被解释为选项:
git clean -nd -- build/
git clean -fd -- build/预期输出
Would remove build/
Removing build/对象较多或无法一次确认时使用交互模式:
git clean -di预期输出
Would remove the following items:
build/ debug.log
*** Commands ***
1: clean 2: filter by pattern 3: select by numbers
4: ask each 5: quit 6: help
What now>风险与边界
- 执行
-f后,未跟踪文件不在提交历史中,git restore、git reset和git checkout通常无法找回。存在保留价值时先复制到仓库外,或使用git stash -u保存未跟踪文件。 -x会删除忽略文件,可能包括.env、密钥、IDE 配置和本地数据库。安全替代是使用-X仅清构建产物,或用-e '.env'明确保留。-d会递归删除未跟踪目录。目录内混有手工文件时,先执行git clean -nd或改用git clean -di逐项确认。- 嵌套 Git 仓库默认受保护;第二个强制参数
-ff可越过保护并删除它。除非明确确认该目录可丢弃,否则不要使用-ff。
git worktree add [-b <新分支名>] <路径> [<分支或提交>]
git worktree list
git worktree remove <路径>使用工作树同时检出多个分支并行开发。
创建独立工作目录
需要同时在多个分支上工作,又不想反复切换当前目录时使用 git worktree。它让多个工作目录共享同一套 Git 对象和引用,但各自拥有独立的 HEAD、暂存区和工作区文件。
基本语法
git worktree add <PATH> <BRANCH>
git worktree add -b <NEW_BRANCH> <PATH> <START_POINT>
git worktree list
git worktree remove <PATH>
可运行示例
下面创建临时仓库,并额外创建一个检出 hotfix 分支的工作树:
BASE=$(mktemp -d)
git init -q "$BASE/repo"
git -C "$BASE/repo" config user.name "Demo User"
git -C "$BASE/repo" config user.email "demo@example.com"
printf 'base\n' > "$BASE/repo/README.md"
git -C "$BASE/repo" add README.md
git -C "$BASE/repo" commit -qm "init"
git -C "$BASE/repo" branch -M main
git -C "$BASE/repo" worktree add -b hotfix "$BASE/hotfix" main
git -C "$BASE/repo" worktree list --porcelain预期输出节选:
Preparing worktree (new branch 'hotfix')
HEAD is now at <COMMIT> init
worktree <PATH>/repo
HEAD <COMMIT>
branch refs/heads/main
worktree <PATH>/hotfix
HEAD <COMMIT>
branch refs/heads/hotfix<PATH> 和 <COMMIT> 由运行环境决定。最后两个 worktree 区块确认两个目录分别检出了 main 与 hotfix。
常用操作
| 目标 | 命令 |
|---|---|
| 查看全部工作树 | git worktree list |
| 创建只读检查目录 | git worktree add --detach <PATH> <COMMIT> |
| 安全移除工作树 | git worktree remove <PATH> |
| 清理已丢失目录的元数据 | git worktree prune -v |
| 防止工作树被自动清理 | git worktree lock <PATH> |
同一普通分支默认不能同时检出到多个工作树;如果只是审查某个提交,优先使用 --detach,不要用 --force 绕过保护。
风险与恢复
工作树虽然目录独立,但分支、标签、对象和远程配置仍然共享。在任一工作树删除分支、变基或强制移动引用,都可能影响其他工作树。
不要直接用文件管理器删除仍登记的工作树。优先执行 git worktree remove <PATH>;目录已经意外删除时,再从仍有效的工作树运行 git worktree prune -v 清理失效记录。
git submodule add <仓库地址> <路径>
git submodule update --init --recursive
git submodule status [--recursive]添加、初始化、更新或移除仓库中的子模块。
管理子模块
当主仓库需要引用一个独立 Git 仓库的固定提交时使用子模块。主仓库记录子模块路径、URL 和目标提交,不会把子仓库历史合并进自己的提交历史。
状态关系
子模块同时涉及 .gitmodules、主仓库索引中的子模块提交指针,以及子模块目录自身当前检出的提交。更新子模块后,如果没有在主仓库提交新的指针,其他人仍会得到旧版本。

基本语法
git submodule add <URL> <PATH>
git submodule update --init --recursive
git submodule status
git submodule sync --recursive
git submodule update --remote --checkout--init 初始化本地尚未登记的子模块;--recursive 连同嵌套子模块一起处理;--remote 会按配置的跟踪分支取更新,并可能改变主仓库随后要记录的提交指针。
可运行示例
下面只使用本地临时仓库,创建一个库仓库并把它加入主仓库的 deps/lib:
BASE=$(mktemp -d)
git init -q --bare "$BASE/lib.git"
git clone -q "$BASE/lib.git" "$BASE/lib-src"
git -C "$BASE/lib-src" config user.name "Demo User"
git -C "$BASE/lib-src" config user.email "demo@example.com"
printf 'v1\n' > "$BASE/lib-src/README.md"
git -C "$BASE/lib-src" add README.md
git -C "$BASE/lib-src" commit -qm "init lib"
git -C "$BASE/lib-src" branch -M main
git -C "$BASE/lib-src" push -qu origin main
git --git-dir="$BASE/lib.git" symbolic-ref HEAD refs/heads/main
git init -q "$BASE/app"
git -C "$BASE/app" config user.name "Demo User"
git -C "$BASE/app" config user.email "demo@example.com"
git -C "$BASE/app" -c protocol.file.allow=always submodule add -q "$BASE/lib.git" deps/lib
git -C "$BASE/app" add .gitmodules deps/lib
git -C "$BASE/app" commit -qm "add submodule"
git -C "$BASE/app" submodule status预期结果以最后一行为准:
<COMMIT> deps/lib (heads/main)<COMMIT> 是主仓库当前记录的子模块提交。某些 Git 版本可能另外输出本地空仓库克隆提示;不影响最终 submodule status 的读取。示例仅对这一次 submodule add 临时允许本地 file 协议,没有修改全局安全配置。
高频操作
| 目标 | 命令 |
|---|---|
| 克隆主仓库并拉齐子模块 | git clone --recurse-submodules <URL> |
| 已克隆仓库首次拉子模块 | git submodule update --init --recursive |
| 检查当前子模块状态 | git submodule status --recursive |
| URL 改动后同步本地配置 | git submodule sync --recursive |
| 跟随配置的远程分支升级 | git submodule update --remote --checkout <PATH> |
git submodule status 行首为空格表示已检出到主仓库记录的提交;- 表示尚未初始化;+ 表示当前检出提交与主仓库记录不同;U 表示存在合并冲突。
风险与恢复
直接在子模块目录执行 git pull 只会移动子模块自身的 HEAD。确认升级后必须回到主仓库执行 git add <PATH> 并提交新的指针,否则团队成员不会得到同一版本。
子模块通常以 detached HEAD 检出。需要真正修改依赖时,先在子模块中切换到明确分支,再提交并推送;否则本地提交可能在后续更新中难以找回。
出现 No url found for submodule path 时先检查 .gitmodules 的 path 与 url,再执行 git submodule sync --recursive;出现 reference is not a tree 时,确认主仓库记录的子模块提交确实已经存在于远程仓库。
git fsck [选项]检查 Git 对象、引用和仓库数据是否损坏。
检查仓库完整性
当仓库出现对象读取失败、提交记录异常、克隆后怀疑数据损坏,或磁盘故障后需要确认对象库状态时,使用 git fsck 检查对象、引用和可达性。该命令以只读检查为主,不会自动修复损坏对象。
基本语法
git fsck [选项]常用参数:
--full:检查所有对象池和备用对象库;排障时优先使用。--no-reflogs:不把 reflog 中的对象视为可达,便于查找真正失去引用的对象。--lost-found:把悬空提交或 Blob 写入.git/lost-found/,用于人工恢复。--connectivity-only:只检查对象之间的连接关系,速度更快,但不会校验所有对象内容。
高频用法
先执行完整检查:
git fsck --full预期输出:
dangling commit <COMMIT_ID>
dangling blob <BLOB_ID>没有输出且退出码为 0,通常表示未发现完整性问题。dangling 表示对象存在但当前没有分支、标签或其他可达引用,并不等同于损坏。
需要排除 reflog 干扰时执行:
git fsck --full --no-reflogs预期输出:
unreachable commit <COMMIT_ID>
unreachable tree <TREE_ID>unreachable 表示对象不再被当前引用或 reflog 访问,可结合 git show <COMMIT_ID> 判断是否需要恢复。
检查到悬空提交并希望导出恢复线索时执行:
git fsck --lost-found
find .git/lost-found -maxdepth 2 -type f -print预期输出:
dangling commit <COMMIT_ID>
.git/lost-found/commit/<COMMIT_ID>实际对象 ID 会不同。可用 git show <COMMIT_ID> 查看内容,再通过新分支恢复。
输出判断
dangling:对象完好,但没有可达引用,常见于 reset、rebase 或删除分支之后。unreachable:对象无法从当前引用访问;是否还能恢复取决于对象是否仍保留。missing <TYPE> <ID>:引用指向的对象不存在,仓库已不完整。error: object file ... is empty、corrupt:对象文件损坏,需从远端、备份或其他克隆副本补回。
风险与边界
git fsck 不能重建已丢失的对象。出现 missing 或 corrupt 时,继续执行 git gc 可能让恢复更困难;应先复制整个仓库目录,暂停写入,再从可信远端或备份取回对象。
--lost-found 会在 .git/lost-found/ 写入恢复文件,但不会自动创建分支。确认提交内容后再执行 git branch recover/<NAME> <COMMIT_ID>,避免把未知对象直接合并到正式分支。
排障清单
- 先备份仓库目录,尤其是
.git/objects和.git/refs。 - 执行
git fsck --full,区分dangling与missing/corrupt。 - 对可疑提交运行
git show <COMMIT_ID>,确认内容是否可读。 - 有远端时执行
git fetch --all --prune后重新检查;远端对象可能补回缺失引用,但不会保证修复本地损坏。 - 仍有缺失对象时,从同一仓库的健康克隆或备份恢复,不要直接删除报错对象文件。
速查:只有 dangling 通常不需要处理;出现 missing、bad object 或 corrupt 才属于需要立即备份并修复的完整性故障。
git gc [选项]整理对象并回收无用数据以减小仓库体积。
压缩优化仓库
当 .git 目录持续增大、松散对象过多或大量 rebase、删除分支后需要整理对象时,使用 git gc 打包对象并清理已过期数据。日常优先使用默认参数,不要直接运行激进清理命令。
基本语法
git gc [选项]常用参数:
--auto:仅在对象数量达到 Git 配置阈值时执行维护,适合脚本和日常操作。--aggressive:花费更多 CPU 和时间重新压缩,通常只在仓库明显膨胀且维护窗口充足时使用。--prune=<DATE>:删除早于指定时间且不可达的松散对象;默认通常保留一段宽限期。--prune=now:立即删除不可达松散对象,恢复窗口几乎消失,生产排障中慎用。
高频用法
先查看优化前后的对象占用,再执行默认回收:
git count-objects -vH
git gc
git count-objects -vH预期输出:
count: <LOOSE_COUNT_BEFORE>
size: <LOOSE_SIZE_BEFORE>
in-pack: <PACKED_COUNT_BEFORE>
packs: <PACK_COUNT_BEFORE>
size-pack: <PACK_SIZE_BEFORE>
prune-packable: <PRUNE_COUNT_BEFORE>
garbage: 0
size-garbage: 0 bytes
count: <LOOSE_COUNT_AFTER>
size: <LOOSE_SIZE_AFTER>
in-pack: <PACKED_COUNT_AFTER>
packs: <PACK_COUNT_AFTER>
size-pack: <PACK_SIZE_AFTER>
prune-packable: <PRUNE_COUNT_AFTER>
garbage: 0
size-garbage: 0 bytes实际数量和大小会不同。优化后通常表现为 count、size 降低,in-pack 或 size-pack 增加;git gc 本身成功时通常不输出内容。
让 Git 按阈值自行判断是否需要维护:
git gc --auto
echo $?预期输出:
0退出码 0 表示命令成功;是否真正执行压缩取决于当前松散对象和 pack 数量是否达到配置阈值。
维护窗口内需要更高压缩率时,可先备份后执行:
git gc --aggressive
echo $?预期输出:
0退出码 0 表示执行成功;git gc --aggressive 本身通常无输出。该操作可能持续较久,并显著占用 CPU、磁盘 I/O 和临时空间。
风险与边界
在另一个 Git 进程仍可能创建对象时使用 git gc --prune=now,可能删除刚创建但尚未建立引用的对象,导致并发操作失败或数据难以恢复。安全替代方案是使用默认 git gc,让宽限期保护近期不可达对象,并避开提交、fetch、rebase 等并发写操作。
--aggressive 不保证长期显著缩小仓库。它会增加维护时间,后续新增对象后 pack 仍会继续增长;大型生产仓库应先用 git count-objects -vH 和 du -sh .git 确认问题,再安排低峰维护。
不要把 git prune 当作常规优化命令直接运行。它只处理不可达松散对象,缺少 git gc 的整体协调与安全策略;需要立即清理时也应先备份,并确认没有并发 Git 操作。
排障清单
- 执行
git status,确认没有未完成的 merge、rebase 或 cherry-pick。 - 使用
git fsck --full确认仓库无missing或corrupt错误。 - 检查可用磁盘空间;重打包期间可能同时保留旧 pack 和新 pack。
- 关闭自动化构建、IDE 后台 fetch 等并发 Git 写操作。
- 执行默认
git gc,再用git count-objects -vH和du -sh .git验证效果。 - 若出现锁文件错误,先确认没有 Git 进程,再处理残留的
.lock文件,不要在进程运行时强制删除。
兼容性
现代 Git 通常还会通过 git maintenance 提供计划维护能力;单次手工整理使用 git gc 兼容性更广。托管服务端或共享裸仓库应遵循平台维护策略,不要在未知并发条件下自行执行 --prune=now。
速查:先检查完整性和磁盘空间,再执行默认 git gc;只有在已备份、无并发写入且明确接受恢复窗口消失时,才考虑立即清理。
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize) %(objectname) %(rest)'
git log --all --find-object=<对象ID> --oneline定位导致仓库体积异常增长的大对象和历史文件。
查看大文件历史
用于找出 Git 历史中体积最大的 Blob,并继续定位它由哪些提交引入。命令只读取对象数据库,不会修改工作区或提交历史。
命令定位
git rev-list --objects --all 枚举当前仓库全部可达对象及路径提示,git cat-file --batch-check 读取对象类型和未压缩大小,再按字节数倒序排列。适合排查误提交的压缩包、视频、数据库备份或构建产物。
高频用法
列出历史中最大的 20 个文件对象:
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize) %(objectname) %(rest)' | awk '$1=="blob" {size=$2; oid=$3; $1=$2=$3=""; sub(/^ +/,""); print size "\t" oid "\t" $0}' | sort -nr | head -20预期输出:
<BYTES> <OBJECT_ID> assets/archive.zip
<BYTES> <OBJECT_ID> backup/database.sql第一列是未压缩字节数,第二列是对象 ID,最后一列是该对象关联的历史路径。路径为空时,通常表示对象没有可用路径提示,仍可按对象 ID 继续追踪。
定位某个大对象在哪些提交中被加入或移除:
git log --all --find-object=<OBJECT_ID> --oneline --decorate预期输出:
<COMMIT_ID> (<REF>) add release archive--find-object 会查找该对象出现次数发生变化的提交;结果可能包含引入和删除它的多个提交,需要结合 git show <COMMIT_ID> 查看具体改动。
风险与边界
扫描大型仓库会持续读取大量对象,触发条件是对象数量多或磁盘较慢,可能造成较高 CPU、磁盘 I/O 和数分钟等待。生产服务器上优先在仓库副本执行,并用 head -20 限制输出。
该方法只检查当前本地可达历史。浅克隆、未抓取的远程分支、已过期 Reflog 和已被垃圾回收的对象不会出现在结果中;先补齐所需分支后再扫描。Git LFS 仓库中历史通常只保存指针文件,真实大文件需到 LFS 存储侧检查。
仅执行 git rm 或提交删除不会缩小已有历史。确需清理时,应先备份、评估受影响分支,再使用 git filter-repo 重写历史并协调强制推送,避免直接在共享主分支上试验。
排障清单
- 结果为空:确认当前目录是 Git 仓库,并检查是否为几乎没有历史的浅克隆。
- 只看到当前文件:确认目标提交仍被某个本地分支或标签引用,必要时抓取对应远程引用。
--find-object不受支持:改用git log --all -- <PATH>按历史路径缩小范围,再用git show核对提交。- 仓库占用仍很大:区分工作树文件、松散对象、Pack 文件和 LFS 缓存,可再执行
git count-objects -vH查看空间分布。
git push --force-with-lease <远程名> <分支名>在确认远程历史可被改写时安全执行强制推送。
覆盖推送分支
用于在完成 rebase、commit --amend 或 reset 后更新远程分支。默认使用 --force-with-lease,只有远程分支仍指向预期提交时才允许覆盖。
适用前提
先确认目标分支允许改写历史,并通知正在基于该分支开发的成员。受保护分支、发布分支和多人共享主分支通常应改用新提交修复,而不是覆盖推送。
安全推送
先刷新远程状态、检查双方差异,再执行带租约的强制推送:
git fetch origin <BRANCH>
git log --oneline --left-right --graph origin/<BRANCH>...<BRANCH>
git push --force-with-lease origin <BRANCH>:<BRANCH>预期输出:
To <REMOTE_URL>
+ <OLD_ID>...<NEW_ID> <BRANCH> -> <BRANCH> (forced update)差异列表中 < 表示只存在于远程的提交,> 表示只存在于本地的提交。若出现不属于自己的远程提交,应停止推送并先合并、变基或联系提交者。
对关键分支可固定远程预期提交,避免后台自动 fetch 更新远程跟踪分支后削弱普通租约检查:
expected=$(git rev-parse refs/remotes/origin/<BRANCH>)
git push --force-with-lease=refs/heads/<BRANCH>:$expected origin refs/heads/<BRANCH>:refs/heads/<BRANCH>预期输出:
To <REMOTE_URL>
+ <OLD_ID>...<NEW_ID> <BRANCH> -> <BRANCH> (forced update)这里的 $expected 是本次确认过的远程提交 ID。若远程分支在此后被他人更新,推送会以 stale info 或拒绝更新结束,不会覆盖新提交。
常用参数
--force-with-lease:远程引用符合本地预期时才覆盖,是共享仓库的默认选择。--force-with-lease=<REF>:<OID>:显式锁定远程引用和预期提交,保护条件更明确。--force:无条件覆盖远程引用,可能直接丢失他人提交,不应作为常规替代方案。<LOCAL>:<REMOTE>:明确本地来源和远程目标,避免当前分支名或上游配置不一致时推错分支。
风险与边界
当远程历史已被他人拉取时,覆盖推送会使其本地分支分叉,后续拉取可能产生冲突或重复提交。安全替代方案是在远程历史上追加修复提交,或新建分支发起合并请求。
普通 --force-with-lease 依赖本地远程跟踪引用;IDE 或后台任务自动执行 fetch 时,本地“预期值”可能被刷新。关键操作使用显式 <REF>:<OID>,并在获取预期值后不要再次刷新该引用。
服务端分支保护、权限规则或提交签名策略仍可拒绝推送。客户端参数不能绕过服务器控制,应通过合并请求、临时授权或管理员审批完成。
误推处理
发现误覆盖后立即停止继续提交,记录推送输出中的 <OLD_ID>,并从本地 Reflog、其他成员仓库或代码托管平台审计记录找回旧提交。确认恢复目标后再按同样的显式租约方式推回,避免二次覆盖新的远程更新。