Git
English ▾ 主題 ▾ 最新版本 ▾ git-notes 上次更新於 2.44.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>] [<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>] [<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:」）。

透過使用 --notes 選項，註解也可以新增到使用 git format-patch 準備的修補程式。此類註解會以三個破折號分隔線後的修補程式註解形式新增。

若要變更 git log 顯示的註解，請參閱 組態 中的「notes.displayRef」討論。

請參閱「notes.rewrite.<command>」組態，了解如何在重新寫入提交的命令中傳遞註解。

子命令

list

列出給定物件的註解物件。如果未提供任何物件，則顯示所有註解物件及其註解的物件清單（格式為「<note-object> <annotated-object>」）。如果未提供任何子命令，這是預設的子命令。

add

新增給定物件（預設為 HEAD）的註解。如果物件已具有註解，則中止（使用 -f 覆寫現有註解）。但是，如果您以互動方式使用 add（使用編輯器提供註解內容），則不會中止，而是會在編輯器中開啟現有的註解（如同 edit 子命令）。如果您指定多個 -m 和 -F，則會在訊息之間插入空白行。使用 --separator 選項插入其他分隔符號。

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 hook 的輸入。）

append

將 -m 或 -F 選項給定的新訊息附加到現有註解，如果物件不存在註解，則將其新增為新註解（預設為 HEAD）。附加到現有註解時，會在每個新訊息之前加入空白行，作為段落分隔符號。分隔符號可以使用 --separator 選項自訂。

edit

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

show

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

merge

將給定的註解參考合併到目前的註解參考。這會嘗試將給定的註解參考（稱為「遠端」）自合併基準（如果有的話）以來所做的變更合併到目前的註解參考（稱為「本機」）。

如果發生衝突，且未提供自動解決衝突註解的策略（請參閱「註解合併策略」章節），則會使用「手動」解析器。此解析器會在特殊工作樹狀結構中取出衝突的註解（.git/NOTES_MERGE_WORKTREE），並指示使用者在那裡手動解決衝突。完成後，使用者可以使用 git notes merge --commit 完成合併，或使用 git notes merge --abort 中止合併。

remove

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

prune

移除所有不存在/無法存取物件的註解。

get-ref

列印目前的註解參考。這提供了一種輕鬆擷取目前註解參考的方法（例如，從腳本）。

選項

-f
--force

當將註解新增到已具有註解的物件時，覆寫現有的註解（而不是中止）。

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

使用給定的註解訊息（而不是提示）。如果提供多個 -m 選項，它們的值會串連成個別段落。開頭為 # 的行和段落之間單行以外的空白行將被移除。如果您希望逐字保留它們，請使用 --no-stripspace。

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

從給定的檔案取得註解訊息。使用 - 從標準輸入讀取註解訊息。開頭為 # 的行和段落之間單行以外的空白行將被移除。如果您希望逐字保留它們，請使用 --no-stripspace。

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

採用給定的 blob 物件（例如，另一個註解）作為註解訊息。（改用 git notes copy <object> 在物件之間複製註解。）。預設情況下，訊息會逐字複製，但如果您希望移除開頭為 # 的行和段落之間單行以外的空白行，請使用 `--stripspace` 選項。

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

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

--allow-empty

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

--[no-]separator, --separator=<paragraph-break>

指定一個字串作為自訂的段落分隔符號（視需要會在結尾新增換行符號）。如果為 --no-separator，則不會在段落之間新增分隔符號。預設為空白行。

--[no-]stripspace

移除註解訊息的開頭和結尾空白。也會移除段落之間單行以外的空白行。開頭為 # 的行會在非編輯器案例（例如 -m、-F 和 -C）中移除，但在編輯器案例（例如 git notes edit、-c 等）中則不會移除。

--ref <ref>

操作 <ref> 中的註解樹狀結構。這會覆蓋 GIT_NOTES_REF 和 "core.notesRef" 設定。ref 參照當以 refs/notes/ 開頭時，會指定完整的 ref 名稱；當以 notes/ 開頭時，會加上 refs/ 前綴；否則會加上 refs/notes/ 前綴來形成 ref 的完整名稱。

--ignore-missing

當要求移除未附加註解的物件的註解時，不將其視為錯誤。

--stdin

同時從標準輸入讀取要移除註解的物件名稱（沒有理由不能將此與命令列中的物件名稱結合使用）。

-n
--dry-run

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

-s <策略>
--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 符號連結中的註解 ref 會更新為產生的提交。

--abort

中止/重設進行中的 *git notes merge*，也就是有衝突的註解合併。這只會移除所有與註解合併相關的檔案。

-q
--quiet

當合併註解時，安靜地操作。

-v
--verbose

當合併註解時，更加詳細。當修剪註解時，報告所有被移除註解的物件名稱。

討論

提交註解是包含物件額外資訊的 blob（通常是用於補充提交訊息的資訊）。這些 blob 來自於註解 ref。註解 ref 通常是一個分支，其中包含「檔案」，其路徑是描述的物件的物件名稱，並包含一些目錄分隔符號以提高效能 [1]。

每個註解變更都會在指定的註解 ref 建立一個新的提交。因此，您可以透過呼叫，例如 git log -p notes/commits 來檢視註解的歷史記錄。目前，提交訊息僅記錄觸發更新的操作，並且根據一般規則決定提交作者（請參閱 git-commit[1]）。這些細節將來可能會變更。

註解 ref 也允許直接指向樹狀物件，在這種情況下，可以使用 git log -p -g <refname> 讀取註解的歷史記錄。

註解合併策略

預設的註解合併策略是「manual」，它會在特殊工作樹中檢查有衝突的註解，以解決註解衝突 (.git/NOTES_MERGE_WORKTREE)，並指示使用者在該工作樹中解決衝突。完成後，使用者可以使用 *git notes merge --commit* 完成合併，或使用 *git notes merge --abort* 中止合併。

使用者可以使用 -s/--strategy 選項或相應地設定 notes.mergeStrategy，從以下選項中選擇自動合併策略

「ours」自動解決衝突的註解，優先選擇本機版本（即目前的註解 ref）。

「theirs」自動解決註解衝突，優先選擇遠端版本（即要合併到目前註解 ref 中的給定註解 ref）。

「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

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

本節中高於此行的所有內容不包含在 git-config[1] 文件中。接下來的內容與那裡找到的內容相同

notes.mergeStrategy

當解決註解衝突時，預設選擇哪個合併策略。必須是 manual、ours、theirs、union 或 cat_sort_uniq 其中之一。預設為 manual。請參閱 git-notes[1] 的「註解合併策略」章節，以取得有關每個策略的更多資訊。

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

notes.<name>.mergeStrategy

當執行註解合併到 refs/notes/<name> 時，選擇哪個合併策略。這會覆蓋更通用的 "notes.mergeStrategy"。請參閱 git-notes[1] 中「註解合併策略」章節，以取得有關可用策略的更多資訊。

notes.displayRef

除了由 core.notesRef 或 GIT_NOTES_REF 設定的預設集之外，還有哪些 ref (或 ref，如果為 glob 或指定多次)，要在使用 *git log* 系列命令顯示提交訊息時從中讀取註解。

此設定可以使用 GIT_NOTES_DISPLAY_REF 環境變數覆蓋，該變數必須是以冒號分隔的 ref 或 glob 清單。

對於不存在的 ref 會發出警告，但如果 glob 不符合任何 ref，則會自動忽略。

此設定可以使用 *git log* 系列命令的 --no-notes 選項或這些命令接受的 --notes=<ref> 選項來停用。

"core.notesRef" 的有效值（可能被 GIT_NOTES_REF 覆蓋）也會隱式加入要顯示的 ref 清單中。

notes.rewrite.<command>

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

此設定可以使用 GIT_NOTES_REWRITE_REF 環境變數覆蓋，該變數必須是以冒號分隔的 ref 或 glob 清單。

notes.rewriteMode

當在重寫期間複製註解時（請參閱 "notes.rewrite.<command>" 選項），決定如果目標提交已經有註解時要執行什麼操作。必須是 overwrite、concatenate、cat_sort_uniq 或 ignore 其中之一。預設為 concatenate。

此設定可以使用 GIT_NOTES_REWRITE_MODE 環境變數覆蓋。

notes.rewriteRef

當在重寫期間複製註解時，指定應複製其註解的（完全限定的）ref。可以是 glob，在這種情況下，會複製所有符合 ref 中的註解。您也可以多次指定此設定。

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

可以使用 GIT_NOTES_REWRITE_REF 環境變數覆蓋。請參閱上述的 notes.rewrite.<command>，以進一步說明其格式。

環境

GIT_NOTES_REF

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

GIT_NOTES_DISPLAY_REF

以冒號分隔的 ref 或 glob 清單，指示除了來自 core.notesRef 或 GIT_NOTES_REF 的預設值之外，還有哪些 ref 要在顯示提交訊息時從中讀取註解。這會覆蓋 notes.displayRef 設定。

對於不存在的 ref 會發出警告，但如果 glob 不符合任何 ref，則會自動忽略。

GIT_NOTES_REWRITE_MODE

當在重寫期間複製註解時，如果目標提交已經有註解，則要執行什麼操作。必須是 overwrite、concatenate、cat_sort_uniq 或 ignore 其中之一。這會覆蓋 core.rewriteMode 設定。

GIT_NOTES_REWRITE_REF

當重寫提交時，要將哪些註解從原始提交複製到重寫的提交。必須是以冒號分隔的 ref 或 glob 清單。

如果未在環境中設定，則要複製的註解清單取決於 notes.rewrite.<command> 和 notes.rewriteRef 設定。

GIT

屬於 git[1] 套件的一部分

1. 允許的路徑名稱格式為 *bf*/fe/30/…​/680d5a…​：一系列兩個十六進位數字的目錄名稱，後面接著包含其餘物件 ID 的檔名。
scroll-to-top