Git
简体中文 ▾ Topics ▾ Latest version ▾ git-blame last updated in 2.44.0

名称

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

概述

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

描述

用最后一次修改该行的修订版的信息来注释给定文件中的每一行。可以选择从给定的修订版开始做注释。

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

在整个文件的重命名过程中,行的起源被自动跟踪(目前没有选项可以关闭重命名跟踪)。要跟踪从一个文件移到另一个文件的行,或者跟踪从另一个文件复制和粘贴的行,等等,请参见 -C-M 选项。

报告不会告诉你任何关于被删除或替换的行的信息;你需要使用一个工具,如 git diff 或下段中简要提到的 pickaxe 接口。

除了支持文件注释外,Git 还支持在开发历史中搜索代码片段何时发生变化。这使得追踪一个代码片段何时被添加到一个文件,在文件之间移动或复制,以及最终被删除或替换成为可能。它的工作原理是在差异中搜索一个文本字符串。一个搜索 blame_usage 的 pickaxe 界面的小例子:

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <祖先文件>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

选项

-b

Show blank SHA-1 for boundary commits. This can also be controlled via the blame.blankBoundary config option.

--root

Do not treat root commits as boundaries. This can also be controlled via the blame.showRoot config option.

--show-stats

在历史追溯输出的结尾处包括额外的统计数据。

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

Annotate only the line range given by <start>,<end>, or by the function name regex <funcname>. May be specified multiple times. Overlapping ranges are allowed.

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

<开始><结束> 可以采取这些形式之一:

  • 数目

    如果'<开始>'或'<结束>'是一个数字,它指定了一个绝对行数(行数从1开始计算)。

  • /正则表达式/

    This form will use the first line matching the given POSIX regex. If <start> is a regex, it will search from the end of the previous -L range, if any, otherwise from the start of file. If <start> is ^/regex/, it will search from the start of file. If <end> is a regex, it will search starting at the line given by <start>.

  • +offset或-offset

    这只对'<end>'有效,将指定'<start>'所给的行前或行后的数量。

如果`:<funcname>代替了'<start>'和'<end>',它是一个正则表达式,表示从第一个匹配'<funcname>'的funcname行开始,直到下一个funcname行的范围。:<funcname>从上一个-L’范围的末尾开始搜索,如果有的话,则从文件的开始搜索。‘^:<funcname>`从文件的开始搜索。函数名的确定方式与 `git diff`确定补丁组头的方式相同(见 gitattributes[5] 中的’定义自定义组头’)。

-l

显示长转(默认值:关闭)。

-t

显示原始时间戳(默认值:关闭)。

-S <修订文件>

使用revs-file中的修订,而不是调用 git-rev-list[1]

--reverse <修订>..<修订>

Walk history forward instead of backward. Instead of showing the revision in which a line appeared, this shows the last revision in which a line has existed. This requires a range of revision like START..END where the path to blame exists in START. git blame --reverse START is taken as git blame --reverse START..HEAD for convenience.

--first-parent

在看到合并提交时只关注第一个父提交。这个选项可以用来确定某一行何时被引入某个特定的集成分支,而不是何时被引入整个历史中。

-p
--porcelain

以适合机器使用的格式显示。

--line-porcelain

Show the porcelain format, but output commit information for each line, not just the first time a commit is referenced. Implies --porcelain.

--incremental

以适合机器使用的格式逐步显示结果。

--encoding=<编码>

指定用于输出作者姓名和提交摘要的编码。设置为 none 会使历史追溯输出未转换的数据。更多信息见 git-log[1] 手册页中关于编码的讨论。

--contents <文件>

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

--date <格式>

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

--[no-]progress

当它连接到一个终端时,默认情况下进度状态会在标准错误流中报告。这个标志可以使进度报告即使没有连接到终端。--porcelain`或--incremental` 不能与 --progress 一起使用。

-M[<数量>]

Detect moved or copied lines within a file. When a commit moves or copies a block of lines (e.g. the original file has A and then B, and the commit changes it to B and then A), the traditional blame algorithm notices only half of the movement and typically blames the lines that were moved up (i.e. B) to the parent and assigns blame to the lines that were moved down (i.e. A) to the child commit. With this option, both groups of lines are blamed on the parent by running extra passes of inspection.

<num> 是可选的,但它是 Git 必须检测到的在文件中移动或复制的字母数字字符的数量的下限,以便它将这些行与父提交相关联。默认值是20。

-C[<数量>]

In addition to -M, detect lines moved or copied from other files that were modified in the same commit. This is useful when you reorganize your program and move code around across files. When this option is given twice, the command additionally looks for copies from other files in the commit that creates the file. When this option is given three times, the command additionally looks for copies from other files in any commit.

<num>是 可选的,但它是 Git 必须检测到的在文件之间移动或复制的字母数字字符的数量的下限,以便它将这些行与父提交关联起来。而默认值是 40。如果有一个以上的 `-C ` 选项,只有最后一个 `-C `的 <num> 参数起作用。

--ignore-rev <修订>

Ignore changes made by the revision when assigning blame, as if the change never happened. Lines that were changed or added by an ignored commit will be blamed on the previous commit that changed that line or nearby lines. This option may be specified multiple times to ignore more than one revision. If the blame.markIgnoredLines config option is set, then lines that were changed by an ignored commit and attributed to another commit will be marked with a ? in the blame output. If the blame.markUnblamableLines config option is set, then those lines touched by an ignored commit that we could not attribute to another revision are marked with a *.

--ignore-revs-file <文件>

Ignore revisions listed in file, which must be in the same format as an fsck.skipList. This option may be repeated, and these files will be processed after any files specified with the blame.ignoreRevsFile config option. An empty file name, "", will clear the list of revs from previously processed files.

--color-lines

在默认格式下,如果行注释与前一行来自同一提交,则颜色不同。这可以让我们更容易区分不同提交的代码块。颜色默认为青色,可以使用 color.blame.repeatedLines 配置选项进行调整。

--color-by-age

Color line annotations depending on the age of the line in the default format. The color.blame.highlightRecent config option controls what color is used for each range of age.

-h

显示帮助信息。

-c

使用与 git-annotate[1] 相同的输出模式(默认:关闭)。

--score-debug

Include debugging information related to the movement of lines between files (see -C) and lines moved within a file (see -M). The first number listed is the score. This is the number of alphanumeric characters detected as having been moved between or within files. This must be above a certain threshold for git blame to consider those lines of code to have been moved.

-f
--show-name

Show the filename in the original commit. By default the filename is shown if there is any line that came from a file with a different name, due to rename detection.

-n
--show-number

显示原始提交中的行号(默认:off)。

-s

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

-e
--show-email

Show the author email instead of the author name (Default: off). This can also be controlled via the blame.showEmail config option.

-w

在比较父本和子本的版本时,忽略空白,以找到行的来源。

--abbrev=<n>

Instead of using the default 7+1 hexadecimal digits as the abbreviated object name, use <m>+1 digits, where <m> is at least <n> but ensures the commit object names are unique. Note that 1 column is used for a caret to mark the boundary commit.

默认格式

当既没有指定`--porcelain` 也没有指定`--incremental` 选项时,git blame 将为每一行输出注释:

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

  • 作者身份(默认为作者姓名和日期,除非指定`s`或`e`);以及

  • --line-number

在该行内容之前。

上层命令格式

在这种格式中,每一行都是在页眉之后输出的;页眉至少有第一行,它有:

  • 该行所归属的提交的 40 字节 SHA-1;

  • 原始文件中该行的行号;

  • 最后文件中该行的行号;

  • on a line that starts a group of lines from a different commit than the previous one, the number of lines in this group. On subsequent lines this field is absent.

这个标题行后面是以下信息,每次提交至少有一次:

  • 作者姓名("author")、电子邮件("author-mail")、时间("author-time")和时区("author-tz");对提交者也是如此。

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

  • 提交日志信息的第一行("摘要")。

实际行的内容会在上述标题之后输出,前缀为 TAB。这是为了允许以后添加更多的标题元素。

The porcelain format generally suppresses commit information that has already been seen. For example, two lines that are blamed to the same commit will both be shown, but the details for that commit will be shown only once. This is more efficient, but may require more state be kept by the reader. The --line-porcelain option can be used to output full commit information for each line, allowing simpler (but less efficient) usage like:

# 统计每位作者的作品数
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

指定范围

与旧版本的 "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 周的最新提交)以来没有改变的行被指责为该范围边界提交。

A particularly useful way is to see if an added file has lines created by copy-and-paste from existing files. Sometimes this indicates that the developer was being sloppy and did not refactor the code properly. You can first find the commit that introduced the file with:

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

然后用 commit^! 符号来注释该提交和其父辈之间的变化:

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

增量输出

When called with --incremental option, the command outputs the result as it is built. The output generally will talk about lines touched by more recent commits first (i.e. the lines will be annotated out of order) and is meant to be used by interactive viewers.

输出格式类似于上层命令格式,但它不包含被注释的文件的实际行数。

  1. 每个历史追溯条目总是以一行字开始:

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

    行数从 1 开始计算。

  2. 当一个提交首次出现在数据流中时,它的各种其他信息会被打印出来,每一行的开头都有一个单字标签,描述额外的提交信息(作者、电子邮件、提交者、日期、摘要等)。

  3. 与上层命令格式不同,文件名信息总是给定的,并终止条目:

    "filename" <空白引号-片名-到此为止>

    因此,对于一些面向行和字的解析器来说,它确实很容易解析(这对于大多数脚本语言来说应该是很自然的)。

    Note
    For people who do parsing: to make it more robust, just ignore any lines between the first and last one ("<sha1>" and "filename" lines) where you do not recognize the tag words (or care about that particular one) at the beginning of the "extended information" lines. That way, if there is ever added information (like the commit encoding or extended commit commentary), a blame viewer will not care.

制图作者

参见 gitmailmap[5]

配置

Warning

Missing zh_HANS-CN/includes/cmd-config-section-all.txt

See original version for this content.

Warning

Missing zh_HANS-CN/config/blame.txt

See original version for this content.

GIT

属于 git[1] 文档

scroll-to-top