16 KiB

Raw Blame History Unescape Escape

GitHub 介绍

这节课涵盖了 GitHub 的基础知识，这是一个可以用来存放代码和管理代码变更的平台。

涂鸦笔记作者：Tomomi Imura

课前小测

大纲

这节课我们将会介绍：

在你的电脑上追踪你的工作
与他人协同开发项目
如何参与开源软件贡献

开始之前

开始之前，你需要确保安装了 Git，在终端（译注：即上一节课中介绍的命令行）中输入： git --version

如果没有安装 Git，请先下载并安装 Git。然后用如下命令设置你的本地 Git 使用者配置文件：

git config --global user.name "your-name"
git config --global user.email "your-email"

要检查 Git 使用者是否配置完成，可以输入： git config --list

你还需要一个 GitHub 账户，一个代码编辑器（比如 Visual Studio Code），并且要打开你的终端（或者其他命令行）。

如果你没有现成的 Github 账号，去 github.com 创建一个。如果已经有账号，就登录进去并且完成个人资料的配置。

✅ GitHub 并不是世界上唯一的代码仓库，但是最知名的。

课前准备

你需要在本地（你的笔记本或 PC）创建一个项目文件夹，还需要在 GitHub 上创建一个公开的仓库（译注：后文会有指引），作为本节课中向其他人的项目提贡献的示例。

代码管理

假如你在本地有一个代码项目的文件夹，你希望开始使用 Git （版本控制系统）来追踪你的进度。有的人将使用 Git 比作给未来的你自己写一封情书，在数日、数周乃至数月后阅读你的提交信息（commit messages）时，你就可以想起你做出某个决定的原因，或者回滚（rollback）一次变更 —— 前提是你写了不错的提交信息。

任务：创建仓库并提交代码

在 GitHub 上创建仓库。进入 GitHub.com，在 “Repositories” 标签或者右上角导航栏找到 New repository 按钮。
1. 给你的仓库取个名字；
2. 点击 Create repository。
前往你的工作目录。在你的终端中，通过输入下方命令切换到你希望开始追踪的文件夹（即目录）：
```
cd [文件名称/目录路径]
```
初始化一个 Git 仓库。在你的项目下输入：
```
git init
```
检查状态。要检查你的仓库状态，输入：
```
git status
```
输出看起来将会像这样：
```
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git checkout -- <file>..." to discard changes in working directory)

     modified:   file.txt
     modified:   file2.txt
```
一般来说 git status 命令会告诉你诸如什么文件已经 被保存到 仓库内或者有一些你可能想要保留的变更之类的事。
追踪所有文件 这个操作也叫做暂存（stage）文件或者将文件添加到暂存区（staging area）。
```
git add .
```
git add 命令加上 . 参数将会追踪你的所有文件和变更。
只追踪选定的文件
```
git add [文件或文件夹名]
```
如果你不想一次性将所有文件添加到暂存区，可以用这个命令仅仅添加选定的文件。
取消所有文件的追踪
```
git reset
```
这条命令可以帮我们取消暂存（unstage）所有文件。
取消特定文件的追踪
```
git reset [文件或文件夹名]
```
如果你在下次提交中不希望提交某个已经暂存的文件，可以用这条命令取消它的暂存。
保存你的工作。现在你应该已经将文件添加到了所谓 暂存区 中，这是 Git 追踪你的文件的地方。为了永久地保存变更，你需要 提交（commit） 这些文件。你可以用 git commit 命令创建一次提交。一次提交代表你的仓库历史中的一个存档点。输入下方命令来创建一次提交：
```
git commit -m "first commit"
```
这会提交你暂存区中的所有文件，并带上一条提交信息 —— “first commit”。在以后的提交信息中你会想要加入更加准确的描述，比如一些表示你这次变更的类型的信息。
将你的本地仓库连接到 GitHub。现在 Git 仓库已经能在你的本地机器上正常运作，但是有时候你会想要将你的文件备份到别处，或者希望邀请其他人来一起参与这个仓库的协作。GitHub 就是一个可以满足你要求的好地方。我们此前已经在 GitHub 上创建了一个仓库，现在只需要将本地 Git 仓库连接到 GitHub 就可以了，用 git remote add 命令就可以做到。输入下面的命令：

注意，在你输入命令前，需要前往你的 GitHub 仓库而页面来找到仓库的地址（URL），用它来替换命令中 username/repository_name 这一部分。
```
git remote add origin https://github.com/username/repository_name.git
```
这会创建一个被命名为 “origin” 的 远程仓库位置（remote），也可以理解为一个连接，指向你早先创建的 GitHub 仓库。
将本地文件上传至 GitHub。现在你已经创建了一个本地仓库和 GitHub 仓库间的连接。让我们通过 git push 命令将这些文件上传至 GitHub，就像这样：
```
git push -u origin main
```
这样就会把你的提交上传到 GitHub 上你的 “main” 分支了。
添加更多的变更。如果你想继续搞点变更并且将它们传到 GitHub 上，你只需要使用下面的三行命令：
```
git add .
git commit -m "在这里填写你的提交信息"
git push
```
提示，你可能还需要建立一个 .gitignore 文件来防止 Git 追踪一些文件并且让它们不会被上传到 GitHub，比如一些你写在本地仓库但并不想放到公开仓库的笔记文件。你可以在 .gitignore templates 找到一些现成的 .gitignore 文件模板。

提交信息（Commit Messages）

一条好的 Git 提交信息标题（subject line）可以理解为下方句子的填空：如果生效，这次提交将会 <你的提交信息标题>

在标题内，使用祈使语气和现在时态，即使用 “change” 而非 “changed” 或 “changes”。同理，在正文（body，可选）中也要用祈使语气和现在时态。正文中需要包括更改的动机，并对比与更改前后行为的变化。确保你说明的是为什么，而不是怎么做。

✅ 花几分钟逛逛 GitHub。你能找到感觉非常棒的提交信息吗？你可以找到非常简洁的提交信息吗？你认为在一条提交信息中，传达什么信息是最重要和有用的？

任务：协作

将项目放到 GitHub 的主要原因是让和其他开发者协作开发成为可能。

和其他人协作开发项目

在你的仓库中，前往 Insights > Community 来查看你的项目和推荐的社区规范的对比。

这里有一些你可以改进你的项目仓库的点：

项目描述（Description）。你为你的项目添加了描述吗？
README。你有添加 README 吗？GitHub 提供了撰写 README 的指南。
贡献指南（Contributing guideline）。你的项目是否有贡献指南？
行为准则（Code of Conduct）。添加一份行为准则
开源协议（License）。或许是最重要的，添加一个开源协议

所有这些资源对于新加入的团队成员都是很有好处的，这些一般是新的贡献者在看你的代码前会更先去看的东西，以确认你的项目是否值得他们在这上面花费时间。

✅ 尽管很多人都准备了 README 文件，但常常会因为太忙而疏于维护。你能找到一个这样的例子吗？注：这里有一些可以用于创建优秀的 README 的工具，你或许愿意试试。

任务：合并（Merge）一些代码

贡献文档帮助人们对项目做贡献，其中说明了你正需要什么样的贡献以及贡献的过程该是怎样的。贡献者需要完成一系列步骤才能在 GitHub 上参与你项目的贡献：

复刻（Fork）你的仓库。你可能希望人们复刻你的项目。复刻意味着在他们自己的 GitHub 账户下创建你的项目的一份副本。
克隆（Clone）。在这里他们将会将项目克隆到他们的本地机器上。
创建一个分支（Branch）。你可能希望他们能创建一个分支来进行他们的工作。
集中进行一个区域的修改。要求贡献者每次贡献只专注做一件事，这样你才更可能合并他们的工作。想象一下如果他们修了一个 BUG，添加了一个新特性，然后更新了几个测试，而你其实只想要其中的一个或两个更改时该怎么办？

✅ 想一想分支在什么情况下对于编写和发布优质的代码非常重要？你能想到哪些使用实例？

注意，要以身作则，对你自己的工作也要创建分支。任何提交都需要在当前“检出（checked out）”的分支上进行。使用 git status 来查看是哪一个分支。

让我们走一遍贡献者的工作流程。假设贡献者已经复刻并克隆了仓库，他们在本地机器已经有了一个可以工作的仓库：

创建一个分支。使用命令 git branch 来创建一个他们希望用来包含计划进行的变更的分支：
```
git branch [分支名]
```
切换到工作分支。使用 git checkout 来切换到指定分支并且更新工作目录中的文件：
```
git checkout [分支名]
```
干活。现在你可以添加你的变更了，别忘了用下面的命令告诉 Git 你所做的工作：
```
git add .
git commit -m "变更内容"
```
确保你的提交有一个好名字，不论是对你自己还是你正在帮助的仓库维护者来说都有好处。
将你的工作合入 main 分支。在完成工作后，你打算将你的工作和 main 分支上的合并。main 分支可能同时有了一些新的变更，所以要先用以下命令确保将其更新至最新版本：
```
git checkout main
git pull
```
这时你想确认是否存在 冲突（conflicts），即 Git 没法简单地将这些变化合入你的分支的情况。为此运行下面的命令：
```
git checkout [分支名]
git merge main
```
这将会把所有 main 分支上的变更带入到你的分支上。运气好的话一切都会自动搞定，否则 VS Code 会告诉你哪些文件 Git 不确定 该如何合并，你只需要手动修改对应文件来解决冲突即可。
将你的工作上传至 GitHub。将你的工作上传至 GitHub 意味着两件事：把你的分支上传到你自己的仓库，然后开启一个 PR（Pull Request）：
```
git push --set-upstream origin [分支名]
```
上述命令在你复刻的仓库中创建了一个分支。
开启一个 PR。接下来，你打算开启一个 PR。前往 GitHub 上你打算贡献的仓库，你将会看到一个消息条询问你是否想要创建一个新的 PR，点击后即可进入创建 PR 的界面。在这里你可以更改提交标题，给出更准确的描述。创建 PR 后，仓库维护者将会看到这个，如果 一切顺利 的话他们会表示感谢并且合并你的 PR。你现在就是一位贡献者啦！ :)
清理。成功合入一个 PR 后，做做清理是一个好习惯。你会想要清理本地和你上传到 GitHub 的分支。首先让我们通过下面的命令来删除本地的分支：
```
git branch -d [分支名]
```
接下来请确保前往 GitHub 中对应仓库的页面并删除你刚才上传的分支。

Pull request 这个术语看起来有些憨，因为你确实打算把你的变更提交到这个项目中。但是在将你的变更合入到项目的 main 分支前，维护者（项目拥有者）或者核心团队需要考虑和检查你的变更，这意味着你实际上是在请求（request）维护者的变更决定。

Pull Request 是一个可以用来比较和讨论一个分支引入的改动的地方，并有代码审查、评论、集成测试等功能。优质的 Pull Request 严格遵照与提交信息相同的规则。如果你的工作是为了修复一个 Issues 面板中的事项，你可以在 PR 中提及这个事项。具体做法是写一个 # 加上事项的编号，比如 #97。

🤞如果一切顺利，所有的检查都通过后项目拥有者就会将你的变更合入项目🤞

使用这个命令即可将 GitHub 上对应远程分支的所有新提交更新到当前本地的工作分支上：

git pull

如何参与开源贡献

首先，让我们在 GitHub 上找到一个你感兴趣且愿意参与贡献的仓库（repo），你会复制一份它的内容到你的机器上。

✅ 一个寻找对入门者友好的仓库的好办法是搜索 “good-first-issue” 标签。

有很多种复制代码的方法，其中一种就是“克隆”仓库的内容，可以用 HTTPS、SSH 或者 GitHub CLI（Command Line Interface）来做到。

打开你的终端并且用类似下方的命令来克隆仓库： git clone https://github.com/ProjectURL

切换到正确的工作目录： cd ProjectURL

你也可以用 Codespaces 来打开整个项目，这是 GitHub 内置的代码编辑器和云开发环境，或者用 GitHub Desktop。

当然，你也可以直接下载代码的压缩包。

🚀 挑战

找朋友一起编辑彼此的代码。协作创建一个项目、复刻代码、创建分支，然后合并变更。

课后小测

复习 & 自学

了解更多如何提交贡献。

Git cheatsheet。

练习，练习，再练习。GitHub 在 lab.github.com 提供了很棒的学习路径：

在 GitHub 的第一周

你还可以在上面找到更多高阶的实验内容。

作业

完成在 GitHub 的第一周

16 KiB Raw Blame History Unescape Escape