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 Forkorigin你在 GitHub 上点击 Fork 按钮生成的个人副本。只有通过它才能发起 Pull Request详见仓库根目录 README.md 中的 fork → clone → 修改 → push → PR 主流程。你的本地仓库local你通过git clone拉取到本机、真正写代码的工作目录。这种一源两副本的协作形态是开源项目的典型特征被称为Triangle Workflows三角工作流。同步的方向是有严格顺序的绝不能跳步上游公开仓库upstream │ │ ① fetch拉取到本地 │ ② rebase/merge合并到本地主分支 ▼ 本地仓库local │ │ ③ push推送到你的 Fork ▼ 你的 GitHub Forkorigin教程特别点明了为什么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 认识官方主仓库需要把它添加为第二个远程并约定俗成地命名为upstreamgit 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 upstreamfetch会把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 Forkgit 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 maingit pull本质上是git fetch 整合merge 或 rebase取决于上文配置的组合命令。如果你不想分两步执行一条git pull upstream main就能同时完成拉取上游 合并进当前分支。它的适用前提是你正处在想要同步的主分支上且本地没有未提交的改动。对于日常快速同步这个写法更省事对于想精确控制每个环节比如先看 fetch 结果再决定策略的场景分开执行fetchrebase更稳妥。何时需要同步跟随 GitHub 的 behind 提示教程最后给出了触发同步的信号每当你的 GitHub 仓库提示你落后上游几个提交This branch is X commits behind时就应执行上述同步流程。这是因为开源项目的上游如 first-contributions会不断合并来自全球贡献者的 PRContributors.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。两者一前一后、循环往复共同构成开源贡献者的完整工作闭环。相关阅读仓库内延伸资料英文原版教程docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md完整贡献入门流程README.mdRebase 与 Merge 深度对比及pull.rebase配置docs/additional-material/git_workflow_scenarios/rebase-vs-merge.md分支的作用与特性分支实践docs/additional-material/git_workflow_scenarios/why-using-branches.md查看提交历史确认同步结果docs/additional-material/git_workflow_scenarios/check-commit-log.md解决合并冲突docs/additional-material/git_workflow_scenarios/resolving-merge-conflicts.md同步完成后清理已合并分支docs/additional-material/git_workflow_scenarios/removing-branch-from-your-repository.mdGit 用户信息等基础配置docs/additional-material/git_workflow_scenarios/configuring-git.md进阶 Git 主题索引docs/additional-material/git_workflow_scenarios/additional-material.md【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考