1. 为什么单独把 git push 的参数拎出来讲很多人用 Git 用了两三年git push这条命令翻来覆去就敲过两种形态git push和git push origin master。日常提交代码确实够用可一旦碰上多人协作、分支策略调整、误提交回滚、CI 流水线配置这些场景光靠这两条命令就会开始抓瞎。我见过不少同事在推送失败时第一反应是删本地仓库重新克隆其实问题往往就出在 push 的参数没配对。git push的参数体系是整个 Git 命令里最容易被低估的一块。它不像git rebase那样有炫技感也不像git log那样天天被翻但它直接决定了你本地的提交以什么方式、推到哪个远端、覆盖还是拒绝、要不要顺带建立追踪关系。这些决策一旦出错轻则推送被拒重来一遍重则把别人的提交冲掉或者把不该公开的分支推上去。这篇内容面向的是已经能完成日常提交、但对 push 行为缺乏掌控感的开发者。我会把git push的参数按使用场景拆开讲重点放在那些知道的人觉得理所当然、不知道的人反复踩坑的地方。每个参数我都会说清楚它解决什么问题、背后的机制是什么、什么情况下该用、什么情况下千万别用。读完之后你应该能对着任意一次推送需求快速组合出正确的参数而不是靠试。需要先说明一点push 的参数在不同 Git 版本间有细微差异下面涉及的参数以当前主流稳定版本为准个别较新的参数我会标注适用条件。另外所有示例里的远端名统一用origin分支名用main和feature这类通用命名你可以直接替换成自己项目里的实际名称。2. push 的基本模型先搞清楚它在推什么2.1 一次 push 到底发生了什么在讲参数之前得先把 push 的底层动作说清楚否则参数讲再多也是死记硬背。git push的本质是一次引用更新请求本地 Git 把某个分支或标签当前指向的提交对象连同它背后缺失的对象一起打包发送给远端然后请求远端把对应的引用从旧值更新为新值。这里的关键词是引用更新。远端并不是简单地接收文件它是在做一次带条件的引用替换。远端会检查你要更新的这个引用当前值是不是你声明的旧值如果是允许更新如果不是说明期间有人推过拒绝。这个机制叫快进检查fast-forward check是 push 安全性的根基。理解了这个模型很多参数就好解释了。--force是让远端跳过旧值校验直接覆盖--force-with-lease是让你自己声明一个我认为远端旧值是什么远端拿这个值去比对对不上就拒绝--delete是把更新目标变成一个空引用等价于删除。所有参数本质上都在调整这次引用更新请求的条件和范围。2.2 本地分支、远端分支与追踪关系新手最容易混淆的是三个东西本地分支、远端跟踪分支、远端分支。本地分支main是你工作的地方远端跟踪分支origin/main是本地对远端 main 上次长什么样的缓存远端分支是远端仓库里真实存在的main。git push默认行为依赖追踪关系upstream。当你git clone或git push -u之后本地分支会记住它的 upstream 是哪个远端的哪个分支。有了追踪关系直接敲git push就知道往哪推没有追踪关系Git 会报错让你显式指定或者根据push.default配置猜一个。这个设计的意义在于push 的目标不该靠猜。追踪关系是一份显式契约写清楚了这个本地分支对应远端哪个分支。后面讲-u参数时你会看到建立追踪关系本身就是一次 push 的副产品。2.3 push.default 配置决定了裸 push 的行为在不带任何参数敲git push时Git 到底推什么由push.default这个配置决定。这个配置有几个常见取值理解它们能避免很多我明明只想推当前分支怎么推了一堆东西上去的困惑。取值行为适用场景simple只推当前分支到它的 upstream且要求两边分支名相同现代 Git 默认值最安全current只推当前分支到同名远端分支分支名规范统一的团队matching推送所有本地与远端同名的分支老项目、多分支同步nothing裸 push 直接报错必须显式指定强制显式操作防误推simple和current的区别很微妙simple要求本地分支名和 upstream 分支名一致current则允许推到不同名的远端分支。大多数团队用默认的simple就够了。如果你的团队分支命名有前缀规范比如本地叫feature-login远端要求叫login那current配合显式 upstream 会更顺手。我个人的建议是永远不要用matching。它会在你只想推一个分支时把所有同名分支一起推上去在多分支并行开发时极易造成意外推送。这个配置是历史遗留现代项目没有理由再用。3. 常用参数逐个拆从安全到激进3.1 -u / --set-upstream一次推送长期省事-u大概是git push里性价比最高的参数。第一次推送一个新分支时用它Git 会在推送成功后把本地分支的 upstream 设置为对应的远端分支之后直接git push和git pull都不用再带远端和分支名。git push -u origin feature这条命令做了两件事把本地feature推到远端origin/feature然后建立追踪关系。之后你在feature分支上敲git pushGit 就知道往origin/feature推。这里有个细节值得说-u建立的是双向追踪关系push 和 pull 都受益。很多人只知道它对 push 有用其实git pull不带参数能正常工作靠的也是这个 upstream。所以新分支第一次推送时带上-u是一个几乎无成本的好习惯。注意如果远端已经存在同名分支且历史不一致-u推送会失败。这时候不要急着加--force先搞清楚远端那个分支是什么来路是不是别人正在用的分支。3.2 --force 与 --force-with-lease强推的正确姿势--force是 push 参数里最危险的一个它让远端无条件接受你的引用更新跳过快进检查。什么时候真的需要它典型场景是本地历史被改写过你做了git rebase、git commit --amend、或者git reset回退了提交本地分支的提交链和远端已经分叉普通推送会被拒绝这时候才需要强推。但--force的问题在于它太粗暴如果在你 rebase 期间别人往同一个远端分支推了新提交你的强推会把这些提交直接冲掉而且没有任何提示。这就是所谓的覆盖别人的工作。--force-with-lease就是为解决这个问题设计的。它的逻辑是我强推但前提是远端的当前值必须等于我本地记录的origin/分支值。如果期间有人推过我本地的origin/分支缓存就过期了比对不上推送被拒绝。git push --force-with-lease origin feature这条命令的语义是如果远端 feature 还是我上次看到的那个样子就覆盖它如果变了就拒绝并告诉我。它把覆盖别人提交的风险从无条件变成了有条件。实操心得--force-with-lease有一个坑——如果你在强推前执行过git fetch本地的origin/分支缓存会被更新成远端最新值这时候 lease 检查就形同虚设了。所以强推前不要 fetch让缓存保持你记忆中的远端状态这样 lease 才有保护意义。这个细节很多人不知道导致以为用了 lease 就万无一失。还有一个更严格的变体--force-with-lease分支:期望的提交哈希可以显式指定你期望的远端值适合脚本化场景。日常手动操作一般用不带参数的版本就够。3.3 --delete删远端分支别用错命令删除远端分支有两种写法效果一样git push origin --delete feature git push origin :feature第二种是第一种的简写冒号左边为空表示推一个空引用过去等价于删除。我建议用--delete可读性好不容易看错。这里要区分清楚git branch -d feature删的是本地分支git push origin --delete feature删的是远端分支。两者互不影响。删远端分支前确认这个分支上没有别人还在依赖的提交尤其是那种临时分支推上去给同事 review的场景删之前最好在群里说一声。注意删除远端分支后其他协作者本地的origin/feature跟踪分支不会自动消失他们需要执行git fetch --prune或git remote prune origin来清理。这个清理动作不会删他们的本地feature分支只是清掉过期的远端跟踪引用。3.4 --all 与 --branches批量推送的边界--all推送所有本地分支到远端--branches推送所有本地分支不含标签。这两个参数在初始化一个新远端仓库时有用本地攒了一堆分支一次性推上去。git push --all origin但日常开发中我几乎不用它们。原因很简单批量推送意味着你放弃了对推什么的控制。本地可能有一些实验性分支、临时备份分支--all会一股脑全推上去远端仓库瞬间变得杂乱。更稳妥的做法是逐个分支git push -u推哪些、什么时候推心里有数。--tags是另一个批量参数推送所有本地标签。标签推送有个特点默认情况下git push不会推标签必须显式加--tags或单独推某个标签。这个设计是为了避免误推临时标签。如果你只想推一个标签用git push origin v1.0.0这种形式。3.5 --dry-run推之前先彩排--dry-run简写-n不实际推送只打印如果执行会做什么。这个参数在两种情况下特别有用一是不确定当前配置下裸 push 会推什么二是准备强推或删分支前想确认目标。git push --dry-run git push --dry-run --force-with-lease origin feature输出会列出每个引用的更新方向新建、快进、强制、删除但不发送任何数据。养成危险操作前先 dry-run的习惯能挡掉相当一部分误操作。我自己的流程里凡是涉及--force或--delete的命令都会先跑一遍--dry-run看一眼目标分支名对不对。3.6 --no-verify跳过钩子的代价--no-verify跳过 push 阶段的钩子pre-push。有些团队在pre-push里挂了代码检查、单元测试、提交信息校验--no-verify能绕过这些检查直接推。git push --no-verify我的态度很明确除非你完全清楚自己在绕过什么否则不要用。pre-push钩子存在的意义就是在代码离开本地前做最后一道拦截绕过它等于把问题推给 CI 或者更后面的环节。真遇到钩子误报正确做法是修钩子或临时禁用钩子文件而不是养成随手--no-verify的习惯。这个参数我一年用不到两次每次用都记着事后补检查。4. 引用规格refspecpush 参数里的进阶武器4.1 refspec 的语法结构前面讲的都是选项参数git push还有一类更底层的参数叫引用规格refspec直接写在命令末尾格式是源引用:目标引用比如git push origin main:refs/heads/release表示把本地main推到远端的release分支。冒号左边是本地右边是远端这个方向别搞反。refspec 的强大之处在于它能精确控制哪个本地引用映射到哪个远端引用这是-u和裸 push 做不到的。常见用法包括推本地分支到不同名的远端分支、推某个提交到远端分支、删除远端引用目标为空。4.2 用 refspec 实现跨分支推送假设你在本地main上做了个紧急修复想直接推到远端的hotfix分支但不想切换分支git push origin main:hotfix这条命令把本地main的当前提交推到远端hotfix。如果远端hotfix不存在会新建如果存在且能快进会更新如果不能快进会拒绝。这种用法在紧急修复场景很实用省去了切分支、推、切回来的来回。但要小心它不会建立追踪关系也不会改变你当前所在的分支。推完之后本地main和远端hotfix是两个独立的东西别搞混。4.3 带 前缀的强制 refspecrefspec 前面加表示强制更新等价于对这个引用使用--forcegit push origin main:hotfix这个写法的粒度比--force更细--force作用于整条命令的所有引用而只作用于它修饰的那一个 refspec。当你一次推多个引用、只想对其中一个强推时这个区别就很重要。不过说实话日常手动操作里我很少用前缀因为--force-with-lease的安全性更好。更适合脚本里对特定引用做精确控制手动场景下容易看漏那个加号。4.4 空源引用与删除的等价关系前面提过git push origin :feature等价于删除远端feature。这里的原理是冒号左边为空表示推一个空值过去远端收到空值就理解为删除该引用。这个语法在批量删除时能派上用场git push origin :feature-a :feature-b :feature-c一条命令删多个远端分支。但同样地删之前务必--dry-run确认别把还在用的分支误删了。我个人更倾向用--delete逐个删可读性和安全性都更好批量删除的场景其实很少。5. 推送失败的排查与实战避坑5.1 常见拒绝原因速查push 被拒是家常便饭关键是快速定位原因。下面这张表覆盖了我遇到过的绝大多数情况报错关键词原因处理方式non-fast-forward远端有你本地没有的提交先git pull --rebase再推fetch first同上远端领先先 fetch 查看差异再决定protected branch分支受保护禁止直接推走合并请求流程pre-receive hook declined远端钩子校验失败看钩子输出通常是规范问题remote rejected远端策略拒绝联系仓库管理员确认规则failed to push some refs通用失败提示往上翻具体是哪个引用失败non-fast-forward是最常见的。它的本质是远端分支有你本地没有的提交直接推会造成历史分叉。正确做法是先同步git pull --rebase origin main把远端提交拉到本地并变基解决冲突后再推。不要一看到这个报错就--force那是在用覆盖别人的方式掩盖同步问题。5.2 强推之后如何补救万一真的强推覆盖了别人的提交别慌Git 的对象还在远端仓库里只是引用不指向它们了。补救思路是找到被覆盖前的提交哈希重新推一个引用指向它。具体操作让被覆盖的同事在他本地用git reflog找到他最后一次推送的提交哈希然后你或者他执行git push origin 被覆盖的提交哈希:refs/heads/recover-branch先把丢失的提交挂到一个临时分支上保住再决定怎么合并回主分支。这个操作的前提是那个提交对象还没被远端的垃圾回收清理掉所以发现覆盖后要尽快处理别拖太久。实操心得团队里应该约定强推只允许发生在个人分支共享分支main、develop 这类一律禁止强推用仓库的分支保护规则从服务端强制。光靠口头约定不够服务端规则才是最后一道防线。5.3 推送大文件被拒的处理有时候 push 被拒是因为提交里混进了大文件超过了远端的大小限制。报错通常包含file is too large或exceeds之类的字样。这种情况不能靠改 push 参数解决因为问题在提交历史里。处理思路分两步先把大文件从历史中移除用git filter-repo这类工具重写历史再强推。重写历史是破坏性操作务必在个人分支上做做完确认无误再推。如果大文件已经在共享分支的历史里需要团队协调统一重写后所有人重新克隆这个成本很高所以预防比补救重要提交前用git status和git diff --stat看一眼别把构建产物、数据集、视频文件误提交进去。5.4 推送超时与网络问题的应对推送大仓库或网络不稳定时可能遇到超时。可以调整一些传输相关的配置来缓解git config http.postBuffer 524288000 git config http.lowSpeedLimit 1000 git config http.lowSpeedTime 60第一行把 HTTP 传输缓冲区调大到约 500MB第二三行设置低速阈值和超时时间。这些配置对 HTTPS 协议下的推送有效能缓解推一半卡住的问题。但要注意调大缓冲区只是缓解症状如果仓库本身巨大根本方案还是拆分仓库或改用更合适的传输方式。注意这些配置是本地行为不影响远端。调完之后如果还是超时问题多半在网络链路或远端负载不是本地配置能解决的。6. 把参数用对的几个习惯6.1 推送前的三秒自检我现在每次 push 前会花三秒做三件事git status看有没有漏提交或误提交的文件git log origin/main..HEAD --oneline看这次要推几个提交、都是什么内容git push --dry-run确认目标分支和更新方向。这三步加起来不到十秒但挡掉过好几次推错分支和把调试代码推上去的事故。尤其是git log origin/main..HEAD这个命令它列出的是本地有而远端没有的提交正好就是这次 push 会带上去的内容。养成推前看一眼的习惯比事后回滚省事得多。6.2 分支保护与个人习惯的配合服务端的分支保护规则禁止强推、要求 review、要求 CI 通过是团队层面的安全网但个人习惯才是第一道防线。我的做法是共享分支永远不用--force个人分支强推前必--dry-run删远端分支前必确认分支名新分支首次推送必带-u。这几条规则简单到可以背下来执行成本几乎为零但能避免绝大多数 push 相关的翻车。参数是工具工具本身没有对错关键在于用的人清不清楚每个参数在什么条件下安全、什么条件下危险。--force不是洪水猛兽--force-with-lease也不是万能护身符理解它们背后的引用更新模型才能在对的场景用对的参数。6.3 团队协作中的推送约定最后说点协作层面的经验。一个团队如果对 push 行为没有共识光靠个人小心是不够的。我们团队的做法是在仓库配置里把push.default统一设为simple共享分支开保护个人分支命名带开发者标识前缀强推只允许在个人分支上发生。这些约定写进仓库的贡献指南新人入职第一件事就是读一遍。参数层面的知识最终要落到协作规范上才有价值。你一个人把--force-with-lease用得出神入化抵不过团队里有人随手--force一次。所以我在带新人的时候讲 push 参数的同时一定会讲清楚哪些分支能强推、哪些不能这比单纯记参数重要得多。这套东西我用了几年push 相关的意外基本绝迹。参数本身不难难的是把什么时候该用哪个变成肌肉记忆。多练几次 dry-run多看一眼推送内容慢慢就顺了。
1. 为什么单独把 git push 的参数拎出来讲很多人用 Git 用了两三年git push这条命令翻来覆去就敲过两种形态git push和git push origin master。日常提交代码确实够用可一旦碰上多人协作、分支策略调整、误提交回滚、CI 流水线配置这些场景光靠这两条命令就会开始抓瞎。我见过不少同事在推送失败时第一反应是删本地仓库重新克隆其实问题往往就出在 push 的参数没配对。git push的参数体系是整个 Git 命令里最容易被低估的一块。它不像git rebase那样有炫技感也不像git log那样天天被翻但它直接决定了你本地的提交以什么方式、推到哪个远端、覆盖还是拒绝、要不要顺带建立追踪关系。这些决策一旦出错轻则推送被拒重来一遍重则把别人的提交冲掉或者把不该公开的分支推上去。这篇内容面向的是已经能完成日常提交、但对 push 行为缺乏掌控感的开发者。我会把git push的参数按使用场景拆开讲重点放在那些知道的人觉得理所当然、不知道的人反复踩坑的地方。每个参数我都会说清楚它解决什么问题、背后的机制是什么、什么情况下该用、什么情况下千万别用。读完之后你应该能对着任意一次推送需求快速组合出正确的参数而不是靠试。需要先说明一点push 的参数在不同 Git 版本间有细微差异下面涉及的参数以当前主流稳定版本为准个别较新的参数我会标注适用条件。另外所有示例里的远端名统一用origin分支名用main和feature这类通用命名你可以直接替换成自己项目里的实际名称。2. push 的基本模型先搞清楚它在推什么2.1 一次 push 到底发生了什么在讲参数之前得先把 push 的底层动作说清楚否则参数讲再多也是死记硬背。git push的本质是一次引用更新请求本地 Git 把某个分支或标签当前指向的提交对象连同它背后缺失的对象一起打包发送给远端然后请求远端把对应的引用从旧值更新为新值。这里的关键词是引用更新。远端并不是简单地接收文件它是在做一次带条件的引用替换。远端会检查你要更新的这个引用当前值是不是你声明的旧值如果是允许更新如果不是说明期间有人推过拒绝。这个机制叫快进检查fast-forward check是 push 安全性的根基。理解了这个模型很多参数就好解释了。--force是让远端跳过旧值校验直接覆盖--force-with-lease是让你自己声明一个我认为远端旧值是什么远端拿这个值去比对对不上就拒绝--delete是把更新目标变成一个空引用等价于删除。所有参数本质上都在调整这次引用更新请求的条件和范围。2.2 本地分支、远端分支与追踪关系新手最容易混淆的是三个东西本地分支、远端跟踪分支、远端分支。本地分支main是你工作的地方远端跟踪分支origin/main是本地对远端 main 上次长什么样的缓存远端分支是远端仓库里真实存在的main。git push默认行为依赖追踪关系upstream。当你git clone或git push -u之后本地分支会记住它的 upstream 是哪个远端的哪个分支。有了追踪关系直接敲git push就知道往哪推没有追踪关系Git 会报错让你显式指定或者根据push.default配置猜一个。这个设计的意义在于push 的目标不该靠猜。追踪关系是一份显式契约写清楚了这个本地分支对应远端哪个分支。后面讲-u参数时你会看到建立追踪关系本身就是一次 push 的副产品。2.3 push.default 配置决定了裸 push 的行为在不带任何参数敲git push时Git 到底推什么由push.default这个配置决定。这个配置有几个常见取值理解它们能避免很多我明明只想推当前分支怎么推了一堆东西上去的困惑。取值行为适用场景simple只推当前分支到它的 upstream且要求两边分支名相同现代 Git 默认值最安全current只推当前分支到同名远端分支分支名规范统一的团队matching推送所有本地与远端同名的分支老项目、多分支同步nothing裸 push 直接报错必须显式指定强制显式操作防误推simple和current的区别很微妙simple要求本地分支名和 upstream 分支名一致current则允许推到不同名的远端分支。大多数团队用默认的simple就够了。如果你的团队分支命名有前缀规范比如本地叫feature-login远端要求叫login那current配合显式 upstream 会更顺手。我个人的建议是永远不要用matching。它会在你只想推一个分支时把所有同名分支一起推上去在多分支并行开发时极易造成意外推送。这个配置是历史遗留现代项目没有理由再用。3. 常用参数逐个拆从安全到激进3.1 -u / --set-upstream一次推送长期省事-u大概是git push里性价比最高的参数。第一次推送一个新分支时用它Git 会在推送成功后把本地分支的 upstream 设置为对应的远端分支之后直接git push和git pull都不用再带远端和分支名。git push -u origin feature这条命令做了两件事把本地feature推到远端origin/feature然后建立追踪关系。之后你在feature分支上敲git pushGit 就知道往origin/feature推。这里有个细节值得说-u建立的是双向追踪关系push 和 pull 都受益。很多人只知道它对 push 有用其实git pull不带参数能正常工作靠的也是这个 upstream。所以新分支第一次推送时带上-u是一个几乎无成本的好习惯。注意如果远端已经存在同名分支且历史不一致-u推送会失败。这时候不要急着加--force先搞清楚远端那个分支是什么来路是不是别人正在用的分支。3.2 --force 与 --force-with-lease强推的正确姿势--force是 push 参数里最危险的一个它让远端无条件接受你的引用更新跳过快进检查。什么时候真的需要它典型场景是本地历史被改写过你做了git rebase、git commit --amend、或者git reset回退了提交本地分支的提交链和远端已经分叉普通推送会被拒绝这时候才需要强推。但--force的问题在于它太粗暴如果在你 rebase 期间别人往同一个远端分支推了新提交你的强推会把这些提交直接冲掉而且没有任何提示。这就是所谓的覆盖别人的工作。--force-with-lease就是为解决这个问题设计的。它的逻辑是我强推但前提是远端的当前值必须等于我本地记录的origin/分支值。如果期间有人推过我本地的origin/分支缓存就过期了比对不上推送被拒绝。git push --force-with-lease origin feature这条命令的语义是如果远端 feature 还是我上次看到的那个样子就覆盖它如果变了就拒绝并告诉我。它把覆盖别人提交的风险从无条件变成了有条件。实操心得--force-with-lease有一个坑——如果你在强推前执行过git fetch本地的origin/分支缓存会被更新成远端最新值这时候 lease 检查就形同虚设了。所以强推前不要 fetch让缓存保持你记忆中的远端状态这样 lease 才有保护意义。这个细节很多人不知道导致以为用了 lease 就万无一失。还有一个更严格的变体--force-with-lease分支:期望的提交哈希可以显式指定你期望的远端值适合脚本化场景。日常手动操作一般用不带参数的版本就够。3.3 --delete删远端分支别用错命令删除远端分支有两种写法效果一样git push origin --delete feature git push origin :feature第二种是第一种的简写冒号左边为空表示推一个空引用过去等价于删除。我建议用--delete可读性好不容易看错。这里要区分清楚git branch -d feature删的是本地分支git push origin --delete feature删的是远端分支。两者互不影响。删远端分支前确认这个分支上没有别人还在依赖的提交尤其是那种临时分支推上去给同事 review的场景删之前最好在群里说一声。注意删除远端分支后其他协作者本地的origin/feature跟踪分支不会自动消失他们需要执行git fetch --prune或git remote prune origin来清理。这个清理动作不会删他们的本地feature分支只是清掉过期的远端跟踪引用。3.4 --all 与 --branches批量推送的边界--all推送所有本地分支到远端--branches推送所有本地分支不含标签。这两个参数在初始化一个新远端仓库时有用本地攒了一堆分支一次性推上去。git push --all origin但日常开发中我几乎不用它们。原因很简单批量推送意味着你放弃了对推什么的控制。本地可能有一些实验性分支、临时备份分支--all会一股脑全推上去远端仓库瞬间变得杂乱。更稳妥的做法是逐个分支git push -u推哪些、什么时候推心里有数。--tags是另一个批量参数推送所有本地标签。标签推送有个特点默认情况下git push不会推标签必须显式加--tags或单独推某个标签。这个设计是为了避免误推临时标签。如果你只想推一个标签用git push origin v1.0.0这种形式。3.5 --dry-run推之前先彩排--dry-run简写-n不实际推送只打印如果执行会做什么。这个参数在两种情况下特别有用一是不确定当前配置下裸 push 会推什么二是准备强推或删分支前想确认目标。git push --dry-run git push --dry-run --force-with-lease origin feature输出会列出每个引用的更新方向新建、快进、强制、删除但不发送任何数据。养成危险操作前先 dry-run的习惯能挡掉相当一部分误操作。我自己的流程里凡是涉及--force或--delete的命令都会先跑一遍--dry-run看一眼目标分支名对不对。3.6 --no-verify跳过钩子的代价--no-verify跳过 push 阶段的钩子pre-push。有些团队在pre-push里挂了代码检查、单元测试、提交信息校验--no-verify能绕过这些检查直接推。git push --no-verify我的态度很明确除非你完全清楚自己在绕过什么否则不要用。pre-push钩子存在的意义就是在代码离开本地前做最后一道拦截绕过它等于把问题推给 CI 或者更后面的环节。真遇到钩子误报正确做法是修钩子或临时禁用钩子文件而不是养成随手--no-verify的习惯。这个参数我一年用不到两次每次用都记着事后补检查。4. 引用规格refspecpush 参数里的进阶武器4.1 refspec 的语法结构前面讲的都是选项参数git push还有一类更底层的参数叫引用规格refspec直接写在命令末尾格式是源引用:目标引用比如git push origin main:refs/heads/release表示把本地main推到远端的release分支。冒号左边是本地右边是远端这个方向别搞反。refspec 的强大之处在于它能精确控制哪个本地引用映射到哪个远端引用这是-u和裸 push 做不到的。常见用法包括推本地分支到不同名的远端分支、推某个提交到远端分支、删除远端引用目标为空。4.2 用 refspec 实现跨分支推送假设你在本地main上做了个紧急修复想直接推到远端的hotfix分支但不想切换分支git push origin main:hotfix这条命令把本地main的当前提交推到远端hotfix。如果远端hotfix不存在会新建如果存在且能快进会更新如果不能快进会拒绝。这种用法在紧急修复场景很实用省去了切分支、推、切回来的来回。但要小心它不会建立追踪关系也不会改变你当前所在的分支。推完之后本地main和远端hotfix是两个独立的东西别搞混。4.3 带 前缀的强制 refspecrefspec 前面加表示强制更新等价于对这个引用使用--forcegit push origin main:hotfix这个写法的粒度比--force更细--force作用于整条命令的所有引用而只作用于它修饰的那一个 refspec。当你一次推多个引用、只想对其中一个强推时这个区别就很重要。不过说实话日常手动操作里我很少用前缀因为--force-with-lease的安全性更好。更适合脚本里对特定引用做精确控制手动场景下容易看漏那个加号。4.4 空源引用与删除的等价关系前面提过git push origin :feature等价于删除远端feature。这里的原理是冒号左边为空表示推一个空值过去远端收到空值就理解为删除该引用。这个语法在批量删除时能派上用场git push origin :feature-a :feature-b :feature-c一条命令删多个远端分支。但同样地删之前务必--dry-run确认别把还在用的分支误删了。我个人更倾向用--delete逐个删可读性和安全性都更好批量删除的场景其实很少。5. 推送失败的排查与实战避坑5.1 常见拒绝原因速查push 被拒是家常便饭关键是快速定位原因。下面这张表覆盖了我遇到过的绝大多数情况报错关键词原因处理方式non-fast-forward远端有你本地没有的提交先git pull --rebase再推fetch first同上远端领先先 fetch 查看差异再决定protected branch分支受保护禁止直接推走合并请求流程pre-receive hook declined远端钩子校验失败看钩子输出通常是规范问题remote rejected远端策略拒绝联系仓库管理员确认规则failed to push some refs通用失败提示往上翻具体是哪个引用失败non-fast-forward是最常见的。它的本质是远端分支有你本地没有的提交直接推会造成历史分叉。正确做法是先同步git pull --rebase origin main把远端提交拉到本地并变基解决冲突后再推。不要一看到这个报错就--force那是在用覆盖别人的方式掩盖同步问题。5.2 强推之后如何补救万一真的强推覆盖了别人的提交别慌Git 的对象还在远端仓库里只是引用不指向它们了。补救思路是找到被覆盖前的提交哈希重新推一个引用指向它。具体操作让被覆盖的同事在他本地用git reflog找到他最后一次推送的提交哈希然后你或者他执行git push origin 被覆盖的提交哈希:refs/heads/recover-branch先把丢失的提交挂到一个临时分支上保住再决定怎么合并回主分支。这个操作的前提是那个提交对象还没被远端的垃圾回收清理掉所以发现覆盖后要尽快处理别拖太久。实操心得团队里应该约定强推只允许发生在个人分支共享分支main、develop 这类一律禁止强推用仓库的分支保护规则从服务端强制。光靠口头约定不够服务端规则才是最后一道防线。5.3 推送大文件被拒的处理有时候 push 被拒是因为提交里混进了大文件超过了远端的大小限制。报错通常包含file is too large或exceeds之类的字样。这种情况不能靠改 push 参数解决因为问题在提交历史里。处理思路分两步先把大文件从历史中移除用git filter-repo这类工具重写历史再强推。重写历史是破坏性操作务必在个人分支上做做完确认无误再推。如果大文件已经在共享分支的历史里需要团队协调统一重写后所有人重新克隆这个成本很高所以预防比补救重要提交前用git status和git diff --stat看一眼别把构建产物、数据集、视频文件误提交进去。5.4 推送超时与网络问题的应对推送大仓库或网络不稳定时可能遇到超时。可以调整一些传输相关的配置来缓解git config http.postBuffer 524288000 git config http.lowSpeedLimit 1000 git config http.lowSpeedTime 60第一行把 HTTP 传输缓冲区调大到约 500MB第二三行设置低速阈值和超时时间。这些配置对 HTTPS 协议下的推送有效能缓解推一半卡住的问题。但要注意调大缓冲区只是缓解症状如果仓库本身巨大根本方案还是拆分仓库或改用更合适的传输方式。注意这些配置是本地行为不影响远端。调完之后如果还是超时问题多半在网络链路或远端负载不是本地配置能解决的。6. 把参数用对的几个习惯6.1 推送前的三秒自检我现在每次 push 前会花三秒做三件事git status看有没有漏提交或误提交的文件git log origin/main..HEAD --oneline看这次要推几个提交、都是什么内容git push --dry-run确认目标分支和更新方向。这三步加起来不到十秒但挡掉过好几次推错分支和把调试代码推上去的事故。尤其是git log origin/main..HEAD这个命令它列出的是本地有而远端没有的提交正好就是这次 push 会带上去的内容。养成推前看一眼的习惯比事后回滚省事得多。6.2 分支保护与个人习惯的配合服务端的分支保护规则禁止强推、要求 review、要求 CI 通过是团队层面的安全网但个人习惯才是第一道防线。我的做法是共享分支永远不用--force个人分支强推前必--dry-run删远端分支前必确认分支名新分支首次推送必带-u。这几条规则简单到可以背下来执行成本几乎为零但能避免绝大多数 push 相关的翻车。参数是工具工具本身没有对错关键在于用的人清不清楚每个参数在什么条件下安全、什么条件下危险。--force不是洪水猛兽--force-with-lease也不是万能护身符理解它们背后的引用更新模型才能在对的场景用对的参数。6.3 团队协作中的推送约定最后说点协作层面的经验。一个团队如果对 push 行为没有共识光靠个人小心是不够的。我们团队的做法是在仓库配置里把push.default统一设为simple共享分支开保护个人分支命名带开发者标识前缀强推只允许在个人分支上发生。这些约定写进仓库的贡献指南新人入职第一件事就是读一遍。参数层面的知识最终要落到协作规范上才有价值。你一个人把--force-with-lease用得出神入化抵不过团队里有人随手--force一次。所以我在带新人的时候讲 push 参数的同时一定会讲清楚哪些分支能强推、哪些不能这比单纯记参数重要得多。这套东西我用了几年push 相关的意外基本绝迹。参数本身不难难的是把什么时候该用哪个变成肌肉记忆。多练几次 dry-run多看一眼推送内容慢慢就顺了。
