版本控制与协作 / 系统课时

排查常见 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-branch

Tips

  • 先复制完整错误信息,不要只描述“Git 不行”。
  • 破坏性操作前创建备份分支。
  • 远程拒绝通常是保护信号,不是需要绕过的障碍。

常见错误

1. 推送被拒绝就 force

  • 错误表现:覆盖了他人提交。
  • 产生原因:没有先检查远程新增历史。
  • 正确处理:fetch 后比较和整合,必要时使用受控策略。
  • 修复结果:双方提交都保留。

2. 分离 HEAD 中提交后直接切走

  • 错误表现:新提交变得难以发现。
  • 产生原因:没有分支引用保存。
  • 正确处理:在当前位置创建救援分支。
  • 修复结果:提交重新可达。

本课练习

1. 诊断非快进推送

  • 任务目标:练习分叉分析。
  • 输入或初始条件:两个克隆分别提交。
  • 实现要求:让后推送者先诊断再整合。
  • 验收条件:远程最终包含双方提交。

2. 恢复分离 HEAD 提交

  • 任务目标:练习救援分支。
  • 输入或初始条件:在历史提交上创建新提交。
  • 实现要求:创建分支保存。
  • 验收条件:普通日志可通过分支访问提交。

3. 建立排障清单

  • 任务目标:形成固定流程。
  • 输入或初始条件:汇总五类常见错误。
  • 实现要求:为每类写检查命令和安全动作。
  • 验收条件:清单不依赖直接 hard reset 或 force。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查常见 Git 故障

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通