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 push，Git 就知道往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. 引用规格（refspec）：push 参数里的进阶武器
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 带 + 前缀的强制 refspec
refspec 前面加+表示强制更新，等价于对这个引用使用--force：
git 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，多看一眼推送内容，慢慢就顺了。
