设置和配置
获取和创建项目
基本快照
分支和合并
共享和更新项目
检查和比较
打补丁
调试
电子邮件
外部系统
服务器管理
指南
管理
底层命令
-
2.49.0
2025-03-14
- 2.48.1 没有更改
-
2.48.0
2025-01-10
- 2.44.1 → 2.47.2 没有更改
-
2.44.0
2024-02-23
- 2.43.1 → 2.43.6 没有更改
-
2.43.0
2023-11-20
- 2.42.1 → 2.42.4 没有更改
-
2.42.0
2023-08-21
- 2.38.1 → 2.41.3 没有更改
-
2.38.0
2022-10-02
- 2.29.1 → 2.37.7 没有更改
-
2.29.0
2020-10-19
- 2.25.1 → 2.28.1 没有更改
-
2.25.0
2020-01-13
- 2.22.1 → 2.24.4 没有更改
-
2.22.0
2019-06-07
- 2.19.1 → 2.21.4 没有更改
-
2.19.0
2018-09-10
- 2.17.0 → 2.18.5 没有更改
-
2.16.6
2019-12-06
- 2.15.4 没有更改
-
2.14.6
2019-12-06
- 2.10.5 → 2.13.7 没有更改
-
2.9.5
2017-07-30
-
2.8.6
2017-07-30
- 2.7.6 没有更改
-
2.6.7
2017-05-05
- 2.4.12 → 2.5.6 没有更改
-
2.3.10
2015-09-28
- 2.1.4 → 2.2.3 没有更改
-
2.0.5
2014-12-17
概要
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 以及从中读取，但是此默认值可以被覆盖。请参见下面的 OPTIONS、CONFIGURATION 和 ENVIRONMENT 章节。如果此引用不存在，它会在首次需要存储备注时被静默创建。
备注的典型用途是补充提交消息，而不更改提交本身。备注可以由 git log 与原始提交消息一起显示。为了将这些备注与存储在提交对象中的消息区分开来，备注会像消息一样缩进，并在未缩进的行说 "Notes (<refname>):"（对于 refs/notes/commits，则是 "Notes:"）之后。
备注还可以使用 --notes 选项添加到使用 git format-patch 准备的补丁中。此类备注会作为补丁注释添加在三个破折号分隔线之后。
要更改 git log 显示哪些备注，请参见 CONFIGURATION 中的 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钩子的输入。） -
append -
将由
-m或-F选项给出的新消息追加到现有备注，如果该对象不存在，则将其添加为新备注（默认为HEAD）。当追加到现有备注时，每个新消息之前都会添加一个空行作为段落间分隔符。可以使用--separator选项自定义分隔符。使用-e以交互方式（使用编辑器）编辑由-m和-F选项给出的要追加的备注，然后再追加备注。 -
edit -
编辑给定对象的备注（默认为
HEAD）。 -
show -
显示给定对象的备注（默认为
HEAD）。 -
merge -
将给定的备注引用合并到当前备注引用中。这将尝试将给定的备注引用（称为“远程”）自合并基础（如果有）以来所做的更改合并到当前备注引用（称为“本地”）。
如果出现冲突，并且没有给出自动解决冲突备注的策略（请参见“备注合并策略”章节），则使用
manual解析器。此解析器会在一个特殊的工作区 (.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 <对象> -
--reuse-message=<对象> -
将给定的 blob 对象（例如，另一个备注）作为备注消息。（使用
git notes copy <对象>代替在对象之间复制备注。）。默认情况下，消息将被原样复制，但如果您希望删除以#开头的行和除段落间单个空行外的空行，请使用--stripspace选项。 -
-c <对象> -
--reedit-message=<对象> -
与
-C类似，但使用-c会调用编辑器，以便用户可以进一步编辑备注消息。 -
--allow-empty -
允许存储空的备注对象。默认行为是自动删除空备注。
-
--[no-]separator -
--separator=<段落分隔符> -
指定一个字符串用作自定义的段落间分隔符（必要时在末尾添加换行符）。如果
--no-separator，则段落之间不会添加分隔符。默认为空行。 -
--[no-]stripspace -
删除备注消息开头和结尾的空白。也删除除段落间单个空行外的空行。以
#开头的行将在非编辑器情况下（如-m、-F和-C）被删除，但在编辑器情况下（如git notes edit、-c等）不会被删除。 -
--ref <引用> -
在 <引用> 中操作备注树。这将覆盖
GIT_NOTES_REF和core.notesRef配置。该引用指定了完整的引用名，当它以refs/notes/开头时；当它以notes/开头时，refs/；否则refs/notes/将作为前缀以形成引用的完整名称。 -
--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符号引用中的备注引用将更新为结果提交。 -
--abort -
中止/重置正在进行的
git notes merge，即具有冲突的备注合并。这只是删除与备注合并相关的所有文件。 -
-q -
--quiet -
合并备注时，以静默方式操作。
-
-v -
--verbose -
合并备注时，更详细。修剪备注时，报告所有备注被删除的对象名称。
讨论
提交备注是包含有关对象的额外信息的 blob（通常是补充提交消息的信息）。这些 blob 取自备注引用。备注引用通常是一个分支，其中包含“文件”，其路径是它们描述的对象的对象名称，其中包含一些目录分隔符以提高性能 [1]。
每个备注更改都会在指定的备注引用处创建一个新的提交。因此，您可以通过调用（例如）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 显示非文本格式的备注没有多大意义，因此如果您使用此类备注，您可能需要编写一些专用工具来对它们执行一些有用的操作。
配置
本节中此行之上的所有内容均未包含在 git-config[1] 文档中。以下内容与在那里找到的内容相同
-
notes.mergeStrategy -
解决备注冲突时默认选择的合并策略。必须是
manual、ours、theirs、union或cat_sort_uniq之一。默认为manual。有关每个策略的更多信息，请参见 git-notes[1] 的“备注合并策略”部分。可以通过将
--strategy选项传递给 git-notes[1] 来覆盖此设置。 -
notes.<名称>.mergeStrategy -
在进行备注合并到
refs/notes/<名称>时选择的合并策略。这将覆盖更通用的notes.mergeStrategy。有关可用策略的更多信息，请参见 git-notes[1] 中的“备注合并策略”部分。 -
notes.displayRef -
除了
core.notesRef或GIT_NOTES_REF设置的默认值之外，当使用git log系列命令显示提交消息时，从中读取备注的引用（或引用，如果是一个 glob 或多次指定）。可以使用
GIT_NOTES_DISPLAY_REF环境变量覆盖此设置，该变量必须是以冒号分隔的引用或 glob 列表。将为不存在的引用发出警告，但会以静默方式忽略与任何引用都不匹配的 glob。
可以通过 git-log[1] 系列命令的
--no-notes选项或这些命令接受的--notes=<引用>选项来禁用此设置。core.notesRef的有效值（可能被GIT_NOTES_REF覆盖）也会隐式添加到要显示的引用列表中。 -
notes.rewrite.<命令> -
在使用 <命令>（当前为
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 -
冒号分隔的引用或全局模式列表，指示在显示提交消息时，除了来自
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] 套件的一部分
