簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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 中並從中讀取，但此預設設定可以被覆蓋。請參閱下面的選項、配置和環境變數部分。如果此引用不存在，將在首次需要儲存筆記時自動建立。

筆記的一個典型用法是在不更改提交本身的情況下補充提交訊息。筆記可以與原始提交訊息一起透過 git log 顯示。為了區分這些筆記和儲存在提交物件中的訊息，筆記的縮排方式與訊息相同，在一段不縮排的行“Notes (<refname>):”（或對於 refs/notes/commits 顯示“Notes:”）之後。

使用 git format-patch 準備的補丁也可以透過使用 --notes 選項新增筆記。這些筆記在三條短線分隔符之後作為補丁註釋新增。

要更改 git log 顯示的筆記，請參閱 配置 部分中的 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

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

如果出現衝突，並且未指定自動解決衝突筆記的策略（請參閱“NOTES MERGE STRATEGIES”部分），則使用 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 配置設定。有關每種筆記合併策略的更多資訊，請參閱下面的“NOTES MERGE STRATEGIES”部分。

--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

合併筆記時，更詳細。修剪筆記時，報告所有將被刪除筆記的物件名稱。

討論

提交筆記是包含有關物件額外資訊的 blob（通常是補充提交訊息的資訊）。這些 blob 來自筆記引用。筆記引用通常是一個包含“檔案”的分支，其路徑是它們描述的物件的物件名稱，為提高效能會包含一些目錄分隔符[1]。

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

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

NOTES MERGE STRATEGIES

預設的筆記合併策略是 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

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

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

notes.<name>.mergeStrategy

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

notes.displayRef

除了由 core.notesRef 或 GIT_NOTES_REF 預設設定之外，還從哪個 ref（或 refs，如果是 glob 或指定多次）讀取 notes，用於在顯示提交訊息時（使用 git-log[1] 系列命令）。

此設定可以透過 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 不會從原始提交複製 notes 到重寫的提交。預設為 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

冒號分隔的引用列表或萬用字元，指示除了 core.notesRef 或 GIT_NOTES_REF 的預設值外，還從哪些引用讀取筆記來顯示提交訊息。這會覆蓋 notes.displayRef 設定。

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

GIT_NOTES_REWRITE_MODE

在重寫時複製筆記，如果目標提交已具有筆記，該如何處理。必須是 overwrite、concatenate、cat_sort_uniq 或 ignore 之一。這會覆蓋 core.rewriteMode 設定。

GIT_NOTES_REWRITE_REF

重寫提交時，從原始提交複製哪些筆記到重寫的提交。必須是冒號分隔的引用列表或萬用字元。

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

GIT

Git[1] 套件的一部分

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