章节 ▾ 第二版

6.3 GitHub - 维护项目

维护项目

既然我们已经熟练地向项目贡献代码了，那么接下来看看另一面：创建、维护和管理自己的项目。

创建新仓库

我们来创建一个新仓库，以便分享项目代码。首先点击仪表盘右侧的“New repository”按钮，或者点击顶部工具栏用户名旁边的“+”按钮，如“New repository”下拉菜单所示。

The “Your repositories” area
图 109. “Your repositories”区域
The “New repository” dropdown
图 110. “New repository”下拉菜单

这将带你进入“New repository”表单。

The “new repository” form
图 111. “New repository”表单

你真正需要做的就是提供一个项目名称；其余字段完全可选。现在，只需点击“Create Repository”按钮，砰——你就有一个新的 GitHub 仓库了，命名为<user>/<project_name>。

由于你还没有代码，GitHub 将会向你展示如何创建一个全新的 Git 仓库，或者如何连接一个现有 Git 项目的说明。我们在这里不再赘述；如果你需要复习，请查阅Git 基础。

现在你的项目已经托管在 GitHub 上了，你可以将 URL 提供给任何你想分享项目的人。GitHub 上的每个项目都可以通过 HTTPS 访问，URL 为 https://github.com/<user>/<project_name>，也可以通过 SSH 访问，URL 为 git@github.com:<user>/<project_name>。Git 可以从这两个 URL 拉取和推送，但它们是根据连接用户的凭据进行访问控制的。

注意

对于公共项目，通常更倾向于分享基于 HTTPS 的 URL，因为用户无需拥有 GitHub 账户即可克隆项目。如果你向他们提供了 SSH URL，用户则必须拥有账户并上传 SSH 密钥才能访问你的项目。HTTPS URL 也与他们在浏览器中查看项目时粘贴的 URL 完全相同。

添加协作者

如果你与其他希望授予提交权限的人协作，你需要将他们添加为“协作者”。如果 Ben、Jeff 和 Louise 都在 GitHub 上注册了账户，并且你希望授予他们向你的仓库推送的权限，你可以将他们添加到你的项目。这样做将授予他们“推送”权限，这意味着他们对项目和 Git 仓库同时拥有读写权限。

点击右侧边栏底部的“Settings”链接。

The repository settings link
图 112. 仓库设置链接

然后从左侧菜单中选择“Collaborators”。接下来，只需在框中输入用户名，然后点击“Add collaborator”。你可以根据需要重复此操作，以授予所有你喜欢的人访问权限。如果你需要撤销访问权限，只需点击他们行右侧的“X”。

The repository collaborators box
图 113. 仓库协作者框

管理拉取请求

现在你有一个包含一些代码的项目，甚至可能还有一些拥有推送权限的协作者，让我们来看看当你自己收到拉取请求时该怎么做。

拉取请求可能来自你的仓库的一个分支的派生，也可能来自同一仓库的另一个分支。唯一的区别是，派生中的拉取请求通常来自你无法推送到其分支，他们也无法推送到你的分支的人，而内部拉取请求通常双方都可以访问该分支。

在这些示例中，我们假设你是“tonychacon”，并且你创建了一个名为“fade”的新 Arduino 代码项目。

电子邮件通知

有人对你的代码进行了更改并向你发送了拉取请求。你应该会收到一封通知你新的拉取请求的电子邮件，它看起来应该像新拉取请求的电子邮件通知。

Email notification of a new Pull Request
图 114. 新拉取请求的电子邮件通知

这封电子邮件有几点值得注意。它会给你一个简短的 diffstat——一个拉取请求中更改的文件列表以及更改的程度。它给你一个指向 GitHub 上拉取请求的链接。它还提供了一些你可以从命令行使用的 URL。

如果你注意到那行写着 git pull <url> patch-1，这是一种简单地合并远程分支而无需添加远程的方法。我们在检出远程分支中快速介绍了这一点。如果你愿意，你可以创建并切换到一个主题分支，然后运行此命令来合并拉取请求的更改。

另外两个有趣的 URL 是 .diff 和 .patch URL，顾名思义，它们提供了拉取请求的统一差异和补丁版本。你可以在技术上使用类似这样的方式合并拉取请求的工作：

$ curl https://github.com/tonychacon/fade/pull/1.patch | git am

协作处理拉取请求

正如我们在GitHub 工作流中介绍的那样，你现在可以与打开拉取请求的人进行对话。你可以评论特定代码行、评论整个提交或评论整个拉取请求本身，所有这些都使用 GitHub 风格的 Markdown。

每当其他人评论拉取请求时，你都会继续收到电子邮件通知，以便你知道有活动发生。每封邮件都会有一个指向正在发生活动的拉取请求的链接，你也可以直接回复邮件以评论拉取请求线程。

Responses to emails are included in the thread
图 115. 电子邮件回复包含在线程中

一旦代码达到你满意并希望合并的位置，你可以拉取代码并在本地合并，无论是使用我们之前看到的 git pull <url> <branch> 语法，还是通过添加 fork 作为远程并进行 fetch 和合并。

如果合并是微不足道的，你也可以直接点击 GitHub 网站上的“Merge”按钮。这将执行“非快进”合并，即使快进合并是可能的，也会创建一个合并提交。这意味着无论如何，每次你点击合并按钮，都会创建一个合并提交。正如你在合并按钮以及手动合并拉取请求的说明中看到的，如果你点击提示链接，GitHub 会为你提供所有这些信息。

Merge button and instructions for merging a Pull Request manually
图 116. 合并按钮以及手动合并拉取请求的说明

如果你决定不合并它，你也可以直接关闭拉取请求，打开它的人将收到通知。

拉取请求引用

如果你处理**大量**的拉取请求，并且不想每次都添加一堆远程或进行一次性拉取，那么 GitHub 提供了一个巧妙的技巧。这有点高级，我们将在引用规范中更详细地介绍它，但它可能非常有用。

GitHub 实际上会将仓库的拉取请求分支作为服务器上的伪分支来宣传。默认情况下，你克隆时不会得到它们，但它们以一种模糊的方式存在，并且你可以很轻松地访问它们。

为了演示这一点，我们将使用一个底层命令（通常称为“plumbing”命令，我们将在底层命令和上层命令中详细了解）ls-remote。此命令通常不用于日常 Git 操作，但它对于显示服务器上存在哪些引用很有用。

如果我们对之前使用的“blink”仓库运行此命令，我们将获得仓库中所有分支、标签和其他引用的列表。

$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d	HEAD
10d539600d86723087810ec636870a504f4fee4d	refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e	refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3	refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1	refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d	refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a	refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c	refs/pull/4/merge

当然，如果你在你的仓库中运行 git ls-remote origin 或任何你想检查的远程，它会显示类似这样的内容。

如果仓库在 GitHub 上并且你有一些已打开的拉取请求，你将获得这些以 refs/pull/ 为前缀的引用。它们基本上是分支，但由于它们不在 refs/heads/ 下，所以你在克隆或从服务器拉取时通常不会得到它们——拉取过程通常会忽略它们。

每个拉取请求有两个引用——以 /head 结尾的引用指向拉取请求分支中最后一个提交的完全相同的提交。因此，如果有人在我们的仓库中打开一个拉取请求，并且他们的分支名为 bug-fix 并指向提交 a5a775，那么在**我们的**仓库中，我们将没有 bug-fix 分支（因为它在他们的 fork 中），但我们*将*有一个 pull/<pr#>/head 指向 a5a775。这意味着我们可以非常轻松地一次性拉取所有拉取请求分支，而无需添加一堆远程。

现在，你可以直接获取引用。

$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
 * branch            refs/pull/958/head -> FETCH_HEAD

这告诉 Git：“连接到 `origin` 远程，并下载名为 `refs/pull/958/head` 的引用。” Git 愉快地服从，下载了构建该引用所需的一切，并将指向你想要的提交的指针放在 `.git/FETCH_HEAD` 下。你可以接着将 `git merge FETCH_HEAD` 合并到你想要测试它的分支中，但合并提交消息看起来有点奇怪。此外，如果你正在审查**大量**拉取请求，这会变得很繁琐。

还有一种方法可以获取**所有**拉取请求，并在你连接到远程时保持它们最新。在你喜欢的编辑器中打开 .git/config，然后查找 origin 远程。它应该看起来像这样：

[remote "origin"]
    url = https://github.com/libgit2/libgit2
    fetch = +refs/heads/*:refs/remotes/origin/*

那行以 fetch = 开头的行是一个“refspec”。它是一种将远程上的名称与本地 .git 目录中的名称进行映射的方式。这个特定的 refspec 告诉 Git：“远程上 refs/heads 下的内容应该进入我的本地仓库的 refs/remotes/origin 下。”你可以修改此部分以添加另一个 refspec：

[remote "origin"]
    url = https://github.com/libgit2/libgit2.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

最后一行告诉 Git：“所有看起来像 refs/pull/123/head 的引用都应该在本地存储为 refs/remotes/origin/pr/123。”现在，如果你保存该文件，并执行 git fetch：

$ git fetch
# …
 * [new ref]         refs/pull/1/head -> origin/pr/1
 * [new ref]         refs/pull/2/head -> origin/pr/2
 * [new ref]         refs/pull/4/head -> origin/pr/4
# …

现在，所有远程拉取请求都在本地由引用表示，其行为与跟踪分支非常相似；它们是只读的，并且在你执行 fetch 时会更新。这使得在本地尝试拉取请求中的代码变得超级简单：

$ git checkout pr/2
Checking out files: 100% (3769/3769), done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'

眼尖的读者可能会注意到 refspec 远程部分末尾的 head。在 GitHub 端还有一个 refs/pull/#/merge 引用，它表示如果你点击网站上的“merge”按钮将产生的提交。这允许你在实际点击按钮之前测试合并。

拉取请求上的拉取请求

你不仅可以打开目标是主分支或 master 分支的拉取请求，你实际上还可以打开目标是网络中任何分支的拉取请求。事实上，你甚至可以目标另一个拉取请求。

如果你看到一个拉取请求朝着正确的方向发展，并且你有一个依赖于它的更改想法，或者你不确定这是否是一个好主意，或者你只是没有推送到目标分支的权限，你可以直接向它打开一个拉取请求。

当你去打开一个拉取请求时，页面顶部有一个框，指定你要拉取到哪个分支以及从哪个分支拉取。如果你点击该框右侧的“Edit”按钮，你不仅可以更改分支，还可以更改哪个 fork。

Manually change the Pull Request target fork and branch
图 117. 手动更改拉取请求目标 fork 和分支

在这里你可以相当容易地指定将你的新分支合并到另一个拉取请求或项目的另一个派生中。

提及和通知

GitHub 还内置了一个非常好的通知系统，当你有问题或需要特定个人或团队的反馈时，它会派上用场。

在任何评论中，你都可以开始输入一个 @ 字符，它将开始自动补全项目中的协作者或贡献者的姓名和用户名。

Start typing @ to mention someone
图 118. 开始输入 @ 提及某人

你也可以提及不在该下拉列表中的用户，但自动补全通常可以使其更快。

一旦你发布了一条带有用户提及的评论，该用户就会收到通知。这意味着这是一种将人们拉入对话而非让他们投票的非常有效的方式。在 GitHub 的拉取请求中，人们经常会拉入团队或公司的其他人来审查问题或拉取请求。

如果有人在拉取请求或问题中被提及，他们将被“订阅”该项目，并且每当有活动发生时，他们将继续收到通知。如果你打开了它，如果你正在关注该仓库，或者如果你评论了某些内容，你也将被订阅。如果你不再希望收到通知，页面上有一个“Unsubscribe”按钮，你可以点击该按钮停止接收更新。

Unsubscribe from an Issue or Pull Request
图 119. 取消订阅问题或拉取请求

通知页面

当我们在 GitHub 上提及“通知”时，我们指的是 GitHub 在事件发生时与您联系的特定方式，并且您可以通过几种不同的方式配置它们。如果您从设置页面转到“通知中心”选项卡，您可以看到一些可用的选项。

Notification center options
图 120. 通知中心选项

有两个选择：通过“电子邮件”和通过“Web”接收通知，您可以选择其中一个、都不选或两者都选，用于您积极参与的事件和您正在关注的仓库上的活动。

网络通知

网络通知仅存在于 GitHub 上，并且只能在 GitHub 上查看。如果你在偏好设置中选择了此选项并且为你触发了通知，你将在屏幕顶部看到通知图标上方有一个小蓝点，如通知中心所示。

Notification center
图 121. 通知中心

如果你点击它，你将看到所有你已收到通知的项目列表，按项目分组。你可以通过点击左侧边栏中的项目名称来筛选特定项目的通知。你还可以通过点击任何通知旁边的勾号图标来确认通知，或者通过点击分组顶部的勾号来确认项目中的**所有**通知。每个勾号旁边还有一个静音按钮，你可以点击它来停止接收该项目的任何进一步通知。

所有这些工具对于处理大量通知都非常有用。许多 GitHub 高级用户会干脆完全关闭电子邮件通知，并通过此屏幕管理所有通知。

电子邮件通知

电子邮件通知是你在 GitHub 上处理通知的另一种方式。如果你启用了此功能，你将收到每条通知的电子邮件。我们在以电子邮件通知发送的评论和新拉取请求的电子邮件通知中看到了示例。电子邮件也会正确地形成线程，如果你使用的是支持线程的电子邮件客户端，这将非常方便。

GitHub 发送给你的电子邮件的头部还嵌入了大量的元数据，这对于设置自定义过滤器和规则非常有帮助。

例如，如果我们查看新拉取请求的电子邮件通知中显示给 Tony 的电子邮件的实际电子邮件头，我们将看到以下信息：

To: tonychacon/fade <fade@noreply.github.com>
Message-ID: <tonychacon/fade/pull/1@github.com>
Subject: [fade] Wait longer to see the dimming effect better (#1)
X-GitHub-Recipient: tonychacon
List-ID: tonychacon/fade <fade.tonychacon.github.com>
List-Archive: https://github.com/tonychacon/fade
List-Post: <mailto:reply+i-4XXX@reply.github.com>
List-Unsubscribe: <mailto:unsub+i-XXX@reply.github.com>,...
X-GitHub-Recipient-Address: tchacon@example.com

这里有一些有趣的事情。如果你想突出显示或重新路由发往此特定项目甚至拉取请求的电子邮件，Message-ID 中的信息以 <user>/<project>/<type>/<id> 格式为你提供所有数据。例如，如果这是一个问题，<type> 字段将是“issues”而不是“pull”。

List-Post 和 List-Unsubscribe 字段意味着如果你有一个理解这些的邮件客户端，你可以轻松地向列表发布或从线程中“取消订阅”。这基本上与点击网页版通知上的“静音”按钮或问题或拉取请求页面本身上的“取消订阅”相同。

值得注意的是，如果你同时启用了电子邮件和网络通知，并且你在邮件客户端中允许图像，那么当你阅读电子邮件版本的通知时，网络版本也将被标记为已读。

特殊文件

如果你的仓库中存在一些特殊文件，GitHub 会注意到它们。

README

第一个是 README 文件，它可以是 GitHub 识别为散文的几乎任何格式。例如，它可以是 README、README.md、README.asciidoc 等。如果 GitHub 在你的源代码中看到 README 文件，它将在项目的着陆页上渲染它。

许多团队使用此文件来保存所有与项目相关的信息，供可能不熟悉仓库或项目的人员使用。这通常包括以下内容：

  • 项目的用途

  • 如何配置和安装它

  • 如何使用或运行它的示例

  • 项目所提供的许可证

  • 如何贡献

由于 GitHub 会渲染此文件，你可以在其中嵌入图像或链接，以增加易懂性。

贡献

GitHub 识别的另一个特殊文件是 CONTRIBUTING 文件。如果你有一个名为 CONTRIBUTING 且带有任何文件扩展名的文件，当有人开始打开拉取请求时，GitHub 将显示存在 CONTRIBUTING 文件时打开拉取请求。

Opening a Pull Request when a CONTRIBUTING file exists
图 122. 存在 CONTRIBUTING 文件时打开拉取请求

这里的想法是，你可以指定你希望或不希望在发送到你的项目的拉取请求中包含的特定内容。这样，人们在打开拉取请求之前可能真的会阅读这些准则。

项目管理

通常，单个项目并没有太多可供管理的行政事项，但有几个项目可能值得关注。

更改默认分支

如果你使用的默认分支不是“master”，而是你希望人们默认在该分支上打开拉取请求或查看，你可以在仓库设置页面下的“Options”选项卡中更改它。

Change the default branch for a project
图 123. 更改项目的默认分支

只需在下拉菜单中更改默认分支，此后它将成为所有主要操作的默认值，包括有人克隆仓库时默认检出的分支。

转移项目

如果你想将项目转移到 GitHub 中的另一个用户或组织，在你的仓库设置页面中“Options”选项卡的底部有一个“Transfer ownership”选项，允许你执行此操作。

Transfer a project to another GitHub user or Organization
图 124. 将项目转移到另一个 GitHub 用户或组织

如果你要放弃一个项目，而有人想接管它，或者如果你的项目越来越大，想把它移到一个组织中，这很有帮助。

这不仅会将仓库连同所有观察者和星标转移到另一个位置，还会设置从你的 URL 到新位置的重定向。它还会重定向 Git 的克隆和拉取，而不仅仅是网络请求。