使用 GitHub CLI 在 first-contributions 仓库完成你的第一次开源贡献【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions本篇技术指南以 first-contributions 项目的 GitHub Command Line InterfaceCLI教程为核心面向希望在纯终端环境中完成全部操作的开源新手。通过gh命令行工具你无需打开任何图形界面即可依次完成「安装与登录 GitHub CLI → Fork 上游仓库 → 创建分支 → 修改 Contributors.md → 提交并推送 → 发起 Pull Request」的完整贡献闭环。读完本文你将掌握gh repo fork、gh auth login、gh pr create、gh status等核心命令的用法并能独立应对推送阶段的常见认证错误。一、为什么选择 GitHub CLI 路线GitHub 官方命令行工具ghGitHub CLI的价值在于把原本需要浏览器和 Git 命令交替操作的开源贡献流程收敛到同一个终端会话内完成。在 first-contributions 项目的教程体系中它属于 cli-tool-tutorials 分支与图形界面工具如 GitHub Desktop 教程、VS Code 教程并列专为「一切都在终端里完成」的开发者设计。与纯 Git 方式相比CLI 路线的显著差异在于Fork 仓库和创建 Pull Request 这两个原本必须在网页上手动完成的操作现在可以分别通过gh repo fork与gh pr create一条命令完成从而形成完整无断点的终端工作流。二、准备工作环境与账号开始前需要确认以下两项前提条件Git 已安装Git 负责本地版本管理创建分支、暂存、提交、推送。安装方式依操作系统而异仓库中提供了 Ubuntu 安装文档 与 Arch Linux 安装文档 可供参考Windows 用户可参考 Git Bash 与 Windows 教程。安装后可用git --version验证。GitHub 账号贡献内容最终将合并到上游仓库因此需要一个有效的 GitHub 账号。三、安装 GitHub CLI 并完成登录在系统上安装github-cli工具包名通常为gh按官方安装文档操作即可。安装完成后在终端执行登录命令gh auth login命令执行后gh会以交互方式引导你完成以下选择登录 GitHub.com 还是 GitHub Enterprise Server使用 HTTPS 还是 SSH 作为 Git 协议通过浏览器完成认证或粘贴认证令牌Token是否使用 Git 凭据管理器存储凭据。按照提示逐步完成即可。登录成功后gh会在本地保存认证状态后续所有gh命令Fork、创建 PR 等都将以你的身份自动执行无需再次输入用户名密码。可以执行gh auth status验证当前登录状态。四、Fork 上游仓库Fork 的作用是在你自己的 GitHub 账号下生成一份 first-contributions 仓库的副本之后的修改、推送都以该副本为基地最终再通过 Pull Request 把改动合并回上游。在终端中执行gh repo fork firstcontributions/first-contributions这条命令的语义是「Forkfirstcontributions/first-contributions这个仓库」。重要提示命令执行过程中会询问你是否需要同时把 Fork 后的仓库克隆到本地请选择「yes」是。这与 README.md 中描述的经典流程 一致——先 Fork 再 Clone 到本机gh repo fork把这两个动作合并成了带确认提示的一步。克隆完成后你会在本地得到一个first-contributions目录进入该目录后即可开始后续操作cd first-contributions五、创建你的专属分支开源协作的惯例是不要在默认分支main上直接提交改动而是为每一次改动创建独立分支。这一步仍使用 Git 原生命令完成git switch -c add-john-doe其中-c表示创建create新分支add-john-doe是分支名请替换为与你身份相关的名字例如add-你的名字。创建完成后你已自动切换到新分支。兼容性说明git switch是较新版本的 Git 提供的命令。如果执行时报错提示switch不是有效的 Git 命令说明本地 Git 版本较旧可改用等效的git checkout -b add-john-doe参考 README.md 中的对应说明。六、修改文件并提交6.1 在 Contributors.md 中加入你的名字用文本编辑器打开项目根目录的Contributors.md文件把你的名字加进去。这份文件记录了所有完成过首次贡献的开发者名单当前已积累数千条记录加入名字即代表你的贡献被社区确认。建议把名字放在文件中间任意位置保存文件。6.2 查看改动状态回到项目目录执行git status输出会显示Contributors.md处于已修改modified状态说明你的改动已被 Git 感知。养成「改完先看git status」的习惯能避免漏提交或误提交。6.3 暂存改动将Contributors.md加入暂存区git add Contributors.md注意仓库教程中的文件引用统一为Contributors.md首字母大写执行时请与仓库实际文件名保持一致。6.4 提交改动git commit -m Add your-name to Contributors list将your-name替换为你的真实名字。提交信息commit message遵循了开源项目常见的描述性写法说明「做了什么 对象是谁」方便维护者与后续贡献者快速理解本次提交的意图。关于 Git 提交的进一步操作例如提交后发现信息写错、需要合并多个提交等可查阅仓库的 git_workflow_scenarios 进阶文档目录其中包含 修改最近一次提交amend、合并提交squash、撤销本地提交 等专题。七、推送改动到 GitHub本地提交完成后需要把分支推送到你在 GitHub 上的 Fork 仓库即远程仓库origingit push origin -u your-branch-name将your-branch-name替换为你此前创建的分支名如add-john-doe。其中origin是本地仓库对你 GitHub 上 Fork 副本的远程命名-u即--set-upstream用于建立本地分支与远程分支的追踪关系之后在该分支上可以直接执行git push而无需再写远程与分支名。7.1 推送阶段的认证错误排查如果推送时遇到如下错误remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead. remote: Please see ... for more information. fatal: Authentication failed for https://github.com/your-username/first-contributions.git/这说明自 2021 年 8 月 13 日起GitHub 已彻底移除对 HTTPS 密码账号密码认证方式的支持必须改用个人访问令牌Personal Access TokenPAT或 SSH 密钥进行认证。解决方案有两种改用 SSH 密钥为你的 GitHub 账号生成并配置 SSH 公钥随后把远程地址切换为 SSH 形式git remote -v # 先检查当前远程地址 git remote set-url origin gitgithub.com:your-username/first-contributions.git这与教程中「为账号生成并配置 SSH 密钥」的建议一致也与 keeping-your-fork-synced-with-this-repository 等文档中统一使用 SSH 地址的做法相呼应。使用个人访问令牌在 GitHub 账号设置中生成具有repo权限的令牌并在 HTTPS 推送时以令牌作为密码输入。另外值得留意的是由于本教程全程使用ghCLI 且已在gh auth login阶段完成认证若你的 Git 凭据管理器已与gh联动登录时选择了对应选项推送时通常不会再出现上述认证问题该错误更多出现在仅配置了纯 Git 环境的情况。八、发起 Pull Request 并查看状态改动推送到 Fork 仓库后就可以向firstcontributions/first-contributions上游仓库发起 Pull Request简称 PR请维护者审查并合并你的改动。在仓库目录中执行gh pr create --repo firstcontributions/first-contributions命令参数说明--repo firstcontributions/first-contributions显式指定 PR 的目标仓库为上游仓库即你 Fork 的来源确保 PR 正确提交到公共仓库而不是你自己的副本执行后gh会交互式地引导你填写 PR 的标题title与描述body完成后提交即可。PR 创建后可以用以下命令随时查看它的状态gh statusgh status会汇总展示与当前账号相关的待处理pendingPR、可查看的 PR 等摘要信息帮助你确认自己提交的 PR 正处于「等待审查/合并」流程中。对于希望深入了解 PR 前后协作场景的读者仓库还提供了 解决合并冲突、保持 Fork 与上游同步、删除已合并分支 等进阶文档覆盖贡献者高频遇到的后续场景。九、完成后的路径一次标准工作流的回顾与延伸到这里你已经完整走通了开源贡献的标准工作流Fork → Clone → 编辑 → Pull Request。这是今后作为贡献者参与几乎所有开源项目时都会反复遇到的基本模式阶段本教程中的实现工具Fork 上游仓库gh repo fork firstcontributions/first-contributions并选择克隆gh CLI创建分支git switch -c add-你的名字Git修改文件编辑Contributors.md并git status确认编辑器 Git暂存与提交git addgit commit -m ...Git推送git push origin -u your-branch-nameGit发起审查gh pr create --repo firstcontributions/first-contributionsgh CLI状态跟踪gh statusgh CLI庆祝你的第一次贡献之后可以沿着以下方向继续深入阅读进阶材料仓库的 Additional material 索引 汇总了配置 Git、暂存文件、恢复提交、理解分支why-using-branches、rebase 与 merge 的区别 等十余个实用专题开始贡献其他项目本项目的 Web 应用维护了一份包含「易上手 issue」的开源项目清单可据此选择下一个练习目标尝试其他工具的教程如果不习惯纯命令行也可以对照 图形界面工具教程、IntelliJ IDEA 教程 等仓库内其他入门路线理解不同工具下同一工作流的等价实现。正如教程开头所说第一次贡献应当是有趣的、有回报的、能激励你继续走下去的。现在你已经在终端里迈出了这一步。【免费下载链接】first-contributions✨ Help beginners to contribute to open source projects项目地址: https://gitcode.com/gh_mirrors/fi/first-contributions创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考