# GitHub简介 本课程介绍了GitHub的基础知识，这是一个用于托管和管理代码变更的平台。  > [Tomomi Imura](https://twitter.com/girlie_mac) 的手绘笔记 ## 课前测验 [课前测验](https://ff-quizzes.netlify.app) ## 简介 在本课程中，我们将学习： - 如何跟踪你在本地机器上的工作 - 如何与他人协作完成项目 - 如何为开源软件做贡献 ### 前置条件 在开始之前，你需要检查是否安装了Git。在终端中输入： `git --version` 如果未安装Git，请[下载Git](https://git-scm.com/downloads)。然后，在终端中设置你的本地Git配置文件： * `git config --global user.name "your-name"` * `git config --global user.email "your-email"` 要检查Git是否已配置，可以输入： `git config --list` 你还需要一个GitHub账户，一个代码编辑器（例如Visual Studio Code），并打开你的终端（或命令提示符）。 访问 [github.com](https://github.com/) 创建一个账户（如果尚未创建），或者登录并完善你的个人资料。 ✅ GitHub并不是世界上唯一的代码仓库；还有其他平台，但GitHub是最知名的。 ### 准备工作 你需要一个本地机器（笔记本电脑或PC）上的代码项目文件夹，以及一个GitHub上的公共仓库，这将作为如何为他人项目做贡献的示例。 --- ## 代码管理 假设你在本地有一个代码项目文件夹，并希望使用Git（版本控制系统）开始跟踪你的进度。有人将使用Git比作写给未来自己的情书。几天、几周或几个月后阅读你的提交信息时，你可以回忆起为什么做出某个决定，或者“回滚”某个更改——前提是你写了好的“提交信息”。 ### 任务：创建仓库并提交代码 > 查看视频 > > [](https://www.youtube.com/watch?v=9R31OUPpxU4) 1. **在GitHub上创建仓库**。在GitHub.com的仓库标签中，或从右上角的导航栏找到**新建仓库**按钮。 1. 为你的仓库（文件夹）命名 1. 选择**创建仓库**。 1. **导航到你的工作文件夹**。在终端中，切换到你想开始跟踪的文件夹（也称为目录）。输入： ```bash cd [name of your folder] ``` 1. **初始化Git仓库**。在你的项目中输入： ```bash git init ``` 1. **检查状态**。要检查仓库的状态，输入： ```bash git status ``` 输出可能如下所示： ```output Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) modified: file.txt modified: file2.txt ``` 通常，`git status`命令会告诉你哪些文件准备好被保存到仓库，或者哪些文件有更改需要持久化。 1. **添加所有文件进行跟踪** 这也称为暂存文件/将文件添加到暂存区。 ```bash git add . ``` `git add`加上`.`参数表示将所有文件和更改添加到跟踪中。 1. **添加选定文件进行跟踪** ```bash git add [file or folder name] ``` 当你不想一次提交所有文件时，这可以帮助我们仅添加选定文件到暂存区。 1. **取消暂存所有文件** ```bash git reset ``` 此命令帮助我们一次性取消暂存所有文件。 1. **取消暂存特定文件** ```bash git reset [file or folder name] ``` 此命令帮助我们一次性取消暂存特定文件，不将其包含在下一次提交中。 1. **持久化你的工作**。此时你已将文件添加到所谓的暂存区，这是Git跟踪文件的地方。要使更改永久化，你需要提交文件。提交代表仓库历史中的一个保存点。输入以下命令创建提交： ```bash git commit -m "first commit" ``` 这会提交所有文件，并添加信息“首次提交”。对于未来的提交信息，你需要更具描述性，以传达你进行了什么类型的更改。 1. **将本地Git仓库连接到GitHub**。本地Git仓库在你的机器上很好，但最终你可能希望将文件备份到某个地方，并邀请其他人与你一起协作。一个很好的地方就是GitHub。记住我们已经在GitHub上创建了一个仓库，所以我们只需要将本地Git仓库连接到GitHub。`git remote add`命令可以实现这一点。输入以下命令： > 注意，在输入命令之前，访问你的GitHub仓库页面以找到仓库URL。你将在下面的命令中使用它。将```https://github.com/username/repository_name.git```替换为你的GitHub URL。 ```bash git remote add origin https://github.com/username/repository_name.git ``` 这会创建一个名为“origin”的远程连接，指向你之前创建的GitHub仓库。 1. **将本地文件发送到GitHub**。到目前为止，你已经在本地仓库和GitHub仓库之间创建了连接。使用以下命令`git push`将这些文件发送到GitHub： > 注意，你的分支名称可能默认不同于```main```。 ```bash git push -u origin main ``` 这会将你的“main”分支中的提交发送到GitHub。 2. **添加更多更改**。如果你想继续进行更改并将其推送到GitHub，你只需要使用以下三个命令： ```bash git add . git commit -m "type your commit message here" git push ``` > 提示，你可能还想采用`.gitignore`文件，以防止你不想跟踪的文件出现在GitHub上——例如存储在同一文件夹中的笔记文件，但不适合放在公共仓库中。你可以在[.gitignore模板](https://github.com/github/gitignore)中找到`.gitignore`文件的模板。 #### 提交信息 一个好的Git提交主题行可以完成以下句子： 如果应用此提交，它将<你的主题行> 对于主题行，请使用命令式现在时：“更改”而不是“已更改”或“正在更改”。 在正文中（可选），也使用命令式现在时。正文应包括更改的动机，并与之前的行为形成对比。你是在解释“为什么”，而不是“如何”。 ✅ 花几分钟浏览GitHub。你能找到一个非常好的提交信息吗？你能找到一个非常简短的提交信息吗？你认为提交信息中最重要和最有用的信息是什么？ ### 任务：协作 将内容放到GitHub上的主要原因是为了能够与其他开发者协作。 ## 与他人协作项目 > 查看视频 > > [](https://www.youtube.com/watch?v=bFCM-PC3cu8) 在你的仓库中，导航到`Insights > Community`，查看你的项目与推荐的社区标准的比较情况。 以下是一些可以改善你的GitHub仓库的事项： - **描述**。你是否为你的项目添加了描述？ - **README**。你是否添加了README？GitHub提供了编写[README](https://docs.github.com/articles/about-readmes/?WT.mc_id=academic-77807-sagibbon)的指导。 - **贡献指南**。你的项目是否有[贡献指南](https://docs.github.com/articles/setting-guidelines-for-repository-contributors/?WT.mc_id=academic-77807-sagibbon)？ - **行为准则**。是否有[行为准则](https://docs.github.com/articles/adding-a-code-of-conduct-to-your-project/)？ - **许可证**。或许最重要的是，[许可证](https://docs.github.com/articles/adding-a-license-to-a-repository/)？ 所有这些资源都将有助于新团队成员的入职。这些通常是新贡献者在查看你的代码之前会关注的内容，以了解你的项目是否值得他们投入时间。 ✅ README文件虽然需要时间准备，但经常被忙碌的维护者忽视。你能找到一个特别详细的README示例吗？注意：有一些[工具可以帮助创建好的README](https://www.makeareadme.com/)，你可能会想尝试一下。 ### 任务：合并代码 贡献文档帮助人们为项目做贡献。它解释了你希望的贡献类型以及流程如何运作。贡献者需要完成一系列步骤才能为你的GitHub仓库做贡献： 1. **Fork你的仓库**。你可能希望人们Fork你的项目。Fork意味着在他们的GitHub个人资料中创建你的仓库的副本。 1. **克隆**。然后他们会将项目克隆到本地机器。 1. **创建分支**。你会希望他们为自己的工作创建一个分支。 1. **专注于一个领域的更改**。要求贡献者一次专注于一个方面的贡献——这样你合并他们工作的可能性更高。想象他们修复了一个bug，添加了一个新功能，并更新了几个测试——如果你只想实现其中的2个或3个，或者1个或3个更改怎么办？ ✅ 想象一个分支在编写和发布优质代码时特别重要的情况。你能想到哪些用例？ > 注意，成为你希望看到的改变，并为自己的工作创建分支。你进行的任何提交都将在你当前“检出”的分支上进行。使用`git status`查看当前分支。 让我们来看看贡献者的工作流程。假设贡献者已经Fork并克隆了仓库，因此他们在本地机器上有一个准备工作的Git仓库： 1. **创建分支**。使用`git branch`命令创建一个分支，包含他们打算贡献的更改： ```bash git branch [branch-name] ``` 1. **切换到工作分支**。使用`git switch`切换到指定分支并更新工作目录： ```bash git switch [branch-name] ``` 1. **进行工作**。此时你可以添加更改。别忘了用以下命令告诉Git： ```bash git add . git commit -m "my changes" ``` 确保为你的提交起一个好名字，对你自己和你帮助的仓库维护者来说都很重要。 1. **将工作与`main`分支合并**。完成工作后，你希望将你的工作与`main`分支的工作合并。`main`分支可能已经发生了变化，因此请确保首先使用以下命令更新到最新版本： ```bash git switch main git pull ``` 此时你需要确保任何冲突（Git无法轻松合并的情况）发生在你的工作分支中。因此运行以下命令： ```bash git switch [branch_name] git merge main ``` 这会将`main`中的所有更改带入你的分支，希望你可以继续。如果不能，VS Code会告诉你Git“困惑”的地方，你只需修改受影响的文件以确定哪个内容最准确。 1. **将工作发送到GitHub**。将工作发送到GitHub意味着两件事：将分支推送到你的仓库，然后打开一个PR（Pull Request）。 ```bash git push --set-upstream origin [branch-name] ``` 上述命令会在你的Fork仓库中创建分支。 1. **打开PR**。接下来，你需要打开一个PR。通过导航到GitHub上的Fork仓库，你会看到GitHub提示是否要创建一个新的PR，点击它，你会进入一个界面，可以更改提交信息标题，给出更合适的描述。现在你Fork的仓库的维护者会看到这个PR，希望他们会欣赏并合并你的PR。你现在是一名贡献者，太棒了 :) 1. **清理**。成功合并PR后，清理工作被认为是良好的实践。你需要清理本地分支和推送到GitHub的分支。首先使用以下命令在本地删除分支： ```bash git branch -d [branch-name] ``` 确保接下来访问Fork仓库的GitHub页面并删除你刚刚推送到的远程分支。 `Pull request` 似乎是一个有点奇怪的术语，因为实际上你是想将你的更改推送到项目中。但项目维护者（项目所有者）或核心团队需要在将你的更改合并到项目的“主”分支之前进行审查，因此你实际上是在请求维护者对更改做出决定。 `Pull request` 是一个比较和讨论分支中引入的差异的地方，可以进行审查、评论、集成测试等操作。一个好的 `pull request` 遵循与提交信息大致相同的规则。例如，当你的工作解决了某个问题时，可以在问题跟踪器中添加对该问题的引用。这可以通过使用 `#` 后跟问题编号来完成，例如 `#97`。 🤞希望所有检查都通过，项目所有者将你的更改合并到项目中🤞 更新你当前的本地工作分支，使其包含 GitHub 上对应远程分支的所有新提交： `git pull` ## 如何为开源项目做贡献 首先，找到一个你感兴趣并希望贡献更改的 GitHub 仓库（或 **repo**）。你需要将其内容复制到你的电脑上。 ✅ 找到“适合初学者”的仓库的一个好方法是[通过标签 'good-first-issue' 进行搜索](https://github.blog/2020-01-22-browse-good-first-issues-to-start-contributing-to-open-source/)。  有几种复制代码的方法，其中一种是使用 HTTPS、SSH 或 GitHub CLI（命令行界面）“克隆”仓库的内容。 打开你的终端并像这样克隆仓库： `git clone https://github.com/ProjectURL` 要开始处理项目，请切换到正确的文件夹： `cd ProjectURL` 你也可以使用 [Codespaces](https://github.com/features/codespaces)（GitHub 的嵌入式代码编辑器/云开发环境）或 [GitHub Desktop](https://desktop.github.com/) 打开整个项目。 最后，你可以下载代码的压缩文件夹。 ### 关于 GitHub 的一些有趣的事情 你可以对 GitHub 上的任何公共仓库进行加星、关注和“fork”。你可以在右上角的下拉菜单中找到你加星的仓库。这就像为代码做书签。 项目通常有一个问题跟踪器，大多数情况下在 GitHub 的“Issues”标签中，除非另有说明，人们会在这里讨论与项目相关的问题。而在 Pull Requests 标签中，人们会讨论和审查正在进行的更改。 项目可能还会在论坛、邮件列表或聊天频道（如 Slack、Discord 或 IRC）中进行讨论。 ✅ 浏览一下你的新 GitHub 仓库，尝试一些操作，比如编辑设置、向仓库添加信息以及创建项目（例如看板）。你可以做很多事情！ --- ## 🚀 挑战 与朋友合作处理彼此的代码。协作创建一个项目，fork 代码，创建分支并合并更改。 ## 课后测验 [课后测验](https://ff-quizzes.netlify.app/web/en/) ## 复习与自学 阅读更多关于[如何为开源软件做贡献](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution)的内容。 [Git 速查表](https://training.github.com/downloads/github-git-cheat-sheet/)。 多练习，多实践。GitHub 提供了很棒的学习路径：[skills.github.com](https://skills.github.com): - [GitHub 的第一周](https://skills.github.com/#first-week-on-github) 你还可以找到更高级的课程。 ## 作业 完成 [GitHub 的第一周课程](https://skills.github.com/#first-week-on-github)。 --- **免责声明**： 本文档使用AI翻译服务[Co-op Translator](https://github.com/Azure/co-op-translator)进行翻译。尽管我们努力确保准确性，但请注意，自动翻译可能包含错误或不准确之处。应以原始语言的文档作为权威来源。对于关键信息，建议使用专业人工翻译。因使用本翻译而引起的任何误解或误读，我们概不负责。