簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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