设置和配置
获取和创建项目
基本快照
分支与合并
共享和更新项目
检查和比较
打补丁
调试
电子邮件
外部系统
服务器管理
指南
管理
底层命令
- 2.50.1 无更改
-
2.50.0
2025-06-16
- 2.49.1 无更改
-
2.49.0
2025-03-14
- 2.48.1 → 2.48.2 无更改
-
2.48.0
2025-01-10
- 2.44.1 → 2.47.3 无更改
-
2.44.0
2024-02-23
- 2.43.1 → 2.43.7 无更改
-
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
钩子的输入。)--stdin
不能与命令行中给定的对象名称结合使用。 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
子命令指定空备注消息。在
--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
配置设置。有关每种备注合并策略的更多信息,请参阅下面的“备注合并策略”部分。 --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
-
合并备注时,更详细地操作。修剪备注时,报告所有被移除备注的对象名称。
讨论
提交备注是包含对象额外信息(通常是补充提交消息的信息)的 Git 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] 的“备注合并策略”部分。此设置可以通过向 git-notes[1] 传递
--strategy
选项来覆盖。 notes.
<name>.mergeStrategy
-
当将备注合并到
refs/notes/
<name> 时选择的合并策略。这会覆盖更通用的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=
<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
的默认值之外,在显示提交消息时从哪些引用读取备注。这会覆盖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
设置。