簡體中文 ▾ 主題 ▾ 最新版本 ▾ git-notes 上次更新於 2.50.0

名稱

git-notes - 新增或檢查物件備註

概要

git notes [list [<object>]]
git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes copy [-f] ( --stdin | <from-object> [<to-object>] )
git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
git notes edit [--allow-empty] [<object>] [--[no-]stripspace]
git notes show [<object>]
git notes merge [-v | -q] [-s <strategy> ] <notes-ref>
git notes merge --commit [-v | -q]
git notes merge --abort [-v | -q]
git notes remove [--ignore-missing] [--stdin] [<object>…​]
git notes prune [-n] [-v]
git notes get-ref

描述

新增、移除或讀取附加到物件的備註，而不更改物件本身。

預設情況下，備註儲存到 refs/notes/commits 並從中讀取，但此預設值可以被覆蓋。請參閱下面的 OPTIONS、CONFIGURATION 和 ENVIRONMENT 部分。如果此引用不存在，則在首次需要儲存備註時會靜默建立。

備註的一個典型用途是補充提交訊息，而不更改提交本身。備註可以透過 git log 與原始提交訊息一起顯示。為了區分這些備註與提交物件中儲存的訊息，備註會像訊息一樣縮排，前面有一行不縮排的“Notes (<refname>):”（或者對於 refs/notes/commits 來說是“Notes:”）。

備註也可以透過使用 --notes 選項新增到使用 git format-patch 準備的補丁中。此類備註作為補丁註釋新增在三條破折號分隔線之後。

要更改 git log 顯示哪些備註，請參閱 CONFIGURATION 中 notes.displayRef 的討論。

請參閱 notes.rewrite.<command> 配置，瞭解如何在重寫提交的命令中保留備註。

子命令

list

列出給定物件的備註物件。如果未給定物件，則顯示所有備註物件及其註釋的物件列表（格式為“<note-object> <annotated-object>”）。這是未給定子命令時的預設子命令。

add

為給定物件（預設為 HEAD）新增備註。如果物件已有備註則中止（使用 -f 覆蓋現有備註）。但是，如果您以互動方式使用 add（使用編輯器提供備註內容），則 - 不會中止 - 現有備註將在編輯器中開啟（類似於 edit 子命令）。如果您指定多個 -m 和 -F，則訊息之間會插入一個空行。使用 --separator 選項插入其他分隔符。您可以使用 -e 在新增備註之前互動式地（使用編輯器）編輯和微調從 -m 和 -F 選項提供的訊息。

copy

將第一個物件的備註複製到第二個物件（預設為 HEAD）。如果第二個物件已有備註，或者第一個物件沒有備註，則中止（使用 -f 覆蓋第二個物件的現有備註）。此子命令等同於： git notes add [-f] -C $(git notes list <from-object>) <to-object>

在 --stdin 模式下，從標準輸入讀取以下格式的行

<from-object> SP <to-object> [ SP <rest> ] LF

並將其備註從每個 <from-object> 複製到其對應的 <to-object>。（可選的 <rest> 被忽略，以便命令可以讀取提供給 post-rewrite 鉤子的輸入。）

--stdin 不能與命令列中給定的物件名稱結合使用。

append

將 -m 或 -F 選項提供的新訊息附加到現有備註中，或者如果不存在，則將其新增為物件的新備註（預設為 HEAD）。當附加到現有備註時，每個新訊息前會新增一個空行作為段落間分隔符。分隔符可以透過 --separator 選項進行自定義。在附加備註之前，使用 -e 互動式地（使用編輯器）編輯由 -m 和 -F 選項提供的要附加的備註。

edit

編輯給定物件（預設為 HEAD）的備註。

show

顯示給定物件（預設為 HEAD）的備註。

merge

將給定的備註引用合併到當前備註引用中。這將嘗試將給定備註引用（稱為“遠端”）自合併基礎（如果有）以來的更改合併到當前備註引用（稱為“本地”）中。

如果發生衝突且未給定自動解決衝突備註的策略（參見“備註合併策略”部分），則使用 manual 解決器。此解決器將在特殊工作區（.git/NOTES_MERGE_WORKTREE）中檢出衝突的備註，並指示使用者在那裡手動解決衝突。完成後，使用者可以使用 git notes merge --commit 完成合並，或使用 git notes merge --abort 中止合併。

remove

移除給定物件（預設為 HEAD）的備註。當從命令列給定零個或一個物件時，這等同於向 edit 子命令指定空備註訊息。

在 --stdin 模式下，也移除標準輸入中給定的物件名稱。換句話說，--stdin 可以與命令列中的物件名稱結合使用。

prune

移除所有指向不存在/不可達物件的備註。

get-ref

列印當前備註引用。這提供了一種簡單的方法來檢索當前備註引用（例如，從指令碼中）。

選項

-f
--force

當向已包含備註的物件新增備註時，覆蓋現有備註（而不是中止）。

-m <msg>
--message=<msg>

使用給定的備註訊息（而不是提示）。如果給出多個 -m 選項，它們的值將連線成獨立的段落。

-F <file>
--file=<file>

從給定檔案中讀取備註訊息。使用 - 從標準輸入讀取備註訊息。

-C <object>
--reuse-message=<object>

將給定的 blob 物件（例如，另一條備註）作為備註訊息。（使用 git notes copy <object> 來在物件之間複製備註）。這意味著 --no-stripspace，因為預設行為是逐字複製訊息。

-c <object>
--reedit-message=<object>

類似於 -C，但使用 -c 時會呼叫編輯器，以便使用者可以進一步編輯備註訊息。

--allow-empty

允許儲存空備註物件。預設行為是自動移除空備註。

--separator=<paragraph-break>
--separator
--no-separator

指定用作自定義段落間分隔符的字串（必要時末尾會新增一個換行符）。如果使用 --no-separator，則段落之間不新增任何分隔符。預設為一個空行。

--stripspace
--no-stripspace

清理空白。具體來說（參見 git-stripspace[1]）：

  • 移除所有行的尾隨空白

  • 將多個連續的空行合併為一個空行

  • 移除輸入開頭和結尾的空行

  • 如果需要，在最後一行新增缺失的 \n。

--stripspace 是預設設定，除了 -C/--reuse-message。但是，請記住這取決於相似選項的順序。例如，對於 -C <object> -m<message>，將使用 --stripspace，因為 -m 的預設設定覆蓋了之前的 -C。這是一個已知限制，將來可能會修復。

--ref=<ref>

操作 <ref> 中的備註樹。這將覆蓋 GIT_NOTES_REF 和 core.notesRef 配置。如果引用以 refs/notes/ 開頭，則它指定完整的引用名稱；如果它以 notes/ 開頭，則新增 refs/；否則，新增 refs/notes/ 作為字首以形成引用的完整名稱。

--ignore-missing

如果請求從沒有附加備註的物件中移除備註，則不將其視為錯誤。

--stdin

僅對 remove 和 copy 有效。參見各自的子命令。

-n
--dry-run

不移除任何內容；僅報告其備註將被移除的物件名稱。

-s <strategy>
--strategy=<strategy>

合併備註時，使用給定策略解決備註衝突。識別以下策略：manual（預設）、ours、theirs、union 和 cat_sort_uniq。此選項會覆蓋 notes.mergeStrategy 配置設定。有關每種備註合併策略的更多資訊，請參閱下面的“備註合併策略”部分。

--commit

完成正在進行的 git notes merge。當您已解決 git notes merge 儲存在 .git/NOTES_MERGE_WORKTREE 中的衝突時，使用此選項。這會透過新增 .git/NOTES_MERGE_WORKTREE 中的備註來修改由 git notes merge 建立的部分合並提交（儲存在 .git/NOTES_MERGE_PARTIAL 中）。儲存在 .git/NOTES_MERGE_REF 符號引用中的備註引用將更新為結果提交。

--abort

中止/重置正在進行的 git notes merge，即有衝突的備註合併。這隻會移除所有與備註合併相關的檔案。

-q
--quiet

合併備註時，靜默操作。

-v
--verbose

合併備註時，更詳細地操作。修剪備註時，報告所有被移除備註的物件名稱。

討論

提交備註是包含物件額外資訊（通常是補充提交訊息的資訊）的 Git blob。這些 blob 取自備註引用。備註引用通常是一個分支，其中包含“檔案”，其路徑是它們所描述的物件的物件名稱，並出於效能原因包含一些目錄分隔符[1]。

每次備註更改都會在指定備註引用上建立一個新提交。因此，您可以透過呼叫例如 git log -p notes/commits 來檢查備註的歷史記錄。目前，提交訊息僅記錄觸發更新的操作，提交作者由通常的規則確定（參見 git-commit[1]）。這些細節將來可能會改變。

還允許備註引用直接指向一個樹物件，在這種情況下，備註的歷史記錄可以透過 git log -p -g <refname> 讀取。

備註合併策略

預設的備註合併策略是 manual，它會在一個特殊的用於解決備註衝突的工作樹（.git/NOTES_MERGE_WORKTREE）中檢出衝突的備註，並指示使用者在該工作樹中解決衝突。完成後，使用者可以使用 git notes merge --commit 完成合並，或使用 git notes merge --abort 中止合併。

使用者可以使用 -s/--strategy 選項或相應地配置 notes.mergeStrategy 從以下自動化合並策略中選擇：

ours 自動解決衝突備註，優先採用本地版本（即當前備註引用）。

theirs 自動解決備註衝突，優先採用遠端版本（即正在合併到當前備註引用中的給定備註引用）。

union 自動透過連線本地和遠端版本來解決備註衝突。

cat_sort_uniq 類似於 union，但除了連線本地和遠端版本外，此策略還會對結果行進行排序，並從結果中移除重複行。這等同於對本地和遠端版本應用“cat | sort | uniq”shell 管道。如果備註遵循基於行的格式，並且希望避免合併結果中出現重複行，則此策略非常有用。請注意，如果本地或遠端版本在合併之前包含重複行，這些行也將被此備註合併策略移除。

示例

您可以使用備註來新增在提交寫入時不可用的資訊註釋。

$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
$ git show -s 72a144e
[...]
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

Notes:
    Tested-by: Johannes Sixt <j6t@kdbg.org>

原則上，備註是常規的 Git blob，接受任何型別的（非）格式。您可以使用 git hash-object 安全地從任意檔案建立二進位制備註

$ cc *.c
$ blob=$(git hash-object -w a.out)
$ git notes --ref=built add --allow-empty -C "$blob" HEAD

（您不能簡單地使用 git notes --ref=built add -F a.out HEAD，因為那不是二進位制安全的。）當然，用 git log 顯示非文字格式的備註意義不大，所以如果您使用此類備註，您可能需要編寫一些專用工具來對其進行有用的處理。

配置

core.notesRef

用於讀取和操作備註的引用，而不是 refs/notes/commits。必須是未縮寫的引用名稱。此設定可以透過環境變數和命令列覆蓋。

本節中此行以上的所有內容均未包含在 git-config[1] 文件中。以下內容與該文件中的內容相同

notes.mergeStrategy

解決備註衝突時預設選擇的合併策略。必須是 manual、ours、theirs、union 或 cat_sort_uniq 之一。預設為 manual。有關每種策略的更多資訊，請參閱 git-notes[1] 的“備註合併策略”部分。

此設定可以透過向 git-notes[1] 傳遞 --strategy 選項來覆蓋。

notes.<name>.mergeStrategy

當將備註合併到 refs/notes/<name> 時選擇的合併策略。這會覆蓋更通用的 notes.mergeStrategy。有關可用策略的更多資訊，請參閱 git-notes[1] 的“備註合併策略”部分。

notes.displayRef

除了由 core.notesRef 或 GIT_NOTES_REF 設定的預設集合之外，在使用 git log 系列命令顯示提交訊息時，從哪個引用（或多個引用，如果是 glob 或多次指定）讀取備註。

此設定可以透過 GIT_NOTES_DISPLAY_REF 環境變數覆蓋，該變數必須是一個以冒號分隔的引用或 glob 列表。

對於不存在的引用將發出警告，但與任何引用不匹配的 glob 將被靜默忽略。

此設定可以透過 git-log[1] 系列命令的 --no-notes 選項停用，或者透過這些命令接受的 --notes=<ref> 選項停用。

core.notesRef 的有效值（可能被 GIT_NOTES_REF 覆蓋）也會隱式新增到要顯示的引用列表中。

notes.rewrite.<command>

使用 <command>（當前為 amend 或 rebase）重寫提交時，如果此變數為 false，git 將不會將備註從原始提交複製到重寫後的提交。預設為 true。另請參見下面的 notes.rewriteRef。

此設定可以透過 GIT_NOTES_REWRITE_REF 環境變數覆蓋，該變數必須是一個以冒號分隔的引用或 glob 列表。

notes.rewriteMode

在重寫期間複製備註時（參見 notes.rewrite.<command> 選項），確定如果目標提交已有備註該如何處理。必須是 overwrite、concatenate、cat_sort_uniq 或 ignore 之一。預設為 concatenate。

此設定可以透過 GIT_NOTES_REWRITE_MODE 環境變數覆蓋。

notes.rewriteRef

在重寫期間複製備註時，指定（完全限定的）要複製備註的引用。可以是一個 glob，在這種情況下，所有匹配引用中的備註都將被複制。您也可以多次指定此配置。

沒有預設值；您必須配置此變數才能啟用備註重寫。將其設定為 refs/notes/commits 以啟用預設提交備註的重寫。

可以透過 GIT_NOTES_REWRITE_REF 環境變數覆蓋。有關其格式的進一步描述，請參見上面的 notes.rewrite.<command>。

環境變數

GIT_NOTES_REF

要操作備註的引用，而不是 refs/notes/commits。這會覆蓋 core.notesRef 設定。

GIT_NOTES_DISPLAY_REF

冒號分隔的引用或 glob 列表，指示除了 core.notesRef 或 GIT_NOTES_REF 的預設值之外，在顯示提交訊息時從哪些引用讀取備註。這會覆蓋 notes.displayRef 設定。

對於不存在的引用將發出警告，但與任何引用不匹配的 glob 將被靜默忽略。

GIT_NOTES_REWRITE_MODE

在重寫期間複製備註時，如果目標提交已包含備註，則如何處理。必須是 overwrite、concatenate、cat_sort_uniq 或 ignore 之一。這會覆蓋 core.rewriteMode 設定。

GIT_NOTES_REWRITE_REF

重寫提交時，將哪些備註從原始提交複製到重寫後的提交。必須是冒號分隔的引用或 glob 列表。

如果在環境中未設定，要複製的備註列表取決於 notes.rewrite.<command> 和 notes.rewriteRef 設定。

GIT

Git[1] 套件的一部分

1. 允許的路徑名形式為 bf/fe/30/…​/680d5a…​：一個由兩個十六進位制數字組成的目錄名序列，後跟一個包含物件 ID 剩餘部分的檔名。
scroll-to-top