[开发工具]GitHub之深入解析如何创建、维护和管理自己的项目

一、创建新的版本库

• 创建一个版本库来分享我们的项目，通过点击面板右侧的“New repository”按钮，或者顶部工具条用户名旁边的 + 按钮来开始我们的旅程，这是 “Your repositories” 区域：

• 这是 “New repository” 下拉列表：

• 然后会带到 “new repository” 表单：

• 除了一个必须要填的项目名，其他字段都是可选的。现在只需要点击 “Create Repository” 按钮，就在 GitHub 上拥有了一个以 /<project_name> 命名的新仓库了。因为目前暂无代码，GitHub 会显示有关创建新版本库或者关联到一个已有的 Git 版本库的一些说明。
• 现在我们的项目就托管在 GitHub 上了，可以把 URL 给任何想分享的人。GitHub 上的项目可通过 HTTP 或 SSH 访问，HTTPS 为 https://github.com//<project_name> ，SSH 为 git@github.com:/<project_name>。 Git 可以通过以上两种 URL 进行抓取和推送，但是用户的访问权限又因连接时使用的证书不同而异。
• 通常对于公开项目可以优先分享基于 HTTPS 的 URL，因为用户克隆项目不需要有一个 GitHub 帐号。如果分享 SSH URL，用户必须有一个帐号并且上传 SSH 密钥才能访问我们的项目，HTTPS URL 与贴到浏览器里查看项目用的地址是一样的。

二、添加合作者

• 如果想与他人合作，并想给他们提交的权限，需要把他们添加为 “Collaborators”。如果 Ben，Jeff，Louise 都在 GitHub 上注册了，想给他们推送的权限，可以将他们添加到我们的项目，这样做会给他们 “推送” 权限，就是说他们对项目和 Git 版本库都有读写的权限。
• 点击边栏底部的 “Settings” 链接：

• 然后从左侧菜单中选择 “Collaborators”，在输入框中填写用户名，点击 “Add collaborator” 如果想授权给多个人，可以多次重复这个步骤；如果想收回权限，点击他们同一行右侧的 “X”：

三、管理合并请求

• 现在有一个包含一些代码的项目，可能还有几个有推送权限的合作者，下面来看当收到合并请求时该做什么。合并请求可以来自仓库副本的一个分支，或者同一仓库的另一个分支，唯一的区别是 fork 过来的通常是和不能互相推送的人，而内部的推送通常都可以互相访问。
• 举个例子，假设我们是 “tonychacon” ，创建了一个名为 “fade” 的 Arduino 项目。

① 邮件通知

• 有人来修改了我们的代码，并且发了一个合并请求，我们会收一封关于合并请求的提醒邮件，它看起来像新的合并请求的邮件通知：

• 关于这个邮件有几个要注意的地方：它会给我们一个小的变动统计结果，?一个包含合并请求中改变的文件和改变了多少的列表，它还会给一个 GitHub 上进行合并请求操作的链接，还有几个可以在命令行使用的 URL。
• 如果注意到 git pull patch-1 这一行，它是一种合并远程分支的简单方式，无需必须添加一个远程分支。如果愿意，可以创建并切换到一个主题分支，然后运行这个命令把合并请求合并进来。
• 还有一些有趣的 URL，像 .diff 和 .patch，就像猜的那样，它们提供 diff 和 patch 的标准版本。可以技术性地用下面的方法合并“合并请求”：

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

② 在合并请求上进行合作

• 就像我们在GitHub之深入解析如何对项目做出贡献 中的 GitHub 流程说过的，现在可以跟开启合并请求的人进行会话，既可以对某些代码发表评论，也可以对整个提交或整个合并请求发表评论，在任何地方都可以用 GitHub 风格的 Markdown。
• 每次有人在合并请求上发表了评论，都会收到邮件，通知哪里发生了改变。邮件里面包含一个链接，指向改变的位置，可以直接在邮件中回复，相当于在合并请求上发表评论：

• 一旦代码符合了要求，想把它合并进来，可以把代码拉取下来在本地进行合并，也可以用我们之前提到过的 git pull 语法，或者把 fork 添加为一个 remote，然后进行抓取和合并。
• 对于很琐碎的合并，也可以用 GitHub 网站上的 “Merge” 按钮，它会做一个 “non-fast-forward” 合并，即使可以快进（fast-forward）合并也会产生一个合并提交记录。 就是说无论如何，只要点击 merge 按钮，就会产生一个合并提交记录，如下所示，如果点击提示链接，GitHub 会给出所有的这些信息：

• 如果决定不合并它，可以把合并请求关掉，开启合并请求的人会收到通知。

③ 合并请求引用

• 如果正在处理许多的合并请求，不想添加一堆 remote 或者每次都要做一次拉取，这里有一个可以在 GitHub 上用的小技巧：实际上 GitHub 在服务器上把合并请求分支视为一种 “假分支”，默认情况下克隆时不会得到它们，但它们还是隐式地存在，可以很容易地访问到它们。
• 为了展示这个，我们要用到一个叫做 ls-remote 的低级命令（通常被叫做“plumbing”），这个命令在日常 Git 操作中基本不会用到，但在显示服务器上有哪些引用（reference）时很管用。如果在我们之前用过的 “blink” 版本库上使用这个命令，我们会得到一个版本库里所有的分支，标签和其它引用（reference）的列表：

$ 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 这个 remote，下载名字为 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”，它是一种把 remote 的名称映射到本地 .git 目录的方法，这一条（就是上面的这一条）告诉 Git，“remote 上 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
# …

• 现在所有的合并请求在本地像分支一样展现，它们是只读的，当执行抓取时它们也会更新。这让在本地测试合并请求中的代码变得超级简单：

$ 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 的 remote 部分的结尾有个 head，在 GitHub 那边也有一个 refs/pull/#/merge 引用，它代表的是如果在网站上按了 “merge” 按钮对应的提交记录，这甚至可以在按按钮之前就测试这个合并。

④ 合并请求之上的合并请求

• 不仅可以在主分支或者说 master 分支上开启合并请求，实际上也可以在网络上的任何一个分支上开启合并请求。其实，甚至可以在另一个合并请求上开启一个合并请求。
• 如果看到一个合并请求在向正确的方向发展，然后想在这个合并请求上做一些修改或者不太确定这是个好主意，或者没有目标分支的推送权限，可以直接在合并请求上开启一个合并请求。当开启一个合并请求时，在页面的顶端有一个框框显示要合并到哪个分支和从哪个分支合并过来的，如果点击那个框框右边的 “Edit” 按钮，不仅可以改变分支，还可以选择哪个 fork：

• 这里你可以很简单地指明合并你的分支到哪一个合并请求或 fork。

四、提醒和通知

• GitHub 内置了一个很好的通知系统，当需要与别人或别的团队交流时用起来很方便。在任何评论中可以先输入一个 @ ，系统会自动补全项目中合作者或贡献者的名字和用户名：

• 我们也可以提醒不在列表中的用户，但是通常自动补全用起更快。当发布了一个带用户提醒的评论，那个用户会收到通知，这意味着把人们拉进会话中要比让他们投票有效率得多。对于 GitHub 上的合并请求，人们经常把他们团队或公司中的其它人拉来审查问题或合并请求。
• 如果有人收到了合并请求或问题的提醒，他们会“订阅”它，后面有新的活动发生他们都会持续收到提醒。如果你是合并请求或者问题的发起方我们也会被订阅上，比如在关注一个版本库或者评论了什么东西，如果我们不想再收到提醒，在页面上有个 “Unsubscribe” 按钮，点一下就不会再收到更新了：

① 通知页面

• 当我们在这提到特指 GitHub 的 “notifications”，指的是当 GitHub 上有事件发生时，它通知你的方式，这里有几种不同的方式来配置它们。如果打开配置页面的 “Notification center” 标签，可以看到一些选项：

• 有两个选项，通过“邮件（Email）”和通过“网页（Web）”，可以选用一个或者都不选或者都选。

② 网页通知

• 网页通知只在 GitHub 上存在，也只能在 GitHub 上查看，如果打开了这个选项并且有一个通知，会在屏幕上方的通知图标上看到一个小蓝点：

• 如果点击那个玩意儿，会看到被通知到的所有条目，按照项目分好了组，可以点击左边栏的项目名字来过滤项目相关的通知，可以点击通知旁边的对号图标把通知标为已读，或者点击组上面的图标把项目中所有的通知标为已读。在每个对号图标旁边都有一个静音按钮，可以点一下，以后就不会收到它相关的通知。
• 所有这些工具对于处理大量通知非常有用，很多 GitHub 资深用户都关闭邮件通知，在这个页面上处理他们所有的通知。

③ 邮件通知

• 邮件通知是处理 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> 的格式展现所有的数据。 例如，如果这是一个问题（issue），那么 字段就会是 “issues” 而不是 “pull” 。
• List-Post 和 List-Unsubscribe 字段表示如果邮件客户端能够处理这些，那么可以很容易地在列表中发贴或取消对这个相关帖子的订阅。那会很有效率，就像在页面中点击静音按钮或在问题/合并请求页面点击 “Unsubscribe” 一样。值得注意的是，如果同时打开了邮件和网页通知，那么当在邮件客户端允许加载图片的情况下阅读邮件通知时，对应的网页通知也将会同时被标记为已读。

五、特殊文件

① README

• 第一个就是 README 文件，可以是几乎任何 GitHub 可以识别的格式。 例如，它可以是 README ，README.md，README.asciidoc。如果 GitHub 在版本库中找到 README 文件，会把它在项目的首页渲染出来。
• 很多团队在这个文件里放版本库或项目新人需要了解的所有相关的信息，它一般包含这些内容：
• • 该项目的作用；
• • 如何配置与安装；
• • 有关如何使用和运行的例子；
• • 项目的许可证；
• • 如何向项目贡献力量。
• 因为 GitHub 会渲染这个文件，可以在文件里植入图片或链接让它更容易理解。

② 贡献 CONTRIBUTING

• 另一个 GitHub 可以识别的特殊文件是 CONTRIBUTING，如果有一个任意扩展名的 CONTRIBUTING 文件，当有人开启一个合并请求时 GitHub 会显示开启合并请求时有 CONTRIBUTING 文件存在：

• 这个的作用就是可以在这里指出对于项目开启的合并请求想要的／不想要的各种事情，这样别人在开启合并请求之前可以读到这些指导方针。

六、项目管理

• 对于一个单个项目其实没有很多管理事务要做，但也有几点有趣的。

① 改变默认分支

• 如果想用 “master” 之外的分支作为默认分支，其他人将默认会在这个分支上开启合并请求或进行浏览，可以在版本库的设置页面的 “options” 标签下修改：

• 简单地改变默认分支下拉列表中的选项，它就会作为所有主要操作的默认分支，他人进行克隆时该分支也将被默认检出。

② 移交项目

• 如果想把一个项目移交给 GitHub 中的另一个人或另一个组织，还是设置页面的这个 “options” 标签下有一个 “Transfer ownership” 选项可以用来干这个：

• 当正准备放弃一个项目且正好有别人想要接手时，或者项目壮大了想把它移到一个组织里时，这就管用了。这么做不仅会把版本库连带它所有的关注者和星标数都移到另一个地方，它还会将 URL 重定向到新的位置，它也重定向了来自 Git 的克隆和抓取，而不仅仅是网页端请求。

七、管理组织

• 除了个人帐户之外，GitHub 还提供被称为组织（Organizations）的帐户，组织账户和个人账户一样都有一个用于存放所拥有项目的命名空间，但是许多其他的东西都是不同的，组织帐户代表了一组共同拥有多个项目的人，同时也提供一些工具用于对成员进行分组管理。通常，这种账户被用于开源群组（例如：“perl”或者“rails”），或者公司（例如：“google”或者“twitter”）。

① 组织的基本知识

• 可以很简单地创建一个组织，只需要点击任意 GitHub 页面右上角的“+”图标，在菜单中选择“New organization”即可：

• 首先你须提供组织的名称和组织的主要联系邮箱。然后，如果希望的话，也可以邀请其他用户作为共同拥有人。完成以上步骤后，就会拥有一个全新的组织。类似于个人帐户，如果组织的所有内容都是开源的，那么就可以免费使用这个组织。
• 作为一个组织的拥有者，当在派生一个版本库的时候，可以选择把它派生到我们自己的组织的命名空间内。当新建版本库时，可以把它存放到个人帐户或我们拥有的组织内，同时，也会自动地“关注”所有这些组织内的新版本库。
• 就像头像，可以为组织上传头像，使它更个性化。同时，也和个人帐户类似，组织会有一个着陆页（landing page），用于列出该组织所有的版本库，并且该页面可供所有人浏览。

② 团队

• 组织使用团队（Teams）来管理成员，团队就是组织中的一组个人账户和版本库，以及团队成员对这些版本库的访问权限。
• 例如，假设我们的公司有三个版本库：frontend、backend 和 deployscripts，就会希望 HTML/CSS/Javascript 开发者有 frontend 或者 backend 的访问权限，操作人员有 backend 和 deployscripts 的访问权限，团队让这个任务变得更简单，而不用为每个版本库管理它的协作者。
• 组织页面主要由一个面板（dashboard）构成，这个仪表盘包含了这个组织内的所有版本库，用户和团队：

• 可以点击上图中右边的团队侧边栏（Teams）来管理团队。点击之后，就会进入一个新页面，在这里可以添加新成员和版本库到团队中，或者管理团队的访问权限和其它设置，每个团队对于版本库可以有只读、读写和管理三种权限，可以通过点击在如下页面内的 “Settings” 按钮更改相应权限等级：

• 当邀请一个用户加入团队，该用户会收到一封通知他被邀请的邮件。除此之外，团队也类似于个人帐户，有 @mentions（例如：@acmecorp/frontend）的功能，不同之处就在于被提及的团队内所有成员都会成为这个话题的订阅者。当希望得到团队中某个人的关注，又不知道具体应该问谁的时候，这个功能就显得很有帮助。
• 一个用户可以加入任意数量的团队，所以别把自己局限于拥有访问控制的团队。对于某一类课题，像 ux, css 或者 refactoring 这样有着特殊关注点的团队就显得很有帮助，而像 legal 和 colorblind 这样的就完全是针对它们各自领域的。

③ 审计日志

• 组织的拥有者还可以访问组织中发生的事情的所有信息，在 Audit Log 标签页有整个组织的日志，可以看到谁在世界上哪个地方做了什么事：

• 也可以通过选定某一类型的事件、某个地方、某个人对日志进行过滤。