Git 項目的管理

既然是相互協(xié)作，在貢獻代碼的同時，也免不了要維護管理自己的項目。像是怎么處理別人用 format-patch 生成的補丁，或是集成遠(yuǎn)端倉庫上某個分支上的變化等等。但無論是管理代碼倉庫，還是幫忙審核收到的補丁，都需要同貢獻者約定某種長期可持續(xù)的工作方式。

使用特性分支進行工作

如果想要集成新的代碼進來，最好局限在特性分支上做。臨時的特性分支可以讓你隨意嘗試，進退自如。比如碰上無法正常工作的補丁，可以先擱在那邊，直到有時間仔細(xì)核查修復(fù)為止。創(chuàng)建的分支可以用相關(guān)的主題關(guān)鍵字命名，比如 ruby_client 或者其它類似的描述性詞語，以幫助將來回憶。Git 項目本身還時常把分支名稱分置于不同命名空間下，比如 sc/ruby_client 就說明這是 sc 這個人貢獻的。 現(xiàn)在從當(dāng)前主干分支為基礎(chǔ)，新建臨時分支：

$ git branch sc/ruby_client master

另外，如果你希望立即轉(zhuǎn)到分支上去工作，可以用 checkout -b：

$ git checkout -b sc/ruby_client master

好了，現(xiàn)在已經(jīng)準(zhǔn)備妥當(dāng)，可以試著將別人貢獻的代碼合并進來了。之后評估一下有沒有問題，最后再決定是不是真的要并入主干。

采納來自郵件的補丁
如果收到一個通過電郵發(fā)來的補丁，你應(yīng)該先把它應(yīng)用到特性分支上進行評估。有兩種應(yīng)用補丁的方法：git apply 或者 git am。

使用 apply 命令應(yīng)用補丁
如果收到的補丁文件是用 git diff 或由其它 Unix 的 diff 命令生成，就該用 git apply 命令來應(yīng)用補丁。假設(shè)補丁文件存在 /tmp/patch-ruby-client.patch，可以這樣運行：

$ git apply /tmp/patch-ruby-client.patch

這會修改當(dāng)前工作目錄下的文件，效果基本與運行 patch -p1 打補丁一樣，但它更為嚴(yán)格，且不會出現(xiàn)混亂。如果是 git diff 格式描述的補丁，此命令還會相應(yīng)地添加，刪除，重命名文件。當(dāng)然，普通的 patch 命令是不會這么做的。另外請注意，git apply 是一個事務(wù)性操作的命令，也就是說，要么所有補丁都打上去，要么全部放棄。所以不會出現(xiàn) patch 命令那樣，一部分文件打上了補丁而另一部分卻沒有，這樣一種不上不下的修訂狀態(tài)。所以總的來說，git apply 要比 patch 嚴(yán)謹(jǐn)許多。因為僅僅是更新當(dāng)前的文件，所以此命令不會自動生成提交對象，你得手工緩存相應(yīng)文件的更新狀態(tài)并執(zhí)行提交命令。

在實際打補丁之前，可以先用 git apply --check 查看補丁是否能夠干凈順利地應(yīng)用到當(dāng)前分支中：

$ git apply --check 0001-seeing-if-this-helps-the-gem.patch
error: patch failed: ticgit.gemspec:1
error: ticgit.gemspec: patch does not apply

如果沒有任何輸出，表示我們可以順利采納該補丁。如果有問題，除了報告錯誤信息之外，該命令還會返回一個非零的狀態(tài)，所以在 shell 腳本里可用于檢測狀態(tài)。

使用 am 命令應(yīng)用補丁

如果貢獻者也用 Git，且擅于制作 format-patch 補丁，那你的合并工作將會非常輕松。因為這些補丁中除了文件內(nèi)容差異外，還包含了作者信息和提交消息。所以請鼓勵貢獻者用 format-patch 生成補丁。對于傳統(tǒng)的 diff 命令生成的補丁，則只能用 git apply 處理。

對于 format-patch 制作的新式補丁，應(yīng)當(dāng)使用 git am 命令。從技術(shù)上來說，git am 能夠讀取 mbox 格式的文件。這是種簡單的純文本文件，可以包含多封電郵，格式上用 From 加空格以及隨便什么輔助信息所組成的行作為分隔行，以區(qū)分每封郵件，就像這樣：

From 330090432754092d704da8e76ca5c05c198e71a8 Mon Sep 17 00:00:00 2001
From: Jessica Smith <jessica@example.com>
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

這是 format-patch 命令輸出的開頭幾行，也是一個有效的 mbox 文件格式。如果有人用 git send-email 給你發(fā)了一個補丁，你可以將此郵件下載到本地，然后運行 git am 命令來應(yīng)用這個補丁。如果你的郵件客戶端能將多封電郵導(dǎo)出為 mbox 格式的文件，就可以用 git am 一次性應(yīng)用所有導(dǎo)出的補丁。

如果貢獻者將 format-patch 生成的補丁文件上傳到類似 Request Ticket 一樣的任務(wù)處理系統(tǒng)，那么可以先下載到本地，繼而使用 git am 應(yīng)用該補丁：

$ git am 0001-limit-log-function.patch
Applying: add limit to log function

你會看到它被干凈地應(yīng)用到本地分支，并自動創(chuàng)建了新的提交對象。作者信息取自郵件頭 From 和 Date，提交消息則取自 Subject 以及正文中補丁之前的內(nèi)容。來看具體實例，采納之前展示的那個 mbox 電郵補丁后，最新的提交對象為：

$ git log --pretty=fuller -1
commit 6c5e70b984a60b3cecd395edd5b48a7575bf58e0
Author:     Jessica Smith <jessica@example.com>
AuthorDate: Sun Apr 6 10:17:23 2008 -0700
Commit:     Scott Chacon <schacon@gmail.com>
CommitDate: Thu Apr 9 09:19:06 2009 -0700

   add limit to log function

   Limit log functionality to the first 20

Commit 部分顯示的是采納補丁的人，以及采納的時間。而 Author 部分則顯示的是原作者，以及創(chuàng)建補丁的時間。

有時，我們也會遇到打不上補丁的情況。這多半是因為主干分支和補丁的基礎(chǔ)分支相差太遠(yuǎn)，但也可能是因為某些依賴補丁還未應(yīng)用。這種情況下，git am 會報錯并詢問該怎么做：

$ git am 0001-seeing-if-this-helps-the-gem.patch
Applying: seeing if this helps the gem
error: patch failed: ticgit.gemspec:1
error: ticgit.gemspec: patch does not apply
Patch failed at 0001.
When you have resolved this problem run "git am --resolved".
If you would prefer to skip this patch, instead run "git am --skip".
To restore the original branch and stop patching run "git am --abort".

Git 會在有沖突的文件里加入沖突解決標(biāo)記，這同合并或衍合操作一樣。解決的辦法也一樣，先編輯文件消除沖突，然后暫存文件，最后運行 git am --resolved 提交修正結(jié)果：

$ (fix the file)
$ git add ticgit.gemspec
$ git am --resolved
Applying: seeing if this helps the gem

如果想讓 Git 更智能地處理沖突，可以用 -3 選項進行三方合并。如果當(dāng)前分支未包含該補丁的基礎(chǔ)代碼或其祖先，那么三方合并就會失敗，所以該選項默認(rèn)為關(guān)閉狀態(tài)。一般來說，如果該補丁是基于某個公開的提交制作而成的話，你總是可以通過同步來獲取這個共同祖先，所以用三方合并選項可以解決很多麻煩：

$ git am -3 0001-seeing-if-this-helps-the-gem.patch
Applying: seeing if this helps the gem
error: patch failed: ticgit.gemspec:1
error: ticgit.gemspec: patch does not apply
Using index info to reconstruct a base tree...
Falling back to patching base and 3-way merge...
No changes -- Patch already applied.

像上面的例子，對于打過的補丁我又再打一遍，自然會產(chǎn)生沖突，但因為加上了 -3 選項，所以它很聰明地告訴我，無需更新，原有的補丁已經(jīng)應(yīng)用。

對于一次應(yīng)用多個補丁時所用的 mbox 格式文件，可以用 am 命令的交互模式選項 -i，這樣就會在打每個補丁前停住，詢問該如何操作：

$ git am -3 -i mbox
Commit Body is:
--------------------------
seeing if this helps the gem
--------------------------
Apply? [y]es/[n]o/[e]dit/[v]iew patch/[a]ccept all

在多個補丁要打的情況下，這是個非常好的辦法，一方面可以預(yù)覽下補丁內(nèi)容，同時也可以有選擇性的接納或跳過某些補丁。

打完所有補丁后，如果測試下來新特性可以正常工作，那就可以安心地將當(dāng)前特性分支合并到長期分支中去了。

檢出遠(yuǎn)程分支

如果貢獻者有自己的 Git 倉庫，并將修改推送到此倉庫中，那么當(dāng)你拿到倉庫的訪問地址和對應(yīng)分支的名稱后，就可以加為遠(yuǎn)程分支，然后在本地進行合并。

比如，Jessica 發(fā)來一封郵件，說在她代碼庫中的 ruby-client 分支上已經(jīng)實現(xiàn)了某個非常棒的新功能，希望我們能幫忙測試一下。我們可以先把她的倉庫加為遠(yuǎn)程倉庫，然后抓取數(shù)據(jù)，完了再將她所說的分支檢出到本地來測試：

$ git remote add jessica git://github.com/jessica/myproject.git
$ git fetch jessica
$ git checkout -b rubyclient jessica/ruby-client

若是不久她又發(fā)來郵件，說還有個很棒的功能實現(xiàn)在另一分支上，那我們只需重新抓取下最新數(shù)據(jù)，然后檢出那個分支到本地就可以了，無需重復(fù)設(shè)置遠(yuǎn)程倉庫。

這種做法便于同別人保持長期的合作關(guān)系。但前提是要求貢獻者有自己的服務(wù)器，而我們也需要為每個人建一個遠(yuǎn)程分支。有些貢獻者提交代碼補丁并不是很頻繁，所以通過郵件接收補丁效率會更高。同時我們自己也不會希望建上百來個分支，卻只從每個分支取一兩個補丁。但若是用腳本程序來管理，或直接使用代碼倉庫托管服務(wù)，就可以簡化此過程。當(dāng)然，選擇何種方式取決于你和貢獻者的喜好。

使用遠(yuǎn)程分支的另外一個好處是能夠得到提交歷史。不管代碼合并是不是會有問題，至少我們知道該分支的歷史分叉點，所以默認(rèn)會從共同祖先開始自動進行三方合并，無需 -3 選項，也不用像打補丁那樣祈禱存在共同的基準(zhǔn)點。

如果只是臨時合作，只需用 git pull 命令抓取遠(yuǎn)程倉庫上的數(shù)據(jù)，合并到本地臨時分支就可以了。一次性的抓取動作自然不會把該倉庫地址加為遠(yuǎn)程倉庫。

$ git pull git://github.com/onetimeguy/project.git
From git://github.com/onetimeguy/project
 * branch            HEAD       -> FETCH_HEAD
Merge made by recursive.

決斷代碼取舍

現(xiàn)在特性分支上已合并好了貢獻者的代碼，是時候決斷取舍了。本節(jié)將回顧一些之前學(xué)過的命令，以看清將要合并到主干的是哪些代碼，從而理解它們到底做了些什么，是否真的要并入。

一般我們會先看下，特性分支上都有哪些新增的提交。比如在 contrib 特性分支上打了兩個補丁，僅查看這兩個補丁的提交信息，可以用 --not 選項指定要屏蔽的分支 master，這樣就會剔除重復(fù)的提交歷史：

$ git log contrib --not master
commit 5b6235bd297351589efc4d73316f0a68d484f118
Author: Scott Chacon <schacon@gmail.com>
Date:   Fri Oct 24 09:53:59 2008 -0700

    seeing if this helps the gem

commit 7482e0d16d04bea79d0dba8988cc78df655f16a0
Author: Scott Chacon <schacon@gmail.com>
Date:   Mon Oct 22 19:38:36 2008 -0700

    updated the gemspec to hopefully work better

還可以查看每次提交的具體修改。請牢記，在 git log 后加 -p 選項將展示每次提交的內(nèi)容差異。

如果想看當(dāng)前分支同其他分支合并時的完整內(nèi)容差異，有個小竅門：

$ git diff master
雖然能得到差異內(nèi)容，但請記住，結(jié)果有可能和我們的預(yù)期不同。一旦主干 master 在特性分支創(chuàng)建之后有所修改，那么通過 diff 命令來比較的，是最新主干上的提交快照。顯然，這不是我們所要的。比方在 master 分支中某個文件里添了一行，然后運行上面的命令，簡單的比較最新快照所得到的結(jié)論只能是，特性分支中刪除了這一行。

這個很好理解：如果 master 是特性分支的直接祖先，不會產(chǎn)生任何問題；如果它們的提交歷史在不同的分叉上，那么產(chǎn)生的內(nèi)容差異，看起來就像是增加了特性分支上的新代碼，同時刪除了 master 分支上的新代碼。

實際上我們真正想要看的，是新加入到特性分支的代碼，也就是合并時會并入主干的代碼。所以，準(zhǔn)確地講，我們應(yīng)該比較特性分支和它同 master 分支的共同祖先之間的差異。

我們可以手工定位它們的共同祖先，然后與之比較：

$ git merge-base contrib master
36c7dba2c95e6bbb78dfa822519ecfec6e1ca649
$ git diff 36c7db

但這么做很麻煩，所以 Git 提供了便捷的 ... 語法。對于 diff 命令，可以把 ... 加在原始分支（擁有共同祖先）和當(dāng)前分支之間：

$ git diff master...contrib
現(xiàn)在看到的，就是實際將要引入的新代碼。這是一個非常有用的命令，應(yīng)該牢記。

代碼集成

一旦特性分支準(zhǔn)備停當(dāng)，接下來的問題就是如何集成到更靠近主線的分支中。此外還要考慮維護項目的總體步驟是什么。雖然有很多選擇，不過我們這里只介紹其中一部分。

合并流程

一般最簡單的情形，是在 master 分支中維護穩(wěn)定代碼，然后在特性分支上開發(fā)新功能，或是審核測試別人貢獻的代碼，接著將它并入主干，最后刪除這個特性分支，如此反復(fù)。來看示例，假設(shè)當(dāng)前代碼庫中有兩個分支，分別為 ruby_client 和 php_client，如圖 5-19 所示。然后先把 ruby_client 合并進主干，再合并 php_client，最后的提交歷史如圖 5-20 所示。

圖 5-23. 特性分支發(fā)布后

這樣，在人們克隆倉庫時就有兩種選擇：既可檢出最新穩(wěn)定版本，確保正常使用；也能檢出開發(fā)版本，試用最前沿的新特性。 你也可以擴展這個概念，先將所有新代碼合并到臨時特性分支，等到該分支穩(wěn)定下來并通過測試后，再并入 develop 分支。然后，讓時間檢驗一切，如果這些代碼確實可以正常工作相當(dāng)長一段時間，那就有理由相信它已經(jīng)足夠穩(wěn)定，可以放心并入主干分支發(fā)布。

大項目的合并流程

Git 項目本身有四個長期分支：用于發(fā)布的 master 分支、用于合并基本穩(wěn)定特性的 next 分支、用于合并仍需改進特性的 pu 分支（pu 是 proposed updates 的縮寫），以及用于除錯維護的 maint 分支（maint 取自 maintenance）。維護者可以按照之前介紹的方法，將貢獻者的代碼引入為不同的特性分支（如圖 5-24 所示），然后測試評估，看哪些特性能穩(wěn)定工作，哪些還需改進。穩(wěn)定的特性可以并入 next 分支，然后再推送到公共倉庫，以供其他人試用。

<img src=""/attachments/image/cimg/p" attachments="" image="" cimg="" p="" alt="">

圖 5-25. 將特性并入長期分支

并入 master 后的特性分支，已經(jīng)無需保留分支索引，放心刪除好了。Git 項目還有一個 maint 分支，它是以最近一次發(fā)行版為基礎(chǔ)分化而來的，用于維護除錯補丁。所以克隆 Git 項目倉庫后會得到這四個分支，通過檢出不同分支可以了解各自進展，或是試用前沿特性，或是貢獻代碼。而維護者則通過管理這些分支，逐步有序地并入第三方貢獻。

衍合與挑揀（cherry-pick）的流程

一些維護者更喜歡衍合或者挑揀貢獻者的代碼，而不是簡單的合并，因為這樣能夠保持線性的提交歷史。如果你完成了一個特性的開發(fā)，并決定將它引入到主干代碼中，你可以轉(zhuǎn)到那個特性分支然后執(zhí)行衍合命令，好在你的主干分支上（也可能是develop分支之類的）重新提交這些修改。如果這些代碼工作得很好，你就可以快進master分支，得到一個線性的提交歷史。

另一個引入代碼的方法是挑揀。挑揀類似于針對某次特定提交的衍合。它首先提取某次提交的補丁，然后試著應(yīng)用在當(dāng)前分支上。如果某個特性分支上有多個commits，但你只想引入其中之一就可以使用這種方法。也可能僅僅是因為你喜歡用挑揀，討厭衍合。假設(shè)你有一個類似圖 5-26 的工程。

<img src="/attachments/image/cimg/pp圖 5-26. 挑揀（cherry-pick）之前的歷史/pp如果你希望拉取e43a6到你的主干分支，可以這樣：/pprecode$ git cherry-pick e43a6fd3e94888d76779ad79fb568ed180e5fcdfFinished one cherry-pick.[master]: created a0a41a9: " more="" friendly="" message="" when="" locking="" the="" index="" fails."="" 3="" files="" changed,="" 17="" insertions(+),="" deletions(-)="" code="" pre="" p這將會引入e43a6的代碼，但是會得到不同的sha-1值，因為應(yīng)用日期不同?，F(xiàn)在你的歷史看起來像圖="" 5-27.="" p="" pimg="" scott="" chacon="" <schacon@gmail.com>"="" 1024-bit="" dsa="" key,="" id="" f721c45a,="" created="" 2009-02-09<="">

完成簽名之后，如何分發(fā)PGP公鑰（public key）是個問題。（譯者注：分發(fā)公鑰是為了驗證標(biāo)簽）。還好，Git的設(shè)計者想到了解決辦法：可以把key（即公鑰）作為blob變量寫入Git庫，然后把它的內(nèi)容直接寫在標(biāo)簽里。gpg --list-keys命令可以顯示出你所擁有的key：

$ gpg --list-keys
/Users/schacon/.gnupg/pubring.gpg
---------------------------------
pub   1024D/F721C45A 2009-02-09 [expires: 2010-02-09]
uid                  Scott Chacon <schacon@gmail.com>
sub   2048g/45D02282 2009-02-09 [expires: 2010-02-09]

然后，導(dǎo)出key的內(nèi)容并經(jīng)由管道符傳遞給git hash-object，之后鑰匙會以blob類型寫入Git中，最后返回這個blob量的SHA-1值：

$ gpg -a --export F721C45A | git hash-object -w --stdin
659ef797d181633c87ec71ac3f9ba29fe5775b92

現(xiàn)在你的Git已經(jīng)包含了這個key的內(nèi)容了，可以通過不同的SHA-1值指定不同的key來創(chuàng)建標(biāo)簽。

$ git tag -a maintainer-pgp-pub 659ef797d181633c87ec71ac3f9ba29fe5775b92
在運行g(shù)it push --tags命令之后，maintainer-pgp-pub標(biāo)簽就會公布給所有人。如果有人想要校驗標(biāo)簽，他可以使用如下命令導(dǎo)入你的key：

$ git show maintainer-pgp-pub | gpg --import
人們可以用這個key校驗?zāi)愫灻乃袠?biāo)簽。另外，你也可以在標(biāo)簽信息里寫入一個操作向?qū)?，用戶只需要運行g(shù)it show 查看標(biāo)簽信息，然后按照你的向?qū)Ь湍芡瓿尚ｒ灐?/p>

生成內(nèi)部版本號

因為Git不會為每次提交自動附加類似'v123'的遞增序列，所以如果你想要得到一個便于理解的提交號可以運行g(shù)it describe命令。Git將會返回一個字符串，由三部分組成：最近一次標(biāo)定的版本號，加上自那次標(biāo)定之后的提交次數(shù)，再加上一段所描述的提交的SHA-1值：

$ git describe master
v1.6.2-rc1-20-g8c5b85c

這個字符串可以作為快照的名字，方便人們理解。如果你的Git是你自己下載源碼然后編譯安裝的，你會發(fā)現(xiàn)git --version命令的輸出和這個字符串差不多。如果在一個剛剛打完標(biāo)簽的提交上運行describe命令，只會得到這次標(biāo)定的版本號，而沒有后面兩項信息。

git describe命令只適用于有標(biāo)注的標(biāo)簽（通過-a或者-s選項創(chuàng)建的標(biāo)簽），所以發(fā)行版的標(biāo)簽都應(yīng)該是帶有標(biāo)注的，以保證git describe能夠正確的執(zhí)行。你也可以把這個字符串作為checkout或者show命令的目標(biāo)，因為他們最終都依賴于一個簡短的SHA-1值，當(dāng)然如果這個SHA-1值失效他們也跟著失效。最近Linux內(nèi)核為了保證SHA-1值的唯一性，將位數(shù)由8位擴展到10位，這就導(dǎo)致擴展之前的git describe輸出完全失效了。

準(zhǔn)備發(fā)布

現(xiàn)在可以發(fā)布一個新的版本了。首先要將代碼的壓縮包歸檔，方便那些可憐的還沒有使用Git的人們。可以使用git archive：

$ git archive master --prefix='project/' | gzip > `git describe master`.tar.gz
$ ls *.tar.gz
v1.6.2-rc1-20-g8c5b85c.tar.gz

這個壓縮包解壓出來的是一個文件夾，里面是你項目的最新代碼快照。你也可以用類似的方法建立一個zip壓縮包，在git archive加上--format=zip選項：

$ git archive master --prefix='project/' --format=zip >git describe master.zip
現(xiàn)在你有了一個tar.gz壓縮包和一個zip壓縮包，可以把他們上傳到你網(wǎng)站上或者用e-mail發(fā)給別人。

制作簡報

是時候通知郵件列表里的朋友們來檢驗?zāi)愕某晒恕Ｊ褂胓it shortlog命令可以方便快捷的制作一份修改日志（changelog），告訴大家上次發(fā)布之后又增加了哪些特性和修復(fù)了哪些bug。實際上這個命令能夠統(tǒng)計給定范圍內(nèi)的所有提交;假如你上一次發(fā)布的版本是v1.0.1，下面的命令將給出自從上次發(fā)布之后的所有提交的簡介：

$ git shortlog --no-merges master --not v1.0.1
Chris Wanstrath (8):
      Add support for annotated tags to Grit::Tag
      Add packed-refs annotated tag support.
      Add Grit::Commit#to_patch
      Update version and History.txt
      Remove stray `puts`
      Make ls_tree ignore nils

Tom Preston-Werner (4):
      fix dates in history
      dynamic version method
      Version bump to 1.0.2
      Regenerated gemspec for version 1.0.2

這就是自從v1.0.1版本以來的所有提交的簡介，內(nèi)容按照作者分組，以便你能快速的發(fā)e-mail給他們。