简体中文 ▾ 主题 ▾ 最新版本 ▾ 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 剩余部分的파일명。