第二版

2.3 Git 基礎 - 檢視提交歷史

檢視提交歷史

在你建立了若干次提交，或者克隆了一個含有提交歷史的倉庫之後，你可能希望回顧一下所發生的事情。要做到這一點，最基本且最強大的工具就是 git log 命令。

這些例子使用了一個名為 “simplegit” 的非常簡單的專案。要獲取該專案，請執行

$ git clone https://github.com/schacon/simplegit-progit

當你在這個專案中執行 git log 時，你應該會看到類似這樣的輸出

$ git log
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    Change version number

commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 16:40:33 2008 -0700

    Remove unnecessary test

commit a11bef06a3f659402fe7563abf99ad00de2209e6
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 10:31:28 2008 -0700

    Initial commit

預設情況下，不帶任何引數的 git log 命令會按逆時間順序（即最新提交在前）列出該倉庫中的提交。如你所見，此命令會列出每個提交的 SHA-1 校驗和、作者姓名和電子郵件、提交日期以及提交資訊。

git log 命令提供了大量各式各樣的選項，可以精確地顯示你想要查詢的資訊。在這裡，我們將向你展示一些最常用的選項。

其中一個更有用的選項是 -p 或 --patch，它會顯示每次提交引入的差異（補丁輸出）。你還可以限制顯示的日誌條目數量，例如使用 -2 只顯示最後兩個條目。

$ git log -p -2
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    Change version number

diff --git a/Rakefile b/Rakefile
index a874b73..8f94139 100644
--- a/Rakefile
+++ b/Rakefile
@@ -5,7 +5,7 @@ require 'rake/gempackagetask'
 spec = Gem::Specification.new do |s|
     s.platform  =   Gem::Platform::RUBY
     s.name      =   "simplegit"
-    s.version   =   "0.1.0"
+    s.version   =   "0.1.1"
     s.author    =   "Scott Chacon"
     s.email     =   "schacon@gee-mail.com"
     s.summary   =   "A simple gem for using Git in Ruby code."

commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 16:40:33 2008 -0700

    Remove unnecessary test

diff --git a/lib/simplegit.rb b/lib/simplegit.rb
index a0a60ae..47c6340 100644
--- a/lib/simplegit.rb
+++ b/lib/simplegit.rb
@@ -18,8 +18,3 @@ class SimpleGit
     end

 end
-
-if $0 == __FILE__
-  git = SimpleGit.new
-  puts git.show
-end

此選項顯示相同的資訊，但每個條目後都直接跟著一個差異。這對於程式碼審查或快速瀏覽協作者新增的一系列提交中發生的事情非常有用。你還可以將一系列摘要選項與 git log 一起使用。例如，如果你想檢視每個提交的縮略統計資訊，可以使用 --stat 選項

$ git log --stat
commit ca82a6dff817ec66f44342007202690a93763949
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Mon Mar 17 21:52:11 2008 -0700

    Change version number

 Rakefile | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

commit 085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 16:40:33 2008 -0700

    Remove unnecessary test

 lib/simplegit.rb | 5 -----
 1 file changed, 5 deletions(-)

commit a11bef06a3f659402fe7563abf99ad00de2209e6
Author: Scott Chacon <schacon@gee-mail.com>
Date:   Sat Mar 15 10:31:28 2008 -0700

    Initial commit

 README           |  6 ++++++
 Rakefile         | 23 +++++++++++++++++++++++
 lib/simplegit.rb | 25 +++++++++++++++++++++++++
 3 files changed, 54 insertions(+)

如你所見，--stat 選項會在每個提交條目下方列印一個修改檔案的列表，顯示有多少檔案被更改，以及這些檔案中新增和刪除了多少行。它還會將資訊的摘要放在末尾。

另一個非常有用的選項是 --pretty。此選項會將日誌輸出更改為預設格式以外的格式。有幾個預設的選項值可供你使用。此選項的 oneline 值會將每個提交列印在一行上，如果你要檢視大量提交，這會非常有用。此外，short、full 和 fuller 值會以大致相同的格式顯示輸出，但資訊量分別更少或更多。

$ git log --pretty=oneline
ca82a6dff817ec66f44342007202690a93763949 Change version number
085bb3bcb608e1e8451d4b2432f8ecbe6306e7e7 Remove unnecessary test
a11bef06a3f659402fe7563abf99ad00de2209e6 Initial commit

最有趣的選項值是 format，它允許你指定自己的日誌輸出格式。這在為機器解析生成輸出時特別有用——因為你明確指定了格式，所以你確切知道它不會隨 Git 的更新而改變。

$ git log --pretty=format:"%h - %an, %ar : %s"
ca82a6d - Scott Chacon, 6 years ago : Change version number
085bb3b - Scott Chacon, 6 years ago : Remove unnecessary test
a11bef0 - Scott Chacon, 6 years ago : Initial commit

git log --pretty=format 的有用格式佔位符列出了 format 接受的一些更有用的佔位符。

表 1. `git log --pretty=format` 的有用格式佔位符
佔位符	輸出描述
`%H`	提交雜湊值
`%h`	縮寫提交雜湊值
`%T`	樹雜湊值
`%t`	縮寫樹雜湊值
`%P`	父提交雜湊值
`%p`	縮寫父提交雜湊值
`%an`	作者姓名
`%ae`	作者電子郵件
`%ad`	作者日期（格式遵循 `--date=option` 選項）
`%ar`	作者日期，相對格式
`%cn`	提交者姓名
`%ce`	提交者電子郵件
`%cd`	提交者日期
`%cr`	提交者日期，相對格式
`%s`	主題

你可能想知道作者和 提交者 之間的區別。作者是最初編寫作品的人，而提交者是最後應用該作品的人。因此，如果你向一個專案提交一個補丁，然後一位核心成員應用了該補丁，你們兩人都會獲得貢獻——你作為作者，核心成員作為提交者。我們將在分散式 Git 中更詳細地介紹這種區別。

oneline 和 format 選項值與另一個名為 --graph 的 log 選項結合使用時特別有用。此選項會新增一個漂亮的小型 ASCII 圖形，顯示你的分支和合並歷史

$ git log --pretty=format:"%h %s" --graph
* 2d3acf9 Ignore errors from SIGCHLD on trap
*  5e3ee11 Merge branch 'master' of https://github.com/dustin/grit.git
|\
| * 420eac9 Add method for getting the current branch
* | 30e367c Timeout code and tests
* | 5a09431 Add timeout protection to grit
* | e1193f8 Support for heads with slashes in them
|/
* d6016bc Require time for xmlschema
*  11d191e Merge branch 'defunkt' into local

當我們進入下一章的分支和合並時，這類輸出會變得更加有趣。

這些只是 git log 的一些簡單的輸出格式化選項——還有很多其他的。git log 的常用選項列出了我們目前已介紹的選項，以及一些其他可能有用的常用格式化選項，以及它們如何改變 log 命令的輸出。

表 2. `git log` 的常用選項
選項	描述
`-p`	顯示每個提交引入的補丁。
`--stat`	顯示每個提交中修改檔案的統計資訊。
`--shortstat`	僅顯示 `--stat` 命令中的更改/插入/刪除行。
`--name-only`	在提交資訊後顯示修改檔案的列表。
`--name-status`	顯示受影響的檔案列表，同時包含新增/修改/刪除資訊。
`--abbrev-commit`	只顯示 SHA-1 校驗和的前幾個字元，而不是全部 40 個字元。
`--relative-date`	以相對格式（例如，“2 周前”）顯示日期，而不是使用完整的日期格式。
`--graph`	在日誌輸出旁邊顯示分支和合並歷史的 ASCII 圖形。
`--pretty`	以備選格式顯示提交。選項值包括 `oneline`、`short`、`full`、`fuller` 和 `format`（你可以指定自己的格式）。
`--oneline`	同時使用 `--pretty=oneline --abbrev-commit` 的簡寫形式。

限制日誌輸出

除了輸出格式化選項之外，git log 還接受許多有用的限制選項；也就是說，這些選項允許你只顯示提交的一個子集。你已經見過其中一個選項——-2 選項，它只顯示最後兩個提交。實際上，你可以使用 -<n>，其中 n 是任何整數，以顯示最後 n 個提交。但在實際使用中，你不太可能經常使用它，因為 Git 預設會將所有輸出透過分頁器顯示，因此你一次只能看到一頁日誌輸出。

然而，諸如 --since 和 --until 這樣的時間限制選項非常有用。例如，此命令會獲取過去兩週內進行的提交列表

$ git log --since=2.weeks

此命令支援多種格式——你可以指定一個具體的日期，如 "2008-01-15"，或一個相對日期，如 "2 years 1 day 3 minutes ago"。

你還可以根據某些搜尋條件過濾列表。--author 選項允許你按特定作者過濾，而 --grep 選項允許你在提交資訊中搜索關鍵字。

注意	你可以指定 `--author` 和 `--grep` 搜尋條件的多個例項，這將把提交輸出限制為匹配任何 `--author` 模式和任何 `--grep` 模式的提交；然而，新增 `--all-match` 選項會進一步將輸出限制為只匹配所有 `--grep` 模式的提交。

另一個非常有用的過濾器是 -S 選項（俗稱 Git 的“pickaxe”選項），它接受一個字串，並只顯示那些改變了該字串出現次數的提交。例如，如果你想找到最後一次新增或刪除特定函式引用的提交，你可以呼叫

$ git log -S function_name

傳遞給 git log 作為過濾器的最後一個真正有用的選項是路徑。如果你指定一個目錄或檔名，你可以將日誌輸出限制為對這些檔案引入更改的提交。這總是最後一個選項，通常前面會加上雙破折號 (--) 來將路徑與選項分開

$ git log -- path/to/file

在限制 git log 輸出的選項中，我們將列出這些以及其他一些常用選項供你參考。

表 3. 限制 `git log` 輸出的選項
選項	描述
`-<n>`	只顯示最後 n 個提交。
`--since`, `--after`	將提交限制為在指定日期之後進行的提交。
`--until`, `--before`	將提交限制為在指定日期之前進行的提交。
`--author`	只顯示作者條目匹配指定字串的提交。
`--committer`	只顯示提交者條目匹配指定字串的提交。
`--grep`	只顯示提交資訊中包含指定字串的提交。
`-S`	只顯示新增或刪除與字串匹配的程式碼的提交。

例如，如果你想檢視 Git 原始碼歷史中哪些修改了測試檔案的提交是由 Junio Hamano 在 2008 年 10 月提交且不是合併提交的，你可以執行類似這樣的命令

$ git log --pretty="%h - %s" --author='Junio C Hamano' --since="2008-10-01" \
   --before="2008-11-01" --no-merges -- t/
5610e3b - Fix testcase failure when extended attributes are in use
acd3b9e - Enhance hold_lock_file_for_{update,append}() API
f563754 - demonstrate breakage of detached checkout with symbolic link HEAD
d1a43f2 - reset --hard/read-tree --reset -u: remove unmerged new paths
51a94af - Fix "checkout --track -b newbranch" on detached HEAD
b0ad11e - pull: allow "git pull origin $something:$current_branch" into an unborn branch

在 Git 原始碼歷史的近 40,000 次提交中，此命令顯示了符合這些條件的 6 次提交。

提示	阻止顯示合併提交根據你倉庫中使用的工作流，你的日誌歷史中可能很大一部分提交只是合併提交，這些提交通常資訊量不大。為了防止合併提交使你的日誌歷史變得雜亂，只需新增 `log` 選項 `--no-merges` 即可。

1. 起步

2. Git 基礎

3. Git 分支

4. 伺服器上的 Git

5. 分散式 Git

6. GitHub

7. Git 工具

8. 定製 Git

9. Git 與其他系統

10. Git 內部原理

A1. 附錄 A: Git 在其他環境

A2. 附錄 B: 在應用程式中嵌入 Git

A3. 附錄 C: Git 命令

2.3 Git 基礎 - 檢視提交歷史

檢視提交歷史

限制日誌輸出