1. 一次提交失败引发的连锁思考如果你日常用 Git 管代码大概率遇到过这个场景本地改了半天信心满满敲下git push结果终端甩回来一串红字大意是远端有你本地没有的提交推送被拒绝。这时候很多人的第一反应是git pull然后 Git 又弹出一个合并提交的编辑器界面或者更糟——直接报冲突把工作区搅成一团。我见过不少同事在这个环节反复折腾最后干脆把本地改动复制出来、git reset --hard、重新粘贴一套操作下来半小时没了还容易丢东西。这篇随笔聊的就是这个高频痛点本地分支与目标分支不一致导致提交失败时怎么用git stash配合git pull --rebase干净利落地解决。标题里带了个三说明这是系列文章的第三篇前两篇大概率铺垫了 Git 的基础操作和分支概念这一篇聚焦的是提交失败这个具体故障场景的处置手法。适合谁看刚上手 Git 一两个月、能完成基本 add/commit/push 但对分支同步机制还犯迷糊的同学也适合用了几年 Git 但一直靠暴力 reset解决问题的老手——说不定能改掉一个坏习惯。先把核心结论摆出来当本地有未提交改动、同时远端分支又领先于本地时正确姿势是先stash暂存工作区再pull --rebase把本地提交垫到远端最新提交之上最后stash pop恢复改动。这套组合拳的价值在于不产生多余的合并提交、不丢失任何本地改动、历史线保持线性整洁。下面我把这套流程背后的原理、每一步的意图、以及踩过的坑掰开揉碎讲清楚。2. 提交失败的根因拆解与方案选型2.1 为什么 push 会被拒绝两条分叉的历史线要理解失败原因得先明白 Git 的分支本质是一条提交链。假设远端main分支上有提交 A→B→C你本地从 B 拉下来后继续开发产生了提交 D此时本地是 A→B→C→D 吗不是。你本地是 A→B→D而远端在你拉取之后又被别人推了 C 上去变成 A→B→C。两条线在 B 之后分叉了。Git 在push时会做一次快进检查fast-forward check它要求你的本地分支必须是远端分支的直接后代也就是远端的所有提交你本地都得有。现在远端有 C 而你没有Git 无法判断 D 和 C 谁先谁后、会不会互相覆盖于是直接拒绝。这个设计是保护机制防止你无意中把别人的提交顶掉。报错信息通常长这样! [rejected] main - main (fetch first) error: failed to push some refs to origin hint: Updates were rejected because the remote contains work that you do hint: not have locally.看到fetch first或non-fast-forward字样基本就是这个病。诊断方法很简单先git fetch origin把远端最新状态拉下来注意 fetch 只更新远端跟踪分支不动你的工作区然后git log --oneline --graph --all看一眼分叉点在哪心里就有数了。2.2 三种解法对比merge、rebase、stashrebase面对分叉常见有三条路我做个对照表方便你按场景选方案操作历史形态适用场景风险点直接 mergegit pull默认 merge产生一个合并提交历史呈网状团队协作、公共分支、需要保留真实合并痕迹合并提交噪音多历史不直观直接 rebasegit pull --rebase线性历史本地提交被重放到远端之上个人分支、追求整洁历史工作区有未提交改动时会失败stash rebasegit stash→git pull --rebase→git stash pop线性历史且改动完整保留本地有未提交改动、又想保持线性多一步 stash 管理pop 可能冲突为什么我推荐第三种因为现实里提交失败往往伴随工作区还有一堆没提交的改动。你直接pull --rebaseGit 会报cannot pull with rebase: You have unstaged changes因为它不敢在脏工作区上做重放操作。这时候要么先 commit但改动没写完不想提交要么 stash。stash 就是那个临时抽屉把工作区收拾干净再操作操作完再拿出来。至于为什么不选 merge在个人开发分支上merge 产生的Merge branch main of ...提交除了污染历史没有任何价值review 的时候看着也烦。rebase 把本地提交搬到远端最新提交之后历史是一条直线git log一眼看到底这是很多团队对个人分支的默认要求。当然公共分支比如团队共享的 develop绝对不要 rebase这是铁律后面会细说。2.3 stash 与 rebase 的底层机制速览git stash的本质是把工作区和暂存区的改动打包成两个有时三个提交对象存到.git/refs/stash这个特殊引用下然后把工作区恢复到 HEAD 的干净状态。你可以把它理解成给当前改动拍个快照塞进抽屉桌面擦干净。git stash list能看到抽屉里所有快照git stash pop是取出最近一个并从抽屉删除git stash apply是取出但保留在抽屉里。git pull --rebase则是两步合一先fetch拿到远端最新提交再rebase——把你本地独有的提交逐个摘下来暂存到一边把本地分支指针移到远端最新提交然后把这些提交一个个重新贴上去。贴的过程中如果某个提交和远端改动冲突rebase 会暂停让你解决解决完git rebase --continue继续。理解了这个摘下-移动-重贴的过程你就明白为什么 rebase 会改写提交哈希了——因为父提交变了哈希必然变。3. 完整实操流程与关键参数3.1 第一步确认状态别急着动手动手前先做体检这一步很多人跳过结果后面抓瞎。三条命令足够git status git stash list git log --oneline --graph --all -10git status告诉你工作区有哪些改动、哪些已暂存、当前在哪个分支。git stash list看看抽屉里是不是已经有旧快照有的话先想清楚要不要别 pop 错了对象。git log --graph看分叉结构确认远端确实领先。我踩过的坑有一次 stash 里躺着三天前的半成品我 pop 的时候没注意直接把旧改动和新改动混在一起排查了半天。所以动手前先git stash list扫一眼是保命习惯。3.2 第二步stash 暂存工作区git stash push -m feat: 用户模块半成品待rebase后恢复带-m加备注是个好习惯尤其你一天 stash 好几次的时候stash{0}、stash{1}这种编号根本分不清谁是谁。默认git stash只存已跟踪文件的改动如果你有新创建但没git add的文件它们不会被 stashrebase 后还在工作区里杵着。要连未跟踪文件一起存用git stash push -u -m 包含未跟踪文件-u是--include-untracked的缩写。还有个-a--all连被 ignore 的文件也存一般用不上慎用。stash 完再git status确认工作区干净这是进入下一步的前提。3.3 第三步pull --rebase 拉取并重放git pull --rebase origin main这里有个细节值得说git pull默认行为在不同 Git 版本里不一样老版本默认 merge新版本可能提示你配置。与其依赖默认值不如显式写--rebase意图明确也避免换台机器行为不一致。如果你嫌每次敲麻烦可以设全局默认git config --global pull.rebase true设完之后git pull就等价于git pull --rebase。但注意这个配置是全局的如果你有些仓库确实需要 merge 行为记得在那些仓库里单独git config pull.rebase false覆盖掉。rebase 过程中如果本地提交和远端改动冲突终端会停下来提示CONFLICT此时git status会列出冲突文件。解决冲突后git add 冲突文件 git rebase --continue如果想放弃这次 rebase 回到操作前git rebase --abort一键还原这是 rebase 的后悔药记住它心里不慌。3.4 第四步stash pop 恢复改动并收尾git stash poppop 会把最近一个 stash 取出并应用同时从 stash 列表删除。如果应用时和当前代码冲突比如 rebase 后远端改动碰巧改了你 stash 里的同一行Git 会报冲突并保留 stash 不删除这时候你解决完冲突手动git stash drop清理即可。这个设计挺贴心——冲突没解决干净它不敢删你的快照。恢复完改动git status再确认一遍然后正常git add、git commit、git push。此时本地历史已经是线性的push 一路绿灯。3.5 参数速查与命令清单把上面流程浓缩成一张速查表贴在显示器边上都行步骤命令作用备注体检git status/git stash list/git log --graph --all确认工作区与分叉状态必做暂存git stash push -u -m 备注打包工作区改动-u含未跟踪文件拉取重放git pull --rebase origin main本地提交垫到远端之上冲突则解决后--continue恢复git stash pop取出改动冲突时 stash 保留推送git push推送线性历史此时应成功4. 高频翻车现场与排查实录4.1 stash pop 冲突了怎么办这是最常见的翻车点。现象git stash pop后终端报CONFLICT (content): Merge conflict in xxx文件里出现标记。别慌这跟普通合并冲突处理逻辑一样打开文件保留你要的代码删掉冲突标记git add标记已解决。区别在于——stash 冲突解决后不会自动 drop你得手动git stash drop否则快照一直躺在列表里下次 pop 又冒出来。我个人的习惯是pop 冲突解决完先git stash list确认那个快照还在再git stash drop stash{0}。如果解决到一半发现搞砸了git checkout -- .丢弃工作区stash 还在可以重来。这个快照不自动删的特性反而是个安全网。4.2 rebase 到一半想放弃rebase 冲突解决到第三个文件突然发现方向错了想回到操作前。git rebase --abort直接还原到 rebase 开始前的状态本地提交、工作区都回来。但注意abort 之后你之前 stash 的改动还在抽屉里需要手动 pop。有些人 abort 完发现工作区是干净的以为改动丢了其实是忘了 pop虚惊一场。还有一种情况rebase 已经--continue完成了但发现搞错了想回退。这时候用git reflog找到 rebase 前的 HEAD 位置git reset --hard 哈希回去。reflog 是 Git 的黑匣子记录所有 HEAD 移动rebase、reset、checkout 都能追溯强烈建议每个用 Git 的人都学会看 reflog。4.3 误在公共分支上 rebase这是最严重的问题必须单独拎出来说。假设你和同事共用develop分支你本地 rebase 后强推git push -f远端历史被改写同事本地的develop和远端彻底分叉他们下次 pull 会看到一堆莫名其妙的冲突甚至可能把别人的提交搞丢。判断标准很简单这个分支是不是只有你一个人在用是随便 rebase不是老老实实 merge。已经误操作了怎么办赶紧通知所有相关同事让他们git fetch后git reset --hard origin/develop重新对齐前提是他们本地没有未推送的提交。预防手段给公共分支加保护很多代码托管平台都支持禁止强推设置打开它。4.4 常见问题速查表现象可能原因处置cannot pull with rebase: unstaged changes工作区脏先git stashpush rejected (fetch first)远端领先本地stashpull --rebasestash pop报冲突stash 与当前代码同行冲突手动解决后git stash droprebase 卡住不动有冲突未解决git status看冲突文件解决后--continue改动消失了忘了stash popgit stash list找回历史乱成一团误 rebase 公共分支通知团队reset --hard对齐远端4.5 几条压箱底的经验第一条stash 不是长期存储。有人把 stash 当草稿箱攒了十几个快照最后自己都忘了哪个是哪个。stash 适合几小时内临时周转超过一天的建议开个临时分支git checkout -b wip/xxx提交上去比 stash 可靠得多。第二条rebase 前先git fetch看一眼远端。有时候远端改动很大你 rebase 上去冲突一堆不如先看看远端改了什么评估一下要不要先合并再继续。git log HEAD..origin/main --oneline能列出远端比你多的提交扫一眼心里有底。第三条养成pull --rebase前先 commit 或 stash 的肌肉记忆。我现在敲git pull之前手会自动先git status脏的话先 stash这个习惯帮我省了无数次cannot pull的报错。第四条冲突解决完跑一遍测试再 push。rebase 重放提交时虽然每个提交的改动内容没变但上下文变了可能出现单独看没问题、合起来编译不过的情况。尤其是涉及依赖版本、接口签名的改动rebase 后务必本地构建一次别把问题推给 CI。这套 stash pull --rebase 的组合我从早期被push rejected搞得手忙脚乱到现在闭着眼睛都能走完流程中间踩的坑基本都在这了。核心就一句话动手前先看状态脏工作区先 stash拉取用 rebase 保线性恢复后跑测试再推。把这四步变成条件反射提交失败就不再是事故而是一个三十秒能解决的小插曲。