简体中文 ▾ 主题 ▾ 最新版本 ▾ git-blame 最后更新于 2.50.0

名称

git-blame - 显示文件每行最后修改的版本和作者

概要

git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
	    [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
	    [--ignore-rev <rev>] [--ignore-revs-file <file>]
	    [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]
	    [ --contents <file> ] [<rev> | --reverse <rev>..<rev>] [--] <file>

描述

用最后修改某行的版本的相关信息注释给定文件中的每一行。可选地，可以从给定版本开始注释。

当指定一次或多次时，-L 将注释限制在请求的行。

行源会自动追踪整个文件的重命名（目前没有关闭重命名追踪的选项）。要追踪从一个文件移动到另一个文件，或从另一个文件复制粘贴的行等，请参阅 -C 和 -M 选项。

报告不会告诉你任何关于已删除或替换的行的信息；你需要使用诸如 git diff 或下段中简要提到的 "pickaxe" 接口之类的工具。

除了支持文件注释，Git 还支持搜索开发历史中代码片段何时出现在更改中。这使得追踪代码片段何时被添加到文件、在文件之间移动或复制，以及最终被删除或替换成为可能。它通过在 diff 中搜索文本字符串来实现。一个搜索 blame_usage 的 pickaxe 接口的小例子

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

选项

-b

为边界提交显示空白 SHA-1。这也可以通过 blame.blankBoundary 配置选项控制。

--root

不将根提交视为边界。这也可以通过 blame.showRoot 配置选项控制。

--show-stats

在 blame 输出末尾包含附加统计信息。

-L <start>,<end>
-L :<funcname>

仅注释由 <start>,<end> 或函数名正则表达式 <funcname> 给定的行范围。可以指定多次。允许范围重叠。

<start> 和 <end> 是可选的。-L <start> 或 -L <start>, 范围从 <start> 到文件末尾。-L ,<end> 范围从文件开头到 <end>。

<start> 和 <end> 可以采用以下形式之一

  • 数字

    如果 <start> 或 <end> 是一个数字，它指定一个绝对行号（行从 1 开始计数）。

  • /正则表达式/

    此形式将使用匹配给定 POSIX 正则表达式的第一行。如果 <start> 是一个正则表达式，它将从前一个 -L 范围的末尾（如果有的话）开始搜索，否则从文件开头开始搜索。如果 <start> 是 ^/regex/，它将从文件开头开始搜索。如果 <end> 是一个正则表达式，它将从 <start> 给定的行开始搜索。

  • +偏移量 或 -偏移量

    这仅对 <end> 有效，并将指定 <start> 给定行之前或之后的行数。

如果 :<funcname> 代替 <start> 和 <end> 给出，它是一个正则表达式，表示从匹配 <funcname> 的第一个函数名行到下一个函数名行的范围。:<funcname> 从前一个 -L 范围的末尾（如果有的话）开始搜索，否则从文件开头开始搜索。^:<funcname> 从文件开头开始搜索。函数名的确定方式与 git diff 处理补丁 hunk 头的方式相同（参见 gitattributes[5] 中 Defining a custom hunk-header）。

-l

显示完整版本号（默认：关闭）。

-t

显示原始时间戳（默认：关闭）。

-S <revs-file>

使用 revs-file 中的修订版本，而不是调用 git-rev-list[1]。

--reverse <rev>..<rev>

向前遍历历史而不是向后。它不是显示行出现时的版本，而是显示行存在的最后版本。这需要一个像 START..END 这样的版本范围，其中要 blame 的路径存在于 START 中。为方便起见，git blame --reverse START 被视为 git blame --reverse START..HEAD。

--first-parent

遇到合并提交时，仅追踪第一个父提交。此选项可用于确定某行何时引入特定集成分支，而不是何时引入整个历史。

-p
--porcelain

以机器可读的格式显示。

--line-porcelain

显示 porcelain 格式，但为每行输出提交信息，而不仅仅是首次引用提交时。隐含 --porcelain。

--incremental

以机器可读的格式逐步显示结果。

--encoding=<encoding>

指定用于输出作者姓名和提交摘要的编码。将其设置为 none 会使 blame 输出未转换的数据。有关更多信息，请参阅 git-log[1] 手册页中关于编码的讨论。

--contents <file>

使用指定文件的内容进行注释，如果指定了 <rev> 则从该版本开始，否则从 HEAD 开始。您可以指定 - 使命令从标准输入读取文件内容。

--date <format>

指定用于输出日期的格式。如果未提供 --date，则使用 blame.date 配置变量的值。如果 blame.date 配置变量也未设置，则使用 iso 格式。有关支持的值，请参阅 git-log[1] 中 --date 选项的讨论。

--[no-]progress

当连接到终端时，默认情况下会在标准错误流上报告进度状态。此标志即使未连接到终端也会启用进度报告。不能将 --progress 与 --porcelain 或 --incremental 一起使用。

-M[<num>]

检测文件内移动或复制的行。当一个提交移动或复制一个行块（例如，原始文件有 A 然后 B，提交将其更改为 B 然后 A），传统的 blame 算法仅注意到移动的一半，通常将上移的行（即 B）归咎于父提交，并将下移的行（即 A）归咎于子提交。使用此选项，通过运行额外的检查遍数，两组行都归咎于父提交。

<num> 是可选的，但它是 Git 必须检测为在文件内移动/复制的字母数字字符数的下限，以便将其行与父提交关联。默认值为 20。

-C[<num>]

除了 -M 之外，还检测在同一提交中从其他文件移动或复制的行。这在您重组程序并在文件之间移动代码时很有用。当此选项给出两次时，命令还会查找从创建文件的提交中的其他文件的复制。当此选项给出三次时，命令还会查找任何提交中从其他文件的复制。

<num> 是可选的，但它是 Git 必须检测为在文件之间移动/复制的字母数字字符数的下限，以便将其行与父提交关联。默认值为 40。如果给出了多个 -C 选项，则最后一个 -C 的 <num> 参数将生效。

--ignore-rev <rev>

在分配 blame 时忽略由该版本所做的更改，就像这些更改从未发生过一样。由被忽略的提交更改或添加的行将被归咎于更改该行或附近行的上一个提交。此选项可以指定多次以忽略多个版本。如果设置了 blame.markIgnoredLines 配置选项，则由被忽略的提交更改并归因于另一个提交的行将在 blame 输出中标记为 ?。如果设置了 blame.markUnblamableLines 配置选项，则那些被忽略的提交触及但我们无法归因于其他版本的行将标记为 *。在 porcelain 模式下，我们分别在新行上打印 ignored 和 unblamable。

--ignore-revs-file <file>

忽略 file 中列出的修订版本，其格式必须与 fsck.skipList 相同。此选项可以重复，这些文件将在 blame.ignoreRevsFile 配置选项指定的任何文件之后处理。空文件名 "" 将清除先前处理文件中的修订版本列表。

--color-lines

如果默认格式中的行注释与前一行来自同一提交，则对其进行不同着色。这使得区分由不同提交引入的代码块变得更容易。默认颜色为青色，可以使用 color.blame.repeatedLines 配置选项进行调整。

--color-by-age

根据默认格式中行的“年龄”对行注释进行着色。color.blame.highlightRecent 配置选项控制用于每个年龄范围的颜色。

-h

显示帮助消息。

-c

使用与 git-annotate[1] 相同的输出模式（默认：关闭）。

--score-debug

包含与文件之间（参见 -C）和文件内（参见 -M）行移动相关的调试信息。列出的第一个数字是得分。这是检测到在文件之间或文件内部移动的字母数字字符数。此数字必须高于某个阈值，git blame 才会认为这些代码行已移动。

-f
--show-name

显示原始提交中的文件名。默认情况下，如果由于重命名检测而导致任何行来自不同名称的文件，则显示文件名。

-n
--show-number

显示原始提交中的行号（默认：关闭）。

-s

从输出中抑制作者姓名和时间戳。

-e
--show-email

显示作者电子邮件而不是作者姓名（默认：关闭）。这也可以通过 blame.showEmail 配置选项控制。

-w

比较父版本和子版本以查找行来源时忽略空格。

--abbrev=<n>

不使用默认的 7+1 十六进制数字作为缩写对象名称，而是使用 <m>+1 数字，其中 <m> 至少为 <n> 但确保提交对象名称是唯一的。请注意，1 列用于插入符号以标记边界提交。

默认格式

当未指定 --porcelain 也未指定 --incremental 选项时，git blame 将为每行输出注释，其中包含

  • 该行来自的提交的缩写对象名称；

  • 作者身份（默认是作者姓名和日期，除非指定了 -s 或 -e）；以及

  • 行号

在行内容之前。

Porcelain 格式

在此格式中，每行都在一个头部之后输出；头部至少有第一行，其中包含

  • 该行归因的提交的 40 字节 SHA-1；

  • 该行在原始文件中的行号；

  • 该行在最终文件中的行号；

  • 在与前一行来自不同提交的行组的起始行上，此组中的行数。在后续行上此字段缺失。

此头部行后面至少为每个提交显示以下信息一次

  • 作者姓名（"author"）、电子邮件（"author-mail"）、时间（"author-time"）和时区（"author-tz"）；提交者也类似。

  • 该行归因的提交中的文件名。

  • 提交日志消息的第一行（"summary"）。

实际行内容在上述头部之后输出，并以 TAB 为前缀。这是为了允许以后添加更多头部元素。

porcelain 格式通常会抑制已经看到的提交信息。例如，归咎于同一提交的两行都会显示，但该提交的详细信息只会显示一次。特定于单个行的信息不会被分组在一起，例如要标记为 ignored 或 unblamable 的版本。这更高效，但可能要求读者保留更多状态。--line-porcelain 选项可用于为每行输出完整的提交信息，允许更简单（但效率较低）的用法，例如

# count the number of lines attributed to each author
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

指定范围

与旧版本 Git 中的 git blame 和 git annotate 不同，注释的范围可以限制到行范围和版本范围。-L 选项（将注释限制到行范围）可以指定多次。

当您有兴趣查找文件 foo 的 40-60 行的来源时，您可以使用 -L 选项，如下所示（它们表示相同的意思——都要求从第 40 行开始的 21 行）

git blame -L 40,60 foo
git blame -L 40,+21 foo

您还可以使用正则表达式来指定行范围

git blame -L '/^sub hello {/,/^}$/' foo

这将注释限制在 hello 子例程的主体部分。

当您对早于 v2.6.18 的更改或早于 3 周的更改不感兴趣时，您可以使用类似于 git rev-list 的修订范围指定符

git blame v2.6.18.. -- foo
git blame --since=3.weeks -- foo

当使用版本范围指定符来限制注释时，自范围边界（在上述示例中是提交 v2.6.18 或超过 3 周的最新的提交）以来未更改的行将归咎于该范围边界提交。

一种特别有用的方法是查看添加的文件中是否有通过复制粘贴现有文件创建的行。有时这表明开发人员草率，没有正确重构代码。您可以首先找到引入该文件的提交

git log --diff-filter=A --pretty=short -- foo

然后使用 commit^! 符号注释该提交与其父级之间的更改

git blame -C -C -f $commit^! -- foo

增量输出

当调用 --incremental 选项时，命令会随着结果的构建而输出结果。输出通常会首先谈论最近提交所触及的行（即，行将无序注释），旨在供交互式查看器使用。

输出格式类似于 Porcelain 格式，但它不包含要注释的文件中的实际行。

  1. 每个 blame 条目总是以一行开头

    <40-byte-hex-sha1> <sourceline> <resultline> <num-lines>

    行号从 1 开始计数。

  2. 当一个提交第一次出现在流中时，它会打印出各种其他信息，每行的开头带有一个单词标签，描述附加的提交信息（作者、电子邮件、提交者、日期、摘要等）。

  3. 与 Porcelain 格式不同，文件名信息总是给出并终止条目

    "filename" <whitespace-quoted-filename-goes-here>

    因此，对于一些面向行和单词的解析器来说，解析起来相当容易（这对于大多数脚本语言来说应该是很自然的）。

    注意
    		 对于进行解析的人员：为了使其更健壮，只需忽略第一行和最后一行（"<sha1>" 和 "filename" 行）之间任何您无法识别标签词（或不关心特定标签词）的行，这些标签词位于“扩展信息”行的开头。这样，即使将来添加了信息（例如提交编码或扩展提交注释），blame 查看器也不会受到影响。

作者映射

请参阅 gitmailmap[5]。

配置

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

blame.blankBoundary

在 git-blame[1] 中为边界提交显示空白提交对象名称。此选项默认为 false。

blame.coloring

这决定了应用于 blame 输出的着色方案。它可以是 repeatedLines、highlightRecent 或 none（默认）。

blame.date

指定 git-blame[1] 中用于输出日期的格式。如果未设置，则使用 iso 格式。有关支持的值，请参阅 git-log[1] 中 --date 选项的讨论。

blame.showEmail

在 git-blame[1] 中显示作者电子邮件而不是作者姓名。此选项默认为 false。

blame.showRoot

在 git-blame[1] 中不将根提交视为边界。此选项默认为 false。

blame.ignoreRevsFile

在 git-blame[1] 中，忽略文件中列出的版本，每行一个未缩写对象名称。空格和以 # 开头的注释将被忽略。此选项可以重复多次。空文件名将重置被忽略版本的列表。此选项将在命令行选项 --ignore-revs-file 之前处理。

blame.markUnblamableLines

在 git-blame[1] 的输出中，将那些由被忽略的版本更改但我们无法归因于另一个提交的行标记为 *。

blame.markIgnoredLines

在 git-blame[1] 的输出中，将那些由被忽略的版本更改但我们归因于另一个提交的行标记为 ?。

另请参阅

git-annotate[1]

GIT

Git[1] 套件的一部分

scroll-to-top