first-contributions 实战：用 Git 三角工作流（Triangle Workflow）保持 Fork 与上游仓库同步-平芜编程栈

first-contributions 实战：用 Git 三角工作流（Triangle Workflow）保持 Fork 与上游仓库同步

【免费下载链接】first-contributions🚀✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions

本篇技术指南以 first-contributions 项目的葡萄牙语巴西版同步教程 keeping-your-fork-synced-with-this-repository.pt_br.md 为骨架，完整讲解开源协作中最常见也最重要的操作——当上游项目不断前进时，如何通过fetch、rebase、push三个命令，让你的本地仓库与 GitHub Fork 始终跟上主仓库的节奏。读完本文，你将掌握 Git 三角工作流的原理、可逐行复制的同步命令序列，以及围绕同步衍生出的分支、rebase/merge 取舍、冲突处理等进阶知识，为持续参与开源贡献打下坚实基础。

先理解三角工作流：同步的本质是"三个仓库的接力"

在讨论命令之前，先要建立一张全局地图。正如教程开头强调的，一次完整的同步涉及三个不同的仓库（参见英文原版 keeping-your-fork-synced-with-this-repository.md）：

上游公开仓库（upstream）：项目维护者的公开仓库，例如 first-contributions 的主仓库。它是所有提交的"源头"。
你的 GitHub Fork（origin）：你在 GitHub 上点击 Fork 按钮生成的个人副本。只有通过它才能发起 Pull Request（详见仓库根目录 README.md 中的 fork → clone → 修改 → push → PR 主流程）。
你的本地仓库（local）：你通过git clone拉取到本机、真正写代码的工作目录。

这种"一源两副本"的协作形态是开源项目的典型特征，被称为Triangle Workflows（三角工作流）。同步的方向是有严格顺序的，绝不能跳步：

上游公开仓库（upstream） │ │ ① fetch（拉取到本地） │ ② rebase/merge（合并到本地主分支） ▼ 本地仓库（local） │ │ ③ push（推送到你的 Fork） ▼ 你的 GitHub Fork（origin）

教程特别点明了为什么Fork 必须最后更新：Pull Request 只能从你的 Fork 发起，所以只有当你把本地的更新推送到 Fork 之后，GitHub 上的 Fork 才具备发起新 PR 的资格。这也是"上游 → 本地 → Fork"单向传动的根本原因。

分支命名说明：葡萄牙语巴西版教程写作时仓库默认分支为master（命令为git checkout master、git rebase upstream/master），而当前英文原版与 first-contributions 主仓库已迁移到main（命令为git checkout main、git rebase upstream/main）。执行时请以你自己仓库的实际默认分支名为准（用git branch即可查看），本文以下统一按main讲解，并保留两版对应的命令写法。

同步前的状态检查：确认你站在正确的分支上

教程给出的第一步是确认当前分支。在终端执行：

git status

输出结果的第一行会明确显示当前所在分支，例如On branch main。如果你不在主分支上，先切换过去：

git checkout main

# 若你的仓库默认分支是 master（对应葡语版教程） git checkout master

为什么要强调"必须在主分支"？原因有两层：其一，同步操作会把上游最新提交合并进当前分支，如果你正开着一个功能分支，这些提交会串进你的功能分支，污染干净的提交历史；其二，主分支（main/master）是唯一需要与上游保持一致的分支。关于分支隔离的重要性，可参考仓库内 why-using-branches.md：分支是独立的开发线，一个分支对应一个功能，才能让多人协作互不干扰。

第一步：把上游仓库注册为`upstream`远程

大多数情况下，你克隆的是自己的 Fork，因此本地仓库只认识origin这一个远程。要让 Git 认识"官方主仓库"，需要把它添加为第二个远程，并约定俗成地命名为upstream：

git remote add upstream https://github.com/firstcontributions/first-contributions.git

（葡语版教程对应的地址为https://github.com/Roshanjossey/first-contributions，请以项目当前的官方仓库地址为准。）

这条命令的本质是告诉 Git："在指定的 URL 上存在这个项目的另一个版本，我们把它叫做upstream。" 它只做登记，不下载任何数据。添加后可以用以下命令核对远程配置，确认origin指向你的 Fork、upstream指向官方仓库：

git remote -v

该验证手法也出现在仓库 README.md 的推送认证错误排查小节中——当你怀疑远程地址配错（例如仍然指向https://而非 SSH）时，第一步就是运行git remote -v检查。

第二步：用`git fetch upstream`拉取上游更新

git fetch upstream

fetch会把upstream远程上所有分支的新提交、新标签下载到本地，但不会改动你当前的工作区与分支指针——它只是把上游的提交对象原样搬进你的对象库，并更新upstream/main这类远程跟踪分支。这也是fetch与pull的根本区别：fetch是"只看不动"，安全无副作用。

拉取完成后，你可以先"预览"上游到底多了哪些提交，再决定如何合并。仓库内的 check-commit-log.md 提供了查看提交历史的实用命令，例如：

# 查看最近 5 条提交 git log -n 5 # 查看特定文件的提交历史 git log --all <文件名>

从git log的输出中，你能看到upstream/main、origin/main、main这些引用各自指向哪个提交，从而直观判断"本地落后了上游几个提交"。

第三步：用`git rebase upstream/main`合并上游更新

git rebase upstream/main

（葡语版：git rebase upstream/master）

这一步把刚刚 fetch 到的上游提交"垫"到你的主分支之下，使你的本地main以最新上游状态为基底。教程称之为把公开仓库合并进你的主分支。执行后，本地main即与上游完全同步。

这里有必要展开rebase与merge的取舍，因为这是同步场景最容易困惑的点。仓库内的 rebase-vs-merge.md 给出了权威对照：

维度	Merge（合并）	Rebase（变基）
历史形态	保留真实的时间先后关系	形成线性的干净历史
额外提交	产生一个额外的 merge commit	不产生额外提交
可读性	合并提交多了会显得杂乱	更易阅读和追踪
适用场景	公共分支（如`main`）之间的整合	个人/功能分支上的整合

该文档还给出了一条铁律：永远不要 rebase 公共共享分支（如main）。因为 rebase 会重写提交历史，会让其他基于这些提交协作的人陷入混乱。正确的姿势是"把个人分支 rebase 到 main 之上"，而不是反过来。

那么在同步场景中，为什么教程推荐git rebase upstream/main而不是git merge upstream/main？原因在于：你 fork 出来的main在多数情况下只有你自己在推进（上游的提交会定期流入，但你的本地 main 通常只承载已合并回上游的内容或极少的本地改动），它更接近"个人分支"的属性。用 rebase 可以保持历史线性，避免产生无意义的 merge commit，让后续基于 fork 发起的 PR 干净利落。如果你更习惯 merge 的语义，也可以改用git merge upstream/main，两者都能达成"本地与上游同步"的目标，区别只体现在提交历史上。

另外，如果你希望 Git 在拉取时默认采用某种整合策略，可以在 rebase-vs-merge.md 的指引下做全局配置：

# 默认行为：拉取时用 merge git config pull.rebase false # 推荐：拉取时默认 rebase，保持历史线性（建议加 --global 全局生效） git config --global pull.rebase true

关于冲突：如果本地main与上游对同一处内容都有修改，rebase 会中断并提示冲突。此时不必惊慌，仓库内的 resolving-merge-conflicts.md 专门讲解了冲突文件的标记格式与解决流程：编辑文件消除<<<<<<<、=======、>>>>>>>标记 →git add标记为已解决 →git rebase --continue继续。由于本项目要求贡献者把名字加入 Contributors.md 文件，不同贡献者的改动通常不会重叠，冲突概率很低，但掌握解决方法是进阶必修课。

第四步：用`git push origin main`更新你的 GitHub Fork

git push origin main

（葡语版：git push origin master）

本地已与上游同步，最后一步是把成果推送到你的 Fork。注意这里的远程是origin——即你在 GitHub 上的 Fork，而不是upstream。教程特意强调："注意，这里你是在向名为origin的远程仓库推送。"推送完成后，三个仓库全部处于同一状态，你的 GitHub Fork 上会显示 "This branch is up to date"，下次发起 Pull Request 时对比基准也不会落后。

快捷方式：`git pull upstream main`一步到位

教程末尾还给出了一个等价快捷方式：

git pull upstream main

git pull本质上是git fetch+ 整合（merge 或 rebase，取决于上文配置）的组合命令。如果你不想分两步执行，一条git pull upstream main就能同时完成"拉取上游 + 合并进当前分支"。它的适用前提是：你正处在想要同步的主分支上，且本地没有未提交的改动。对于日常快速同步，这个写法更省事；对于想精确控制每个环节（比如先看 fetch 结果再决定策略）的场景，分开执行fetch+rebase更稳妥。

何时需要同步：跟随 GitHub 的 "behind" 提示

教程最后给出了触发同步的信号：每当你的 GitHub 仓库提示你落后上游几个提交（"This branch is X commits behind"）时，就应执行上述同步流程。这是因为：

开源项目的上游（如 first-contributions）会不断合并来自全球贡献者的 PR，Contributors.md 中的名字列表持续增长；
只有保持 fork 与上游同步，你基于 fork 新建的功能分支才是在最新代码基底上开发的，提交的 PR 才不会因为"过期基底"而引入无谓的冲突；
同步流程本身也是一次绝佳的 Git 实操演练，把remote、fetch、rebase、push四个概念串成一条完整的链路。

仓库内的 additional-material.md 对该主题的定位总结得很到位："在理想情况下，你和许多人都会持续为项目做贡献"，因此保持 fork 与基础仓库同步是反复发生的常态操作，而不是一次性任务。

与 README 主流程的衔接：同步是"第二次贡献"的起点

回顾仓库根目录 README.md 的完整贡献流程：fork 仓库 →git clone克隆到本地 →git switch -c创建功能分支 → 编辑 Contributors.md 并git commit→git push -u origin 分支名→ 提交 Pull Request。

你可以清楚地看到，同步操作不在首次贡献流程之中——它服务于后续的持续贡献：当你完成第一次 PR 并想再次贡献时，先执行本文的三角同步流程，让本地与 fork 追平上游，再按 README 流程开新分支、做修改、发 PR。两者一前一后、循环往复，共同构成开源贡献者的完整工作闭环。

first-contributions 实战：用 Git 三角工作流（Triangle Workflow）保持 Fork 与上游仓库同步