简体中文 ▾ Topics ▾ Latest version ▾ git-notes last updated in 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>] [<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 中，并且可以覆盖此默认设置。请参阅下面的 OPTIONS、CONFIGURATION 和 ENVIRONMENT 部分。如果该引用不存在，当首次需要存储注释时，它将被静默地创建。

注释的一个典型用途是在不改变提交本身的情况下补充提交信息。注释可以通过 "git log "与原始提交信息一起显示。为了将这些注释与保存在提交对象中的消息区分开来，注释会像消息一样缩进，在未缩进的一行后面写上 "注释（<引用名称>）："（或 "注释："用于`参考/注释/提交`）。

注释也可以通过使用`git format-patch`选项添加到补丁中，--notes。这样的注释会作为补丁注释添加在三个破折号的分隔线之后。

要更改 git log 显示的注释，请参阅 配置 中的 notes.displayRef 讨论。

参见 `notes.rewrite.<command>`配置，以了解在重写提交的命令中携带笔记的方法。

次级单位

list

列出给定对象的注释对象。如果没有给定对象，则显示所有注解对象及其注解的对象的列表（格式为"<注解对象><注解对象>"）。 如果没有给出子命令，这是默认的子命令。

add

为给定对象添加注释（默认为 HEAD）。如果对象已有注释，则终止添加（使用 -f 覆盖现有注释）。 但是，如果使用 add 交互式命令（使用编辑器提供注释内容），那么现有注释将在编辑器中打开（类似于 edit 子命令），而不是终止。如果指定多个 -m 和 -F，将在信息之间插入空行。使用 --separator 选项可以插入其他分隔符。

copy

将第一个对象的注释复制到第二个对象上（默认为HEAD）。如果第二个对象已经有注解，或者第一个对象没有注解，则放弃（使用 -f 将现有注解覆盖到第二个对象）。这个子命令等同于。git notes add [-f] -C $(git notes list <from-object>) <to-object>

在`--stdin`模式下，采取格式为

<从对象> SP <到对象 [ SP <停止> ] LF

在标准输入中，将每个 <from-object> 中的注释复制到相应的 <to-object> 中。（可选的 <rest> 被忽略，以便命令可以读取给 post-rewrite 钩的输入）

验证 git commit -S 创建的 GPG 签名。

append

将 -m 或 -F 选项指定的新信息附加到现有注释中，或将不存在的信息作为新注释添加到对象中（默认为 HEAD）。 当添加到现有注释时，每条新信息前都会添加一个空行作为段间分隔符。 分隔符可使用 --separator 选项自定义。

edit

编辑一个给定对象的注释（默认为HEAD）。

show

显示一个给定对象的注释（默认为HEAD）。

merge

将给定的注释参考文献合并到当前的注释参考文献中。 这将尝试把给定的注释（称为 "远程"）自合并基础（如果有的话）以来所做的修改合并到当前的注释（称为 "本地"）。

如果出现冲突，并且没有给出自动解决冲突笔记的策略（见 "NOTES MERGE STRATEGIES "一节），就会使用 "手动 "解决器。这个解决方法在一个特殊的工作区（.git/NOTES_MERGE_WORKTREE）中检查出冲突的笔记，并指示用户手动解决那里的冲突。 完成后，用户可以用 "git notes merge --commit "最终完成合并，或者用 "git notes merge --abort "中止合并。

remove

删除给定对象的注释（默认为HEAD）。当从命令行给出零或一个对象时，这相当于给`edit`子命令指定一个空的注释信息。

还可以从标准输入中读取对象名称来删除注释（你没有理由不把它与命令行的对象名称结合起来）。

prune

删除所有不存在/无法到达的对象的注释。

get-ref

打印当前的注释参考。这提供了一个简单的方法来检索当前的笔记参考文献（例如从脚本中）。

选项

-f
--force

当向一个已经有注释的对象添加注释时，覆盖现有的注释（而不是中止）。

-m <消息>
--message=<msg>

使用给定的<msg>作为提交信息。 如果给定了多个`-m`选项，它们的值会作为单独的段落串联起来。

-F <文件>
--file=<文件>

从给定文件中获取提交信息。 使用`-`可以从标准输入中读取信息。

-C <对象>
--reuse-message=<对象>

将给定的blob对象（例如，另一个笔记）作为笔记信息。(使用`git notes copy <object>`来代替在对象之间复制注释)。

-c <对象>
--reedit-message=<对象>

像 -C 一样，但有了 -c 就会调用编辑器，这样用户就可以进一步编辑注释信息。

--allow-empty

允许存储一个空的笔记对象。默认行为是自动删除空笔记。

--[no-]separator, --separator=<段落分隔符>
--separator
--no-separator

指定用于自定义段落间分隔符的字符串（根据需要在末尾添加换行符）。如果使用 --no-separator，则段落之间不添加分隔符。 默认为空行。

--stripspace
--no-stripspace

清理空白字符。具体来说（见 git-stripspace[1]）：

  • 删除所有行的尾部空白

  • 将多个连续空行折叠为一个空行

  • 删除输入内容开头和结尾的空行

  • 如有必要，在最后一行添加一个缺失的 \n。

除了 -C/--reuse-message 之外，默认使用 --stripspace。不过请注意，这取决于类似选项出现的顺序。例如，对于 -C <object> -m<message>，会使用 --stripspace，因为 -m 的默认值会覆盖之前的 -C。这是一个已知限制，将来可能会修复。

--ref <引用>

操纵<ref>中的笔记树。 这覆盖了`GIT_NOTES_REF`和 "core.notesRef "配置。 当Ref以`refs/notes/开始时，指定完整的Ref名称；当它以`notes/`开始时，`refs/，否则`refs/notes/`前缀，形成Ref的全名。

--ignore-missing

不要认为请求从一个没有附加注释的对象上删除注释是一个错误。

--stdin

仅对 remove 和 copy 有效。参见相应的子命令。

-n
--dry-run

不要删除任何东西；只是报告其注释将被删除的对象名称。

-s <策略>
--strategy=<策略>

合并笔记时，使用给定的策略解决笔记冲突。以下策略是被认可的。"手动"（默认）、"我们的"、"他们的"、"联合 "和 cat_sort_uniq。 这个选项覆盖了 "notes.mergeStrategy "的配置设置。 关于每种笔记合并策略的更多信息，请看下面的 "笔记合并策略 "部分。

--commit

最终确定一个正在进行的`git notes merge`。当您解决了`git notes merge`存储在.git/NOTES_MERGE_WORKTREE中的冲突后，使用此选项。这将修正由`git notes merge`创建的部分合并提交（存储在.git/NOTES_MERGE_PARTIAL中），加入.git/NOTES_MERGE_WORKTREE中的注释。存储在 .git/NOTES_MERGE_REF 符号参考中的注释会被更新到结果提交中。

--abort

中止/重置正在进行的 "git笔记合并"，即有冲突的笔记合并。这只是删除了所有与笔记合并有关的文件。

-q
--quiet

合并笔记时，要安静地操作。

-v
--verbose

当合并笔记时，要更加详细。 当修剪注释时，报告所有被删除注释的对象名称。

讨论

提交注释是包含关于一个对象的额外信息（通常是补充提交信息的信息）的 blobs。 这些 blobs 取自注释参考。 一个注释参考通常是一个包含 “文件” 的分支，这些文件的路径是它们所描述的对象的名称，出于性能的考虑，还包括一些目录分隔符 [1]。

每一个笔记的变化都会在指定的笔记参考号上创建一个新的提交。 因此，你可以通过调用，例如，git log -p notes/commits，来检查笔记的历史。 目前，提交信息只记录了哪个操作触发了更新，而提交者的身份则根据通常的规则确定（见 git-commit[1]）。 这些细节在未来可能会发生变化。

也允许注释直接指向树状对象，在这种情况下，可以用`git log -p -g <refname>`读取注释的历史。

注释 合并策略

默认的笔记合并策略是 "手动"，它在一个用于解决笔记冲突的特殊工作区（.git/NOTES_MERGE_WORKTREE）中检查出冲突的笔记，并指示用户在该工作区中解决冲突。 完成后，用户可以用 "git notes merge --commit "最终完成合并，或者用 "git notes merge --abort "中止合并。

用户可以使用 -s/--strategy 选项或相应地配置 notes.mergeStrategy，从以下内容中选择一个自动合并策略：

"我们的 "自动解决冲突的注释，支持本地版本（即当前的注释参考）。

"他们的 "自动解决笔记冲突，有利于远程版本（即给定的笔记参考文献被合并到当前的笔记参考文献中）。

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

注意事项。
    测试者： 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] 文档中。下面的内容与那里的内容相同：

笔记.合并策略

在解决笔记冲突时，默认选择哪种合并策略。 必须是 manual、ours、theirs、union 或 cat_sort_uniq 之一。 默认为 manual。 关于每种策略的更多信息，请参见 git-notes[1] 的 "NOTES MERGE STRATEGIES" 部分。

这个设置可以通过向 git-notes[1] 传递 --strategy 选项来覆盖。

笔记.<名称>.合并策略

当进行笔记合并到 refs/notes/<name> 时，选择哪种合并策略。 这覆盖了更一般的 notes.mergeStrategy。 关于每个可用策略的更多信息，请参见 git-notes[1] 的 "NOTES MERGE STRATEGIES" 部分。

笔记.displayRef

除了由 core.notesRef 或 GIT_NOTES_REF 设置的默认值外，在使用 git log 系列命令显示提交信息时，还应从哪个 ref（如果使用 glob 或指定多次，则为哪些 ref）中读取注释。

该设置可由 GIT_NOTES_DISPLAY_REF 环境变量覆盖；其值必须是一个以冒号分隔的 ref 或 glob 列表。

对于不存在的 refs 将会发出警告，但是不匹配任何 refs 的 glob 会被默默地忽略。

该设置可通过 git-log[1] 系列命令的 --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

从哪个参考文献来操作笔记，而不是`refs/notes/commits`。 这覆盖了`core.notesRef’的设置。

GIT_NOTES_DISPLAY_REF

以冒号为界的参考文献或globs列表，表示除了默认的`core.notesRef`或`GIT_NOTES_REF`之外，在显示提交信息时要从哪些参考文献读取。 这取代了`notes.displayRef`的设置。

对于不存在的 refs 将会发出警告，但是不匹配任何 refs 的 glob 会被默默地忽略。

GIT_NOTES_REWRITE_MODE

在重写过程中复制注释时，如果目标提交已经有一个注释，该如何处理。 必须是`overwrite`, concatenate, cat_sort_uniq, 或 `ignore`之一。 这覆盖了`core.rewriteMode`的设置。

GIT_NOTES_REWRITE_REF

当重写提交时，要从原始提交中复制哪些注释到重写的提交中。 必须是一个以冒号分隔的 refs 或 globs 列表。

如果环境中没有设置，要复制的笔记列表取决于`notes.rewrite.<command>`和`notes.rewriteRef`设置。

GIT

属于 git[1] 文档

1. 允许的路径名有 bf/fe/30/…​/'680d5a…​ 的形式：一串由两个十六进制数字组成的目录名，后面是一个带有其余对象ID的文件名。