Git 公开项目

公开的小型项目

上面说的是私有项目协作，但要给公开项目作贡献，情况就有些不同了。因为你没有直接更新主仓库分支的权限，得寻求其它方式把工作成果交给项目维护人。下面会介绍两种方法，第一种使用 git 托管服务商提供的仓库复制功能，一般称作 fork，比如 repo.or.cz 和 GitHub 都支持这样的操作，而且许多项目管理员都希望大家使用这样的方式。另一种方法是通过电子邮件寄送文件补丁。

但不管哪种方式，起先我们总需要克隆原始仓库，而后创建特性分支开展工作。基本工作流程如下：

$ git clone (url)    $ cd project    $ git checkout -b featureA    $ (work)    $ git commit    $ (work)    $ git commit

你可能想到用 rebase -i 将所有更新先变作单个提交，又或者想重新安排提交之间的差异补丁，以方便项目维护者审阅 -- 有关交互式衍合操作的细节见第六章。

在完成了特性分支开发，提交给项目维护者之前，先到原始项目的页面上点击“Fork”按钮，创建一个自己可写的公共仓库（译注：即下面的 url 部分，参照后续的例子，应该是 git://githost/simplegit.git）。然后将此仓库添加为本地的第二个远端仓库，姑且称为 myfork：

$ git remote add myfork (url)

你需要将本地更新推送到这个仓库。要是将远端 master 合并到本地再推回去，还不如把整个特性分支推上去来得干脆直接。而且，假若项目维护者未采纳你的贡献的话（不管是直接合并还是 cherry pick），都不用回退（rewind）自己的 master 分支。但若维护者合并或 cherry-pick 了你的工作，最后总还可以从他们的更新中同步这些代码。好吧，现在先把 featureA 分支整个推上去：

$ git push myfork featureA

然后通知项目管理员，让他来抓取你的代码。通常我们把这件事叫做 pull request。可以直接用 GitHub 等网站提供的 “pull request” 按钮自动发送请求通知；或手工把 git request-pull 命令输出结果电邮给项目管理员。

request-pull 命令接受两个参数，第一个是本地特性分支开始前的原始分支，第二个是请求对方来抓取的 Git 仓库 URL（译注：即下面 myfork 所指的，自己可写的公共仓库）。比如现在Jessica 准备要给 John 发一个 pull requst，她之前在自己的特性分支上提交了两次更新，并把分支整个推到了服务器上，所以运行该命令会看到：

$ git request-pull origin/master myfork    The following changes since commit 1edee6b1d61823a2de3b09c160d7080b8d1b3a40:    John Smith (1):    added a new function    are available in the git repository at:    git://githost/simplegit.git featureA    Jessica Smith (2):    add limit to log function    change log output to 30 from 25    lib/simplegit.rb | 10 +++++++++-    1 files changed, 9 insertions(+), 1 deletions(-)

输出的内容可以直接发邮件给管理者，他们就会明白这是从哪次提交开始旁支出去的，该到哪里去抓取新的代码，以及新的代码增加了哪些功能等等。

像这样随时保持自己的 master 分支和官方 origin/master 同步，并将自己的工作限制在特性分支上的做法，既方便又灵活，采纳和丢弃都轻而易举。就算原始主干发生变化，我们也能重新衍合提供新的补丁。比如现在要开始第二项特性的开发，不要在原来已推送的特性分支上继续，还是按原始master 开始：

$ git checkout -b featureB origin/master    $ (work)    $ git commit    $ git push myfork featureB    $ (email maintainer)    $ git fetch origin

现在，A、B 两个特性分支各不相扰，如同竹筒里的两颗豆子，队列中的两个补丁，你随时都可以分别从头写过，或者衍合，或者修改，而不用担心特性代码的交叉混杂。如图 5-16 所示：

图 5-16. featureB 以后的提交历史

假设项目管理员接纳了许多别人提交的补丁后，准备要采纳你提交的第一个分支，却发现因为代码基准不一致，合并工作无法正确干净地完成。这就需要你再次衍合到最新的 origin/master，解决相关冲突，然后重新提交你的修改：

$ git checkout featureA    $ git rebase origin/master    $ git push -f myfork featureA

自然，这会重写提交历史，如图 5-17 所示：

图 5-17. featureA 重新衍合后的提交历史

注意，此时推送分支必须使用 -f 选项（译注：表示 force，不作检查强制重写）替换远程已有的 featureA 分支，因为新的 commit 并非原来的后续更新。当然你也可以直接推送到另一个新的分支上去，比如称作 featureAv2。

再考虑另一种情形：管理员看过第二个分支后觉得思路新颖，但想请你改下具体实现。我们只需以当前 origin/master 分支为基准，开始一个新的特性分支 featureBv2，然后把原来的 featureB 的更新拿过来，解决冲突，按要求重新实现部分代码，然后将此特性分支推送上去：

$ git checkout -b featureBv2 origin/master    $ git merge --no-commit --squash featureB    $ (change implementation)    $ git commit    $ git push myfork featureBv2

这里的 --squash 选项将目标分支上的所有更改全拿来应用到当前分支上，而 --no-commit 选项告诉 Git 此时无需自动生成和记录（合并）提交。这样，你就可以在原来代码基础上，继续工作，直到最后一起提交。

好了，现在可以请管理员抓取 featureBv2 上的最新代码了，如图 5-18 所示：

图 5-18. featureBv2 之后的提交历史

公开的大型项目

许多大型项目都会立有一套自己的接受补丁流程，你应该注意下其中细节。但多数项目都允许通过开发者邮件列表接受补丁，现在我们来看具体例子。

整个工作流程类似上面的情形：为每个补丁创建独立的特性分支，而不同之处在于如何提交这些补丁。不需要创建自己可写的公共仓库，也不用将自己的更新推送到自己的服务器，你只需将每次提交的差异内容以电子邮件的方式依次发送到邮件列表中即可。

$ git checkout -b topicA    $ (work)    $ git commit    $ (work)    $ git commit

如此一番后，有了两个提交要发到邮件列表。我们可以用 git format-patch 命令来生成 mbox 格式的文件然后作为附件发送。每个提交都会封装为一个 .patch 后缀的 mbox 文件，但其中只包含一封邮件，邮件标题就是提交消息（译注：额外有前缀，看例子），邮件内容包含补丁正文和 Git 版本号。这种方式的妙处在于接受补丁时仍可保留原来的提交消息，请看接下来的例子：

$ git format-patch -M origin/master    0001-add-limit-to-log-function.patch    0002-changed-log-output-to-30-from-25.patch

format-patch 命令依次创建补丁文件，并输出文件名。上面的 -M 选项允许 Git 检查是否有对文件重命名的提交。我们来看看补丁文件的内容：

$ cat 0001-add-limit-to-log-function.patch    From 330090432754092d704da8e76ca5c05c198e71a8 Mon Sep 17 00:00:00 2001    From: Jessica Smith <[e-mail]>    Date: Sun, 6 Apr 2008 10:17:23 -0700    Subject: [PATCH 1/2] add limit to log function    Limit log functionality to the first 20    ---    lib/simplegit.rb | 2 +-    1 files changed, 1 insertions(+), 1 deletions(-)    diff --git a/lib/simplegit.rb b/lib/simplegit.rb    index 76f47bc..f9815f1 100644    --- a/lib/simplegit.rb    +++ b/lib/simplegit.rb    @@ -14,7 +14,7 @@ class SimpleGit    end    def log(treeish = 'master')    - command("git log #{treeish}")    + command("git log -n 20 #{treeish}")    end    def ls_tree(treeish = 'master')    --    1.6.2.rc1.20.g8c5b.dirty

如果有额外信息需要补充，但又不想放在提交消息中说明，可以编辑这些补丁文件，在第一个 --- 行之前添加说明，但不要修改下面的补丁正文，比如例子中的 Limit log functionality to the first 20 部分。这样，其它开发者能阅读，但在采纳补丁时不会将此合并进来。

你可以用邮件客户端软件发送这些补丁文件，也可以直接在命令行发送。有些所谓智能的邮件客户端软件会自作主张帮你调整格式，所以粘贴补丁到邮件正文时，有可能会丢失换行符和若干空格。Git 提供了一个通过 IMAP 发送补丁文件的工具。接下来我会演示如何通过 Gmail 的 IMAP 服务器发送。另外，在 Git 源代码中有个 Documentation/SubmittingPatches 文件，可以仔细读读，看看其它邮件程序的相关导引。

首先在 ~/.gitconfig 文件中配置 imap 项。每个选项都可用 git config 命令分别设置，当然直接编辑文件添加以下内容更便捷：

[imap]    folder = "[Gmail]/Drafts"    host = imaps://imap.gmail.com    user = [e-mail]    pass = p4ssw0rd    port = 993    sslverify = false

如果你的 IMAP 服务器没有启用 SSL，就无需配置最后那两行，并且 host 应该以 imap:// 开头而不再是有 s 的 imaps://。保存配置文件后，就能用 git send-email 命令把补丁作为邮件依次发送到指定的 IMAP 服务器上的文件夹中（译注：这里就是 Gmail 的 [Gmail]/Drafts 文件夹。但如果你的语言设置不是英文，此处的文件夹 Drafts 字样会变为对应的语言。）：

$ git send-email *.patch    0001-added-limit-to-log-function.patch    0002-changed-log-output-to-30-from-25.patch    Who should the emails appear to be from? [Jessica Smith <[e-mail]>]    Emails will be sent from: Jessica Smith <[e-mail]>    Who should the emails be sent to? [e-mail]    Message-ID to be used as In-Reply-To for the first email? y

接下来，Git 会根据每个补丁依次输出类似下面的日志：

(mbox) Adding cc: Jessica Smith <[e-mail]> from    \line 'From: Jessica Smith <[e-mail]>'    OK. Log says:    Sendmail: /usr/sbin/sendmail -i [e-mail]    From: Jessica Smith <[e-mail]>    To: [e-mail]    Subject: [PATCH 1/2] added limit to log function    Date: Sat, 30 May 2009 13:29:15 -0700    Message-Id: <[e-mail]>    X-Mailer: git-send-email 1.6.2.rc1.20.g8c5b.dirty    In-Reply-To: <y>    References: <y>    Result: OK

最后，到 Gmail 上打开 Drafts 文件夹，编辑这些邮件，修改收件人地址为邮件列表地址，另外给要抄送的人也加到 Cc 列表中，最后发送。