设置和配置
获取和创建项目
基本快照
分支和合并
共享和更新项目
检查和比较
修补
调试
电子邮件
外部系统
服务器管理员
指南
管理
底层命令
- 2.44.1 → 2.47.0 无更改
-
2.44.0
02/23/24
- 2.43.1 → 2.43.5 无更改
-
2.43.0
11/20/23
- 2.42.1 → 2.42.3 无更改
-
2.42.0
08/21/23
- 2.38.1 → 2.41.2 无更改
-
2.38.0
10/02/22
- 2.29.1 → 2.37.7 无更改
-
2.29.0
10/19/20
- 2.25.1 → 2.28.1 无更改
-
2.25.0
01/13/20
- 2.22.1 → 2.24.4 无更改
-
2.22.0
06/07/19
- 2.19.1 → 2.21.4 无更改
-
2.19.0
09/10/18
- 2.17.0 → 2.18.5 无更改
-
2.16.6
12/06/19
- 2.15.4 无更改
-
2.14.6
12/06/19
- 2.10.5 → 2.13.7 无更改
-
2.9.5
07/30/17
-
2.8.6
07/30/17
- 2.7.6 无更改
-
2.6.7
05/05/17
- 2.4.12 → 2.5.6 无更改
-
2.3.10
09/28/15
- 2.1.4 → 2.2.3 无更改
-
2.0.5
12/17/14
概要
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>):”（或“Notes:” 用于refs/notes/commits）之后）缩进，类似于消息。
使用git format-patch准备的补丁也可以使用--notes选项添加注释。此类注释作为补丁注释添加到三条破折号分隔线之后。
要更改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钩子的输入。） - 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>
- --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符号引用中的笔记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 <[email protected]>' 72a144e2 $ git show -s 72a144e [...] Signed-off-by: Junio C Hamano <[email protected]> Notes: Tested-by: Johannes Sixt <[email protected]>
原则上，笔记是一个常规的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]的"NOTES MERGE STRATEGIES"部分。此设置可以通过将
--strategy选项传递给git-notes[1]来覆盖。 - notes.<name>.mergeStrategy
-
将笔记合并到refs/notes/<name>时选择哪个合并策略。这将覆盖更通用的"notes.mergeStrategy"。有关可用策略的更多信息，请参阅git-notes[1]中的"NOTES MERGE STRATEGIES"部分。
- notes.displayRef
-
除了
core.notesRef或GIT_NOTES_REF设置的默认值之外，哪个ref（或refs，如果为glob或指定多次），在使用git log系列命令显示提交消息时从中读取笔记。此设置可以通过
GIT_NOTES_DISPLAY_REF环境变量覆盖，该变量必须是ref或glob的冒号分隔列表。将针对不存在的ref发出警告，但与任何ref都不匹配的glob将静默忽略。
此设置可以通过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发出警告，但与任何ref都不匹配的glob将静默忽略。
-
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]套件的一部分
