first-contributions 新手首次开源贡献指南：从 fork 到 pull request 的完整 Git 工作流

first-contributions 新手首次开源贡献指南：从 fork 到 pull request 的完整 Git 工作流

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

本文以 first-contributions 仓库官方教程（docs/translations/README.ky.md，与主 README.md 内容一致）为核心骨架，面向完全没接触过开源协作的初学者。读完本文你将能独立走完fork → clone → 创建分支 → 修改文件 → commit → push → pull request这一开源贡献的标准流程，并掌握git switch、git add、git commit、git push等核心命令的用法与常见报错（尤其是 push 认证失败）的解决办法。

项目定位：专为"第一次贡献"而建的教学仓库

first-contributions 是一个以教学为目的的开源仓库：它刻意保持简单，让初学者把注意力完全放在 Git 协作流程本身，而不是被复杂的业务代码吓退。你只需要修改一个纯文本文件（Contributors.md），就能走完一次真实、完整的贡献流程。

从仓库结构可以清晰看到它的"教学工具"定位（详见文末仓库结构速览）：

• 主教程：README.md 及 docs/translations/ 下数十种语言的翻译版（包括 README.zh-cn.md、README.ky.md 等），覆盖全球初学者；
• 配套工具教程：docs/gui-tool-tutorials/ 收录 GitHub Desktop、VS Code、IntelliJ 等 GUI 工具的图文教程，docs/cli-tool-tutorials/ 收录命令行与 GitHub CLI 教程；
• 进阶学习资料：docs/additional-material/git_workflow_scenarios/additional-material.md 汇总了解决合并冲突、压缩提交、撤销提交等高级场景的专题文档。

开始前的准备

动手之前，先确认两件事：

1. 本地已安装 Git。官方教程明确要求：如果电脑上还没有 Git，先完成安装。仓库内提供了针对不同系统的安装指引，例如 installing-git-ubuntu.md（Ubuntu）和 installing-git-arch.md（Arch Linux）。安装完成后可在终端验证版本：

   git --version

2. 拥有一个 GitHub 账号，并且已经登录。后续的 fork、push、pull request 都依赖账号身份。

第一步：Fork 这个仓库

在本仓库页面右上角点击Fork按钮，GitHub 会在你自己的账号下生成一份该仓库的完整副本。

关键认知：fork 出来的副本与原仓库是两个独立的远程仓库——你对自己的副本拥有完整的读写权限，但默认无法直接向原仓库（上游 upstream）推送代码。这种"先复制、再修改、最后通过 PR 请求合并"的模式，正是开源协作最主流的形态。

第二步：把 fork 的仓库 Clone 到本地

登录 GitHub 并打开你 fork 出来的仓库，依次点击：

1. Code按钮；
2. 切换到SSH标签页（教程默认推荐 SSH 方式）；
3. 点击复制 URL 到剪贴板图标。

然后在本地终端执行：

git clone "你刚刚复制的url"

其中"你刚刚复制的 url"（不含引号）就是你 fork 出来的仓库地址。以 SSH 方式为例，地址形如：

git clone [e-mail]:<你的GitHub用户名>/first-contributions.git

这条命令会把远程仓库的完整内容（含全部提交历史）下载到当前目录下的first-contributions文件夹中。

技术说明：git clone除了拉取代码，还会自动把远程地址注册为名为origin的 remote（远程仓库引用），并把默认分支（本仓库为main）建立本地跟踪关系——这是后续git push能直接对应到origin的前提。

第三步：创建你自己的分支

先进入仓库目录（如果不在的话）：

cd first-contributions

然后使用git switch创建一个新分支：

git switch -c your-new-branch-name

其中-c是--create的简写，表示"创建并切换到新分支"。官方示例：

git switch -c add-tigilchi-balanchaev

分支命名惯例：本项目教程习惯用add-<你的名字>作为分支名，例如add-alonzo-church。这种命名能让维护者一眼看出这个分支要做什么、由谁提交。

旧版 Git 的兼容写法：git switch是 Git 2.23 引入的命令，用于把原来git checkout混杂的"切分支"职责独立出来。如果你执行时遇到如下报错：

Git: switch is not a git command. See git –help

说明本机 Git 版本较旧，改用等价的git checkout即可：

git checkout -b your-new-branch-name

git switch -c与git checkout -b功能完全等价，都是"基于当前分支创建新分支并切换过去"。

为什么要新建分支？在真实项目中，直接在main上改代码是高风险操作。独立分支把你的实验性改动与主干隔离，即使改坏也不会影响主分支，这正是 why-using-branches.md 所强调的分支价值。

第四步：修改文件并提交（commit）

4.1 编辑 Contributors.md

用任意文本编辑器打开项目根目录下的 Contributors.md，把你的名字加进去。官方教程特别强调了一条细节：不要加在文件开头或结尾，加在中间的任意位置——这样既锻炼了在大型文件中定位编辑的能力，也能减少多人同时编辑首尾时发生冲突的概率。

编辑后保存文件。此时改动还只存在于工作区，尚未被 Git 记录。

4.2 用 git status 确认改动

回到终端，在项目目录执行：

git status

输出会列出被修改的文件（例如modified: Contributors.md），这相当于 Git 在工作区与上次提交之间做的"差异体检报告"。

4.3 用 git add 暂存改动

Git 采用"暂存区（index/staging area）+ 提交"的两段式工作流。git add把指定文件从工作区放入暂存区：

git add Contributors.md

只暂存这一个文件，可以精确控制"这次提交包含什么"；当然也可以用git add .暂存全部改动（初学者建议按教程精确到文件）。

4.4 用 git commit 生成提交

git commit -m "Add your-name to Contributors list"

把your-name替换成你的真实名字，例如git commit -m "Add Alice to Contributors list"。-m指定提交信息（commit message）。一条清晰、能说明"做了什么"的提交信息是良好协作习惯的开始——后续在进阶资料 squashing-commits.md 中还会看到提交信息在代码评审中的重要性。

第五步：把改动 Push 到 GitHub

git push -u origin your-branch-name

把your-branch-name替换成你第三步创建的分支名。

参数拆解：

• origin：远程仓库名（即 clone 时自动注册的那个）；
• -u（--set-upstream的简写）：把本地分支与远程分支建立上游跟踪关系，此后在该分支上直接执行git push/git pull即可，无需再写远程名和分支名；
• your-branch-name：要推送的本地分支。

push 认证失败：最常见的坑

如果你在 push 时收到如下错误，属于 GitHub 自 2021 年 8 月 13 日起移除密码认证后的典型现象：

remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. fatal: Authentication failed for 'https://github.com/<your-username>/first-contributions.git/'

解决方案（官方教程的完整处理路径）：

1. 改用 SSH 认证：参考 GitHub 官方文档，在账号中生成并配置 SSH 公钥，之后所有 Git 操作都通过 SSH 密钥完成，不再需要用户名密码；

2. 检查当前远程地址：执行

   git remote -v

   如果输出是 HTTPS 形式，例如：

   origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)

   说明 push 时仍会被要求输入用户名和密码，从而再次触发认证错误；

3. 把远程地址切换为 SSH 形式：

   git remote set-url origin [e-mail]:your-username/your_repo.git

   改完后再次git push即走 SSH 认证通道。这也是教程推荐在第二步 clone 时就选SSH tab的原因——从一开始就避开 HTTPS 密码认证的坑。

第六步：提交 Pull Request（PR）

push 成功后，回到 GitHub 上你自己的 fork 仓库页面，会看到一个醒目的Compare & pull request按钮，点击它：

1. 确认对比基准：base 仓库选择原项目（上游），compare 分支选择你刚推送的分支；
2. 填写 PR 标题和描述，说明你做了什么改动；
3. 点击提交（submit）按钮，完成 PR 创建。

之后维护者会审查你的改动，通过后将其合并（merge）到项目主分支；合并完成时，你会收到一封 GitHub 通知邮件——至此你的第一次贡献正式落地。

完成之后：接下来做什么

恭喜！你刚刚走完了开源贡献者最常遇到的fork → clone → edit → pull request标准工作流。教程还给出了几条后续建议：

• 分享你的成就：庆祝这次贡献，把它分享给朋友和关注者；
• 继续练习：如果想再练手，可以找更多类似的小型练习项目；
• 参与真实项目：官方整理了带"easy issue"（适合新手的问题）的项目清单，可以从这些项目开始，把刚学会的流程应用到真实世界。

配套学习资源：从第一次贡献到进阶玩家

完成基础流程只是起点。仓库在 docs/additional-material/git_workflow_scenarios/additional-material.md 中汇总了进阶 Git 场景的专题文档，每个专题解决一个真实协作中会遇到的问题：

场景	文档	适用时机
修改最近一次提交	amending-a-commit.md	提交信息写错、漏加文件，且尚未 push
配置 Git 用户信息	configuring-git.md	首次使用 Git 或需要调整全局配置
保持 fork 与上游同步	keeping-your-fork-synced-with-this-repository.md	上游仓库有新提交，你的 fork 落后了
把提交移到其他分支	moving-a-commit-to-a-different-branch.md	提交错分支，需要转移
删除本地文件	removing-a-file.md	提交前需要移除某文件
删除本地分支	removing-branch-from-your-repository.md	PR 合并后清理本地分支
解决合并冲突	resolving-merge-conflicts.md	多人同时改同一文件，PR 无法自动合并
回滚已推送的提交	reverting-a-commit.md	需要撤销已经推到远程的提交
合并（squash）多个提交	squashing-commits.md	评审者要求把多个琐碎提交合并成一个
撤销本地提交	undoing-a-commit.md	本地改乱了，想重置本地仓库
创建 .gitignore	creating-a-gitignore-file.md	需要忽略编译产物、密钥等不该入库的文件
存储凭据	storing-credentials.md	希望免去重复输入凭据（注意遵循所在机构安全策略）
其他资料索引	Useful-links-for-further-learning.md	想系统学习 Git 与开源知识

如果你不习惯命令行，或希望体验可视化操作，仓库还提供了多种 GUI 工具教程，与本教程的流程一一对应：

• GitHub Desktop 教程
• VS Code 教程
• Visual Studio 2017 教程
• GitKraken 教程
• Atlassian Sourcetree（macOS）教程
• IntelliJ IDEA 教程

其中 GitHub Desktop、VS Code 等教程还有对应的中文翻译版本（见 docs/gui-tool-tutorials/translations/Chinese/），而命令行工具类教程集中在 docs/cli-tool-tutorials/。

仓库结构速览

路径	作用
README.md	主教程（本文对应内容），及 docs/translations/ 下 60+ 语言的翻译
Contributors.md	教程指定的练习文件——本次贡献就是把自己的名字加进这里
docs/gui-tool-tutorials/	GitHub Desktop、VS Code、GitKraken、Sourcetree、IntelliJ 等 GUI 工具教程
docs/cli-tool-tutorials/	命令行、Git Bash、GitHub CLI 等命令行工具教程
docs/additional-material/	进阶 Git 场景专题（合并冲突、squash、amend、fork 同步等）
LICENSE	MIT 开源许可

小结

一次开源贡献的本质，就是"在自己的副本上安全地改动、清晰地记录、礼貌地请求合并"。first-contributions 用最小代价帮你建立这套肌肉记忆：fork 得到可控副本，clone 拉取到本地，独立分支隔离改动，git add+git commit精确记录变更，git push推送远程，最后通过 pull request 把成果交还给上游。掌握这条链路后，你面对任何真实项目都能照方抓药——这也是本仓库被全球初学者广泛用作"开源第一课"的原因。

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