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 汇总了解决合并冲突、压缩提交、撤销提交等高级场景的专题文档。开始前的准备动手之前先确认两件事本地已安装 Git。官方教程明确要求如果电脑上还没有 Git先完成安装。仓库内提供了针对不同系统的安装指引例如 installing-git-ubuntu.mdUbuntu和 installing-git-arch.mdArch Linux。安装完成后可在终端验证版本git --version拥有一个 GitHub 账号并且已经登录。后续的 fork、push、pull request 都依赖账号身份。第一步Fork 这个仓库在本仓库页面右上角点击Fork按钮GitHub 会在你自己的账号下生成一份该仓库的完整副本。关键认知fork 出来的副本与原仓库是两个独立的远程仓库——你对自己的副本拥有完整的读写权限但默认无法直接向原仓库上游 upstream推送代码。这种先复制、再修改、最后通过 PR 请求合并的模式正是开源协作最主流的形态。第二步把 fork 的仓库 Clone 到本地登录 GitHub 并打开你 fork 出来的仓库依次点击Code按钮切换到SSH标签页教程默认推荐 SSH 方式点击复制 URL 到剪贴板图标。然后在本地终端执行git clone 你刚刚复制的url其中你刚刚复制的 url不含引号就是你 fork 出来的仓库地址。以 SSH 方式为例地址形如git clone gitgithub.com:你的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-namegit switch -c与git checkout -b功能完全等价都是基于当前分支创建新分支并切换过去。为什么要新建分支在真实项目中直接在main上改代码是高风险操作。独立分支把你的实验性改动与主干隔离即使改坏也不会影响主分支这正是 why-using-branches.md 所强调的分支价值。第四步修改文件并提交commit4.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 到 GitHubgit 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/解决方案官方教程的完整处理路径改用 SSH 认证参考 GitHub 官方文档在账号中生成并配置 SSH 公钥之后所有 Git 操作都通过 SSH 密钥完成不再需要用户名密码检查当前远程地址执行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 时仍会被要求输入用户名和密码从而再次触发认证错误把远程地址切换为 SSH 形式git remote set-url origin gitgithub.com:your-username/your_repo.git改完后再次git push即走 SSH 认证通道。这也是教程推荐在第二步 clone 时就选SSH tab的原因——从一开始就避开 HTTPS 密码认证的坑。第六步提交 Pull RequestPRpush 成功后回到 GitHub 上你自己的 fork 仓库页面会看到一个醒目的Compare pull request按钮点击它确认对比基准base 仓库选择原项目上游compare 分支选择你刚推送的分支填写 PR 标题和描述说明你做了什么改动点击提交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.mdPR 合并后清理本地分支解决合并冲突resolving-merge-conflicts.md多人同时改同一文件PR 无法自动合并回滚已推送的提交reverting-a-commit.md需要撤销已经推到远程的提交合并squash多个提交squashing-commits.md评审者要求把多个琐碎提交合并成一个撤销本地提交undoing-a-commit.md本地改乱了想重置本地仓库创建 .gitignorecreating-a-gitignore-file.md需要忽略编译产物、密钥等不该入库的文件存储凭据storing-credentials.md希望免去重复输入凭据注意遵循所在机构安全策略其他资料索引Useful-links-for-further-learning.md想系统学习 Git 与开源知识如果你不习惯命令行或希望体验可视化操作仓库还提供了多种 GUI 工具教程与本教程的流程一一对应GitHub Desktop 教程VS Code 教程Visual Studio 2017 教程GitKraken 教程Atlassian SourcetreemacOS教程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 同步等LICENSEMIT 开源许可小结一次开源贡献的本质就是在自己的副本上安全地改动、清晰地记录、礼貌地请求合并。first-contributions 用最小代价帮你建立这套肌肉记忆fork 得到可控副本clone 拉取到本地独立分支隔离改动git addgit commit精确记录变更git push推送远程最后通过 pull request 把成果交还给上游。掌握这条链路后你面对任何真实项目都能照方抓药——这也是本仓库被全球初学者广泛用作开源第一课的原因。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
