赵承铭很多开发者在本地用Git已经很熟练了：clone、commit、push、pull这些命令闭着眼睛都能敲。但真要给一个开源项目提交贡献时，第一反应往往是“我该把代码推到哪里去？”——你发现你根本没法直接往人家的仓库里push。你得先fork，再clone，再建分支，改完代码后推到自己的fork，最后发起Pull Request。很多人就卡在了这一连串流程里：fork和clone到底什么关系？为什么我不能直接在原仓库上开个分支？upstream又是什么鬼？
这篇文章就是为这些疑问准备的。我按自己的理解，把一套完整的、以“贡献”为目标的Git全流程拆开来讲，从环境安装配置讲起，到第一个Pull Request被合并，再到长期维护一个fork的同步策略。它适合谁看？适合那些已经会基本Git命令、但还没完整走通过一次开源贡献流程的人；也适合已经提交过PR、但被维护者要求“请先rebase一下”之后不知道该怎么办的人。这套流程走一遍，你对Git的协作模型才算真正建立起来。
1. 为什么“会Git命令”和“会贡献”是两回事
1.1 你熟悉的Git其实是“小团队模式”
先说一个很多人没意识到的点：你平时在公司或个人项目里用的Git，和开源贡献时用的Git，本质上不是同一套协作模型。
在公司里，通常大家共享同一个远程仓库，每个人都有push权限。你要加功能就git checkout -b feature-xxx，改完git push origin feature-xxx，然后直接在GitLab或GitHub上发起Merge Request或Pull Request让同事review。别人review完，点击合并，完事。
这套流程里，所有分支都活在同一个远程仓库里。你不需要fork，因为你本来就有写权限。
但开源项目不是这样的。绝大多数开源项目，维护者不可能给全世界每个想贡献的人开放写权限。所以平台方设计了一套更稳妥的模型：你想贡献，先在我的仓库旁边复制一份完全属于你的仓库副本，这个动作就叫fork；你在你的副本上随便折腾，改好了，再发起一个请求，请维护者“把你的改动拉回去”。这个请求就是Pull Request。
1.2 开源贡献用的是“fork + PR”模型
所以，一旦进入开源贡献场景，你的本地Git仓库要同时面对三个“仓库”：
- 本地仓库：你clone下来并正在编辑代码的那个目录。
- 你的远端仓库（origin）：你fork出来的、属于你自己的GitHub/GitLab/Gitee仓库。你有完全写权限。
- 上游仓库（upstream）：项目官方维护的那个原始仓库。你只有读权限，除非你的PR被合并。
这三者之间的关系，是理解整个贡献流程的地基。很多新人在看到git remote -v输出两行地址时就开始晕了，其实只要记住一个核心原则：你往origin推，你从upstream拉，你的PR是从origin指向upstream的“申请”。
1.3 全流程里的隐藏要求
另外，这套流程对提交历史的要求，比小团队模式严格得多。在团队里你敲一个“fix bug”的commit message，同事碍于面子可能就merge了。但在开源项目里，维护者和审查者每天要面对几十上百个PR，他们没时间猜你想干什么。你的commit message写得不清不楚、你的PR描述没有交代测试情况、你的分支上堆了一堆“wip”、“haha”之类的提交……这些都会直接拉低你的PR被合入的概率。
所以“从入门到精通”的关键转折点，不是你掌握了多少Git命令，而是你有没有建立起一种意识：你的提交历史、PR描述，本质上是你写给维护者和未来贡献者的一份“沟通文档”。后面几节我会把每个环节怎么做都讲清楚。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：安装、身份配置与SSH密钥里最容易被忽略的三个细节
2.1 安装Git：不同系统的快速路径
这个部分虽然基础，但为了保证流程完整还是说一下。
- Windows：直接下载Git for Windows安装包，一路Next。装完后你会拥有Git Bash，这是Windows上体验最接近Linux终端的环境。
- macOS：推荐用Homebrew安装，
brew install git，比官网下载的dmg包更好管理版本。 - Linux：各发行版包管理器直接装就行，
sudo apt install git或sudo dnf install git。
装完之后验证一下：git --version，能输出版本号就OK。但注意，这只是开始。真正决定你后面能否顺畅提交PR的，是接下来几个配置项。
2.2 第一件事不是clone，而是配置身份
很多人clone完项目才发现，自己提交人的名字是“user”或者一串乱码，头像也不显示。问题出在最基础的两行配置上：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
这里有个很容易被忽略的点：user.name和user.email会作为提交作者信息永久写入Git历史里，开源项目里所有提交都是公开的。所以请务必用你确实想展示的名字，以及和你的代码托管平台账号绑定的邮箱。
比如你在GitHub上开启了“邮箱隐私保护”，GitHub会给你一个形如12345678+username@users.noreply.github.com的地址。如果你在本地配置的不是这个邮箱，而是自己的私人邮箱，那么提交记录里虽然也会显示名字，但和非隐私邮箱之间没有关联，绿格子可能都不亮。
还有一个小技巧：如果你想对不同的项目使用不同的身份，不要用--global，在某个仓库目录下单独配置：
bash复制git config user.name "公司ID"
git config user.email "公司邮箱"
--global是兜底用的，当前仓库的配置优先于全局配置。git config --list可以查看所有生效配置。
2.3 换行符配置：跨平台协作的隐形坑
这个坑我亲眼见过太多次了：Windows开发者提交了一个文件改动，维护者在Linux上一看，整个文件的每一行都被判为“已修改”，原因就是换行符不一致。
Git设计了一个自动转换机制：core.autocrlf。简单说：
- Windows上建议设置
git config --global core.autocrlf true。提交时会自动把CRLF转成LF再入库，检出时再转回CRLF。 - macOS/Linux上建议设置
git config --global core.autocrlf input。提交时转成LF，检出时不转换。
现在GitHub、GitLab也支持在仓库根目录放一个.gitattributes文件来统一规则，但对你个人来说，先把core.autocrlf配好，能少掉一半莫名其妙的冲突。
2.4 SSH密钥：让推送不再反复输密码
如果你用HTTPS方式克隆仓库，每次push都要输入用户名和密码（现在通常是个人访问令牌），非常影响体验。所以我强烈建议配置SSH密钥。
生成密钥：
bash复制ssh-keygen -t ed25519 -C "你的邮箱"
一路回车即可。然后查看公钥：
bash复制cat ~/.ssh/id_ed25519.pub
把输出的内容复制到GitHub/GitLab的Settings -> SSH Keys里。测试连通性：
bash复制ssh -T git@github.com
能收到一条类似“Hi xxx! You've successfully authenticated”的提示就说明通了。
如果你有多台设备或者多个平台账号，还可以在~/.ssh/config里配置多个密钥，比如：
bash复制Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
Host gitlab.com
HostName gitlab.com
User git
IdentityFile ~/.ssh/id_ed25519_gitlab
配好之后，clone地址一定要选SSH格式，比如git@github.com:用户名/仓库名.git，而不是HTTPS格式。
3. fork + clone + branch：贡献流程的骨架是怎么搭起来的
3.1 fork到底做了什么
很多初学者以为fork是“复制仓库到我的账号下，然后我随便改”。这个理解大体不错，但容易漏掉一个关键点：fork不是在本地发生的操作，而是在代码托管平台（GitHub/GitLab等）上发生的一次远程复制。
操作上，你在项目主页点一下Fork按钮，平台就会在你的账号下生成一个原始仓库的完整快照副本。这个副本有自己独立的地址，你对它有完全的管理权限，哪怕你把fork里的主分支删了，也不会影响原始项目。
这一步的意义在于：你拥有了一个可以自由推拉、随意改写历史、不怕搞坏任何东西的“沙盒”。
3.2 双远程模型：origin 和 upstream
点完Fork之后，你账号下多了一个仓库。原来的项目官方仓库称为“上游”，你的副本就是“自己的远程仓库”。
然后把你的fork clone到本地：
bash复制git clone git@github.com:你的用户名/项目名.git
cd 项目名
这时候你的本地仓库只会自动配置一个远程地址——origin，它指向你的fork。但为了和上游保持同步，你需要手动添加上游：
bash复制git remote add upstream git@github.com:原作者名/项目名.git
然后你可以用git remote -v查看，输出应该是这样：
bash复制origin git@github.com:你的用户名/项目名.git (fetch)
origin git@github.com:你的用户名/项目名.git (push)
upstream git@github.com:原作者名/项目名.git (fetch)
upstream git@github.com:原作者名/项目名.git (push)
两个人的命名习惯可能不同，请务必记住这条约定：origin = 你的fork，upstream = 官方仓库。后面所有“同步上游”的操作，都是在fetch upstream。
3.3 分支规范：为什么不能在默认分支上开发
这是我特别想强调的一件事：永远不要在你fork的main/master分支上直接开发。
原因有三个：
- 你的默认分支需要保持和上游“一模一样”。这样每次上游更新了，你可以直接rebase或merge upstream/main进来，不会因为你自己在默认分支上改过东西而产生复杂冲突。
- 维护者在review你的PR时，通常会看你的分支名和提交历史。一个叫
patch-1的随机分支，和一个叫fix/typo-in-readme的分支，给人的专业感完全不同。 - 如果你在默认分支上开发，后续一旦需要同步上游，很容易把两边的改动搅在一起，最后变成一场灾难。
所以规范做法是：每次开发前，先确保默认分支是干净的，然后基于它创建一个新的功能分支：
bash复制git checkout main
git pull upstream main
git checkout -b fix/typo-in-readme
关于分支命名，业界常用的语义化前缀这些：
| 前缀 | 用途 |
|---|---|
fix/ |
修复bug |
feature/ |
新功能 |
docs/ |
文档修改 |
refactor/ |
重构代码 |
chore/ |
构建、工具链等杂活 |
分支名要短小精悍，一眼能看出意图，比如fix/login-redirect-error比fixbug好一百倍。
4. 写一个让人愿意Review的Commit：提交信息与原子化拆分
4.1 维护者的“第一印象”就是你的提交历史
我自己维护过一些小型开源项目，说实话，看到那种提交历史全是Update file.py、fix、test、1、2、3的PR，真的是不想点开。你向一个项目提交PR，其实是在向维护者“推销”你的改动。一个乱七八糟的提交历史，会让维护者本能地觉得：这个人自己都搞不清楚自己在改什么，我不如直接把PR关掉。
所以“精通”的一个重要标志，就是你的提交记录能被任何人读懂。哪怕隔了半年，有人翻到你的某个commit，也能知道它当时是为什么而写的。
4.2 原子化提交：一个commit只做一件事
“原子化提交”（atomic commit）是贡献流程的第一课。意思是一个commit只包含一个逻辑上的改动，它可以独立地被应用、被回滚、被理解。
举个反例：你在一次改动中修了一个bug、重构了一个函数、还顺手改了几个拼写错误，这三个改动互相之间没有强关联，却在同一个commit里。将来如果bug修复需要被cherry-pick到发布分支，或者重构被证明有问题需要回滚，你就得把整个commit一起带走或一起回滚，非常被动。
正确做法是把这三件事拆成三个commit：
bash复制git add -p # 进入交互式暂存，按 hunk 选择要临时保存的代码块
git commit -m "fix: 修复登录后跳转地址错误"
git add -p # 继续选择下一个逻辑块
git commit -m "refactor: 抽取认证逻辑为独立模块"
git commit -m "docs: 修正注释中的拼写错误"
git add -p这个命令是做到原子化提交的关键工具。它允许你逐块（hunk）选择将哪些改动加入暂存区，而不是无脑git add .。刚开始用会有点不适应，但用熟了以后，你会发现它是你管理提交粒度最趁手的工具。
注意：git add -p 只在工作区改动已经存在的情况下有意义。如果你已经提前把文件整个 add 进暂存区了，先执行 `git reset` 把暂存区清空再操作。
4.3 commit message 怎么写
提交信息我推荐使用社区应用最广的Conventional Commits规范，格式如下：
code复制<type>(<scope>): <subject>
<空行>
<body>
<空行>
<footer>
type：提交类型，常见的有fix、feat、docs、refactor、chore、test等。scope：影响范围，比如模块名、组件名，可省略。subject：一句简短描述，命令式语气，不要超过50个字符。首字母不大写，结尾不加句号。body：说明为什么做这个改动、改动的思路、和之前的行为差异。footer：通常用来关联issue，比如Closes #123或Fixes #456。
一个合格的例子：
bash复制fix(auth): 修复登录后跳转地址错误
当用户通过OAuth登录成功后，被重定向到硬编码的首页，
而不是用户请求的原始地址。现在解析redirect参数并拼接到跳转URL。
Fixes #123
对比一下不合格的例子：
bash复制fix bug
你一眼就能感受到两者信息量的差距。对于开源项目的贡献者来说，Fixes #123还有另一个隐藏作用：PR合并时，那个关联的issue会被自动关闭，省掉了维护者手动关issue的时间，这是很受欢迎的行为。
4.4 提交前的自查
在push之前，我习惯先执行这几个命令自查一下：
bash复制git status # 确认没有遗漏或多余的文件
git log --oneline -5 # 确认提交历史清晰
git show --stat # 确认每个commit改动的文件符合预期
git diff --check # 检查是否有空白字符错误
git diff --check是一个特别容易被忽略但极其好用的命令，它能检测出行尾空白、文件末尾缺少换行符等问题。很多CI（持续集成）流程会专门检查这些，如果你在本地提前跑一遍，能避免一轮没必要的“push-失败-修改-再push”循环。
5. 从Pull Request到合并：与维护者打交道的完整链路
5.1 推送分支并创建PR
开发完并提交好commit之后，把分支推送到你的fork：
bash复制git push -u origin fix/login-redirect-error
-u参数会在推送的同时建立本地分支与远程分支的跟踪关系，之后你在本地执行git pull和git push都不用手动指定分支了。
推送完成后，GitHub/GitLab会在页面上弹出一个“Compare & pull request”的按钮。点进去，你会看到PR编辑页。这里要特别留意：base仓库选择和head仓库选择。
- base：你要合并进去的目标分支，通常是
上游仓库的main。 - head：你要被合并的来源，通常是
你fork的分支。
很多新手把base和head选择搞反了，导致PR方向错误，会被直接关闭。
5.2 PR描述的黄金结构
PR描述是维护者判断“要不要花时间看你的代码”的门面。我自己总结了一个比较实用的模板，一直在用：
markdown复制## 背景
（这里写清楚为什么要做这个改动，解决了什么问题）
## 改动内容
- （列出具体改了什么文件、什么模块）
- （如果改动较大，说明拆分的逻辑）
## 测试方式
- （列举你本地跑过的测试命令、手工验证步骤）
- （如果涉及UI改动，最好附上截图）
## 关联issue
Closes #123
其中“测试方式”这一栏，是我觉得最容易被新手忽略、但对维护者最有用的一项。哪怕你只是在文档里改了个拼写，也可以写“无需测试”；只要涉及代码改动，就尽量写清楚本地是怎么验证的。这样维护者做review时，心里会踏实很多。
如果你还在开发中、但想让维护者提前看到方向，可以先把PR标记为Draft（草稿），等代码完成后再点击Ready for review。这算一种沟通礼仪：不要让维护者花时间review一个半成品。
5.3 应对Review意见的正确姿势
PR发出去之后，大概率会收到几条review意见。这是贡献流程里最考验“人”的环节。
首先明确一点：维护者提意见，不是在否定你。他在免费花时间帮你把代码改得更好。所以回复的第一原则是礼貌和具体。
如果意见合理，直接在本地新建一个commit来修改，然后推送到同一个分支：
bash复制git add .
git commit -m "fix: 根据review意见调整错误处理逻辑"
git push
PR会自动更新，不需要重新创建一个PR。
如果某个意见你不同意，也可以回复解释你的思路，但语气要友好。比如：“根据我的测试，这里如果改为XXX方式，会导致XXX的问题。我保留当前写法是因为……。如果你仍然觉得不妥，我可以再调整。”
千万不要做的一件事：收到一堆review意见后，直接关掉旧PR、重新开一个新PR。这会让维护者之前review所花的时间全部作废，而且新PR会丢失所有讨论上下文。除非是分支被误删之类不可控的情况，否则请通过更新同一个分支来推进PR。
5.4 更新PR：追加commit，而不是重开PR
关于PR更新，我要特别说一下“不要随意用force push”这件事。
在PR的review过程中，理想的状态是：你每修改一轮，就追加一个普通的commit并push。这样维护者可以清楚地看到“这个PR经历了哪些迭代”，review的历史也能追溯到每一次具体改动。
沟通成本更低的做法其实是：在你的feature分支没有合并之前、并且确认没有人基于你这条分支做开发的情况下，你仍然可以做交互式rebase来整理提交历史，然后force push。但要遵守一条基本边界：force push只允许发生在你自己开的、尚未合并的feature分支上，绝对不要对共享分支（main、develop）执行强推。
什么时候适合做交互式rebase？比如你开发中途生成了十几个“wip”提交，在PR合并前整理成一两个语义清晰的commit。这是Git社区普遍认可的操作。但如果你的分支上每条commit都有清晰的review讨论记录，那我建议不要乱动，追加commit更安全。
5.5 处理冲突的标准流程
你的PR可能会和上游的新改动产生冲突。GitHub会显示“This branch has conflicts that must be resolved”。不要慌，这是正常现象。
推荐操作是先把上游最新代码合并或变基到你的分支：
bash复制git fetch upstream
git checkout fix/login-redirect-error
git rebase upstream/main
rebase的过程中如果出现冲突，Git会停下来，提示哪个文件冲突。你手动打开文件，搜索<<<<<<<、=======、>>>>>>>这些冲突标记，保留需要的代码，删除标记，然后：
bash复制git add 冲突文件
git rebase --continue
全部解决之后，因为你的提交历史被重写了，推送时需要强推：
bash复制git push --force-with-lease
这里我推荐用--force-with-lease而不是--force。前者在远程分支没有其他人新提交的情况下才会执行强推，是一个更安全的“保护锁”。
6. 长期维护fork的同步策略：rebase和merge到底怎么选
6.1 为什么fork会落后
如果你只贡献一次PR，fork落后不落后问题不大。但如果你想长期维护一个fork，比如给某个项目持续提交多个功能，或者你想基于上游项目做二次开发，那么“如何保持你的fork与上游同步”就成了每天都要面对的问题。
fork不是自动同步的。上游main分支新增的每个commit，都不会自动出现在你的fork里。时间一长，你的fork就会离上游越来越远，最终导致你的下一次PR产生大量冲突。
6.2 rebase vs merge：两种合入逻辑
同步上游合并的目标是：把我本地/我的fork落后于上游的那些提交，整合进来。两种主要方式：
- merge：把你的提交和上游提交合并，生成一个新的“合并提交”。历史会形成分叉再汇合的网状结构。
- rebase：把你的提交“摘下来”，接到上游最新提交的顶上，历史保持一条直线。
用生活化的比喻：merge像是在两个楼层之间搭了一个天桥；rebase像是把你从旧楼层“搬”到新楼层，原楼层不留痕迹。
对于个人开发的分支，推荐用rebase，因为历史更清晰。但需要注意：rebase会改写你本地提交的commit hash，所以一旦你的分支被别人拿来用了，就不能随意rebase了。
6.3 推荐的组合策略
我在自己的日常工作流里，用的是这样一套组合：
- 同步上游main到本地main时，用merge或rebase都可以。我更倾向于：
bash复制git checkout main
git pull upstream main --rebase
git push origin main
这里--rebase的作用是如果本地main有任何上游没有的commit（虽然一般不应该有），会直接把这些commit平移到上游最新代码之上，历史保持线性。如果本地main是干净的，那么rebase和merge的结果没有区别。
- 开发feature分支时，定期把上游main rebase进来：
bash复制git checkout feature/my-feature
git fetch upstream
git rebase upstream/main
这样你的feature分支始终基于上游最新代码，提交历史是干净的线性结构，PR合入时维护者几乎不需要处理额外冲突。
- 如果你需要保留“我什么时候合入了上游改动”的痕迹，或者你的协作伙伴也在同一个feature分支上开发，那就用merge：
bash复制git merge upstream/main
merge会保留分叉和合入点，适合多人共同开发、需要标记“合入时间点”的场景。
6.4 force push的边界
无论选择哪种同步策略，只要有rebase，几乎必然会出现“本地分支和远程分支历史不一致”的情况。这时推送就需要强推。
我强烈建议你在所有强推场景使用--force-with-lease：
bash复制git push --force-with-lease
它的含义是：只有当远程分支在我上次fetch之后没有被别人更新过，才允许强推。这样可以避免你用力过猛，把别人刚推上去的commit给覆盖掉。
关于force push的边界，总结下来就是：
| 场景 | 是否允许强推 |
|---|---|
| 你独占的feature分支，未合并 | 允许 |
| 你独占的feature分支，PR合并前整理历史 | 允许 |
| 多人协作的feature分支 | 尽量不推，若推需提前沟通 |
| 共享的main/develop等长期分支 | 绝对禁止 |
最后再分享一点我个人的体会
我最初给开源项目提PR，也干过“在main分支上直接改然后推到fork”这种事，结果维护者回了一句“please create a new branch”。我当时还挺委屈，觉得改都改完了，为什么不能收。后来自己维护项目，看到别人提交的PR分支乱七八糟、描述空白、commit全叫“update”时，才真正理解了维护者的心情。
其实整个Git贡献流程，核心不是命令的堆砌，而是“你如何降低他人的理解成本”。分支名清晰、commit信息规范、PR描述完整、review意见响应及时，这四件事做到位，你的代码甚至都不用特别完美，很多维护者都愿意帮你修。反过来，如果这四件事做不好，哪怕代码写得再好，review的门槛也会高很多。
如果你第一次走这个流程，不用急着追求完美。先把分支建对、commit message写清楚、PR描述填完整，走通一次，第二次你就会发现整个流程已经变成了肌肉记忆。之后再慢慢去琢磨rebase和merge的微妙差异、提交历史的整理技巧，这些都会水到渠成。