版本控制与协作 / 系统课时
排查常见 Git 故障
排查常见 Git 故障
学习目标
完成本课后,你将能够:
- 按状态、分支、远程、历史顺序诊断问题
- 处理非快进推送和分离 HEAD
- 避免用强制命令掩盖根因
问题背景或应用场景
Git 故障往往不是单条命令错误,而是对当前状态判断错误。可靠排查应先收集信息,再选择最小影响操作,避免看到推送拒绝就强制覆盖、看到分离 HEAD 就直接切换丢失提交。
核心原理
基础诊断顺序可以固定为:git status -sb 查看当前状态,git branch -vv 查看跟踪关系,git remote -v 检查地址,git log --graph --oneline --all 查看分叉,必要时使用 git reflog 恢复引用。
非快进推送通常说明远程包含本地没有的提交,应先 fetch 并整合。分离 HEAD 表示 HEAD 直接指向提交而非分支;在该状态创建的提交应及时创建分支保存。强制推送只能在明确理解远程变化并符合团队规则时使用。
基础用法
先保存错误原文和当前状态,不要连续尝试破坏性命令。每次只改变一个变量并重新验证。对于远程问题,优先在临时分支或新克隆中复现。
完整可运行示例
以下命令使用 Bash 语法,并在独立测试目录中执行。示例只使用本地仓库或本地裸仓库模拟远程服务,不依赖互联网;提交哈希、绝对路径等动态值不作为固定输出。
bash
rm -rf git-troubleshoot-demo
mkdir git-troubleshoot-demo
cd git-troubleshoot-demo
git init -q -b main seed
git -C seed config user.name "Seed"
git -C seed config user.email "seed@example.com"
printf "base
" > seed/app.txt
git -C seed add app.txt
git -C seed commit -q -m "feat: base"
git init -q --bare remote.git
git -C seed remote add origin ../remote.git
git -C seed push -q -u origin main
git -C remote.git symbolic-ref HEAD refs/heads/main
git clone -q remote.git alice
git clone -q remote.git bob
for repo in alice bob; do
git -C "$repo" config user.name "$repo"
git -C "$repo" config user.email "$repo@example.com"
done
printf "alice
" > alice/alice.txt
git -C alice add alice.txt
git -C alice commit -q -m "feat: alice update"
git -C alice push -q
printf "bob
" > bob/bob.txt
git -C bob add bob.txt
git -C bob commit -q -m "feat: bob update"
if git -C bob push -q 2>/dev/null; then echo "push: accepted"; else echo "push: rejected"; fi
git -C bob fetch -q origin
git -C bob rebase -q origin/main
git -C bob push -q
printf "push-after-rebase: accepted
"
git -C bob switch -q --detach HEAD~1
printf "rescue
" > bob/rescue.txt
git -C bob add rescue.txt
git -C bob commit -q -m "fix: rescue detached work"
git -C bob switch -q -c rescue-branch
printf "saved-branch: "
git -C bob branch --show-current预期输出
text
push: rejected
push-after-rebase: accepted
saved-branch: rescue-branchTips
- 先复制完整错误信息,不要只描述“Git 不行”。
- 破坏性操作前创建备份分支。
- 远程拒绝通常是保护信号,不是需要绕过的障碍。
常见错误
1. 推送被拒绝就 force
- 错误表现:覆盖了他人提交。
- 产生原因:没有先检查远程新增历史。
- 正确处理:fetch 后比较和整合,必要时使用受控策略。
- 修复结果:双方提交都保留。
2. 分离 HEAD 中提交后直接切走
- 错误表现:新提交变得难以发现。
- 产生原因:没有分支引用保存。
- 正确处理:在当前位置创建救援分支。
- 修复结果:提交重新可达。
本课练习
1. 诊断非快进推送
- 任务目标:练习分叉分析。
- 输入或初始条件:两个克隆分别提交。
- 实现要求:让后推送者先诊断再整合。
- 验收条件:远程最终包含双方提交。
2. 恢复分离 HEAD 提交
- 任务目标:练习救援分支。
- 输入或初始条件:在历史提交上创建新提交。
- 实现要求:创建分支保存。
- 验收条件:普通日志可通过分支访问提交。
3. 建立排障清单
- 任务目标:形成固定流程。
- 输入或初始条件:汇总五类常见错误。
- 实现要求:为每类写检查命令和安全动作。
- 验收条件:清单不依赖直接 hard reset 或 force。
按自己的节奏,确认真正理解。