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:"）之后。

注释也可以通过使用 --notes 选项添加到使用 git format-patch 准备的补丁中。此类注释作为补丁注释添加在三破折号分隔行之后。

要更改 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-reverse 钩子的输入。） --stdin 不能与命令行上给出的对象名称组合使用。

append

：将 -m 或 -F 选项给出的新消息追加到现有注释，或如果对象没有注释则将它们添加为新注释（默认为 HEAD）。追加到现有注释时，在每条新消息之前添加空行作为段落间分隔符。可以使用 --separator 选项自定义分隔符。使用 -e 在追加注释之前以交互方式（使用编辑器）编辑要追加的注释。

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>, --no-stripspace

将给定的 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

合并注释时，更详细。修剪注释时，报告所有注释被移除的对象名称。

讨论

提交注释是包含有关对象的额外信息的 blob（通常是补充提交消息的信息）。这些 blob 取自注释引用。注释引用通常是包含"文件"的分支，其路径是它们描述的对象的对象名称，出于性能原因包含一些目录分隔符。

每次注释更改都会在指定的注释引用处创建新的提交。因此，您可以通过调用 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 系列命令显示提交消息时要从哪些引用读取注释。 此设置可以使用 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 的默认值外，使用 git log 系列命令显示提交消息时要从哪些引用读取注释。这覆盖了 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) 套件的一部分