第二版

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

该选项显示相同的信息，但在每个条目之后直接附带差异（diff）信息。这对于代码审查或快速浏览协作者所提交的一系列变更非常有用。您还可以配合 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。该选项可以改变日志输出的默认格式。Git 提供了一些内置的选项值。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=选项`）
`%ar`	作者日期，相对显示
`%cn`	提交者姓名
`%ce`	提交者电子邮件
`%cd`	提交者日期
`%cr`	提交者日期，相对显示
`%s`	说明

您可能会好奇作者（author）和提交者（committer）之间的区别。作者是实际编写代码的人，而提交者是最后将代码应用到项目中的人。因此，如果您向项目提交补丁，并且其中一名核心成员应用了该补丁，那么你们俩都会得到认可——您作为作者，核心成员作为提交者。我们将在分布式 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`	仅显示添加或删除了匹配字符串代码的提交。

例如，如果您想查看 2008 年 10 月由 Junio Hamano 提交的修改过 Git 源代码中测试文件的提交，且不包含合并提交，您可以运行类似以下的命令

$ 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 基础 - 查看提交历史

查看提交历史

限制日志输出