1GIT-NOTES(1) Git Manual GIT-NOTES(1)
2
6 git-notes - Add or inspect object notes
7
9 git notes [list [<object>]]
10 git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
11 git notes copy [-f] ( --stdin | <from-object> [<to-object>] )
12 git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
13 git notes edit [--allow-empty] [<object>] [--[no-]stripspace]
14 git notes show [<object>]
15 git notes merge [-v | -q] [-s <strategy> ] <notes-ref>
16 git notes merge --commit [-v | -q]
17 git notes merge --abort [-v | -q]
18 git notes remove [--ignore-missing] [--stdin] [<object>...]
19 git notes prune [-n] [-v]
20 git notes get-ref
21
23 Adds, removes, or reads notes attached to objects, without touching the
24 objects themselves.
25 By default, notes are saved to and read from refs/notes/commits, but
27 this default can be overridden. See the OPTIONS, CONFIGURATION, and
28 ENVIRONMENT sections below. If this ref does not exist, it will be
29 quietly created when it is first needed to store a note.
30 A typical use of notes is to supplement a commit message without
32 changing the commit itself. Notes can be shown by git log along with
33 the original commit message. To distinguish these notes from the
34 message stored in the commit object, the notes are indented like the
35 message, after an unindented line saying "Notes (<refname>):" (or
36 "Notes:" for refs/notes/commits).
37 Notes can also be added to patches prepared with git format-patch by
39 using the --notes option. Such notes are added as a patch commentary
40 after a three dash separator line.
41 To change which notes are shown by git log, see the "notes.displayRef"
43 discussion in the section called “CONFIGURATION”.
44 See the "notes.rewrite.<command>" configuration for a way to carry
46 notes across commands that rewrite commits.
47
49 list
50 List the notes object for a given object. If no object is given,
51 show a list of all note objects and the objects they annotate (in
52 the format "<note object> <annotated object>"). This is the default
53 subcommand if no subcommand is given.
54 add
56 Add notes for a given object (defaults to HEAD). Abort if the
57 object already has notes (use -f to overwrite existing notes).
58 However, if you’re using add interactively (using an editor to
59 supply the notes contents), then - instead of aborting - the
60 existing notes will be opened in the editor (like the edit
61 subcommand). If you specify multiple -m and -F, a blank line will
62 be inserted between the messages. Use the --separator option to
63 insert other delimiters.
64 copy
66 Copy the notes for the first object onto the second object
67 (defaults to HEAD). Abort if the second object already has notes,
68 or if the first object has none (use -f to overwrite existing notes
69 to the second object). This subcommand is equivalent to: git notes
70 add [-f] -C $(git notes list <from-object>) <to-object>
71 In --stdin mode, take lines in the format
73 <from-object> SP <to-object> [ SP <rest> ] LF
75 on standard input, and copy the notes from each <from-object> to
77 its corresponding <to-object>. (The optional <rest> is ignored so
78 that the command can read the input given to the post-rewrite
79 hook.)
80 append
82 Append new message(s) given by -m or -F options to an existing
83 note, or add them as a new note if one does not exist, for the
84 object (defaults to HEAD). When appending to an existing note, a
85 blank line is added before each new message as an inter-paragraph
86 separator. The separator can be customized with the --separator
87 option.
88 edit
90 Edit the notes for a given object (defaults to HEAD).
91 show
93 Show the notes for a given object (defaults to HEAD).
94 merge
96 Merge the given notes ref into the current notes ref. This will try
97 to merge the changes made by the given notes ref (called "remote")
98 since the merge-base (if any) into the current notes ref (called
99 "local").
100 If conflicts arise and a strategy for automatically resolving
102 conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not
103 given, the "manual" resolver is used. This resolver checks out the
104 conflicting notes in a special worktree
105 (.git/NOTES_MERGE_WORKTREE), and instructs the user to manually
106 resolve the conflicts there. When done, the user can either
107 finalize the merge with git notes merge --commit, or abort the
108 merge with git notes merge --abort.
109 remove
111 Remove the notes for given objects (defaults to HEAD). When giving
112 zero or one object from the command line, this is equivalent to
113 specifying an empty note message to the edit subcommand.
114 prune
116 Remove all notes for non-existing/unreachable objects.
117 get-ref
119 Print the current notes ref. This provides an easy way to retrieve
120 the current notes ref (e.g. from scripts).
121
123 -f, --force
124 When adding notes to an object that already has notes, overwrite
125 the existing notes (instead of aborting).
126 -m <msg>, --message=<msg>
128 Use the given note message (instead of prompting). If multiple -m
129 options are given, their values are concatenated as separate
130 paragraphs. Lines starting with # and empty lines other than a
131 single line between paragraphs will be stripped out. If you wish to
132 keep them verbatim, use --no-stripspace.
133 -F <file>, --file=<file>
135 Take the note message from the given file. Use - to read the note
136 message from the standard input. Lines starting with # and empty
137 lines other than a single line between paragraphs will be stripped
138 out. If you wish to keep them verbatim, use --no-stripspace.
139 -C <object>, --reuse-message=<object>
141 Take the given blob object (for example, another note) as the note
142 message. (Use git notes copy <object> instead to copy notes between
143 objects.). By default, message will be copied verbatim, but if you
144 wish to strip out the lines starting with # and empty lines other
145 than a single line between paragraphs, use with`--stripspace`
146 option.
147 -c <object>, --reedit-message=<object>
149 Like -C, but with -c the editor is invoked, so that the user can
150 further edit the note message.
151 --allow-empty
153 Allow an empty note object to be stored. The default behavior is to
154 automatically remove empty notes.
155 --[no-]separator, --separator=<paragraph-break>
157 Specify a string used as a custom inter-paragraph separator (a
158 newline is added at the end as needed). If --no-separator, no
159 separators will be added between paragraphs. Defaults to a blank
160 line.
161 --[no-]stripspace
163 Strip leading and trailing whitespace from the note message. Also
164 strip out empty lines other than a single line between paragraphs.
165 Lines starting with # will be stripped out in non-editor cases like
166 -m, -F and -C, but not in editor case like git notes edit, -c, etc.
167 --ref <ref>
169 Manipulate the notes tree in <ref>. This overrides GIT_NOTES_REF
170 and the "core.notesRef" configuration. The ref specifies the full
171 refname when it begins with refs/notes/; when it begins with
172 notes/, refs/ and otherwise refs/notes/ is prefixed to form a full
173 name of the ref.
174 --ignore-missing
176 Do not consider it an error to request removing notes from an
177 object that does not have notes attached to it.
178 --stdin
180 Also read the object names to remove notes from the standard input
181 (there is no reason you cannot combine this with object names from
182 the command line).
183 -n, --dry-run
185 Do not remove anything; just report the object names whose notes
186 would be removed.
187 -s <strategy>, --strategy=<strategy>
189 When merging notes, resolve notes conflicts using the given
190 strategy. The following strategies are recognized: "manual"
191 (default), "ours", "theirs", "union" and "cat_sort_uniq". This
192 option overrides the "notes.mergeStrategy" configuration setting.
193 See the "NOTES MERGE STRATEGIES" section below for more information
194 on each notes merge strategy.
195 --commit
197 Finalize an in-progress git notes merge. Use this option when you
198 have resolved the conflicts that git notes merge stored in
199 .git/NOTES_MERGE_WORKTREE. This amends the partial merge commit
200 created by git notes merge (stored in .git/NOTES_MERGE_PARTIAL) by
201 adding the notes in .git/NOTES_MERGE_WORKTREE. The notes ref stored
202 in the .git/NOTES_MERGE_REF symref is updated to the resulting
203 commit.
204 --abort
206 Abort/reset an in-progress git notes merge, i.e. a notes merge with
207 conflicts. This simply removes all files related to the notes
208 merge.
209 -q, --quiet
211 When merging notes, operate quietly.
212 -v, --verbose
214 When merging notes, be more verbose. When pruning notes, report all
215 object names whose notes are removed.
216
218 Commit notes are blobs containing extra information about an object
219 (usually information to supplement a commit’s message). These blobs are
220 taken from notes refs. A notes ref is usually a branch which contains
221 "files" whose paths are the object names for the objects they describe,
222 with some directory separators included for performance reasons [1].
223 Every notes change creates a new commit at the specified notes ref. You
225 can therefore inspect the history of the notes by invoking, e.g., git
226 log -p notes/commits. Currently the commit message only records which
227 operation triggered the update, and the commit authorship is determined
228 according to the usual rules (see git-commit(1)). These details may
229 change in the future.
230 It is also permitted for a notes ref to point directly to a tree
232 object, in which case the history of the notes can be read with git log
233 -p -g <refname>.
234
236 The default notes merge strategy is "manual", which checks out
237 conflicting notes in a special work tree for resolving notes conflicts
238 (.git/NOTES_MERGE_WORKTREE), and instructs the user to resolve the
239 conflicts in that work tree. When done, the user can either finalize
240 the merge with git notes merge --commit, or abort the merge with git
241 notes merge --abort.
242 Users may select an automated merge strategy from among the following
244 using either -s/--strategy option or configuring notes.mergeStrategy
245 accordingly:
246 "ours" automatically resolves conflicting notes in favor of the local
248 version (i.e. the current notes ref).
249 "theirs" automatically resolves notes conflicts in favor of the remote
251 version (i.e. the given notes ref being merged into the current notes
252 ref).
253 "union" automatically resolves notes conflicts by concatenating the
255 local and remote versions.
256 "cat_sort_uniq" is similar to "union", but in addition to concatenating
258 the local and remote versions, this strategy also sorts the resulting
259 lines, and removes duplicate lines from the result. This is equivalent
260 to applying the "cat | sort | uniq" shell pipeline to the local and
261 remote versions. This strategy is useful if the notes follow a
262 line-based format where one wants to avoid duplicated lines in the
263 merge result. Note that if either the local or remote version contain
264 duplicate lines prior to the merge, these will also be removed by this
265 notes merge strategy.
266
268 You can use notes to add annotations with information that was not
269 available at the time a commit was written.
270 $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
272 $ git show -s 72a144e
273 [...]
274 Signed-off-by: Junio C Hamano <gitster@pobox.com>
275 Notes:
277 Tested-by: Johannes Sixt <j6t@kdbg.org>
278 In principle, a note is a regular Git blob, and any kind of
280 (non-)format is accepted. You can binary-safely create notes from
281 arbitrary files using git hash-object:
282 $ cc *.c
284 $ blob=$(git hash-object -w a.out)
285 $ git notes --ref=built add --allow-empty -C "$blob" HEAD
286 (You cannot simply use git notes --ref=built add -F a.out HEAD because
288 that is not binary-safe.) Of course, it doesn’t make much sense to
289 display non-text-format notes with git log, so if you use such notes,
290 you’ll probably need to write some special-purpose tools to do
291 something useful with them.
292
294 core.notesRef
295 Notes ref to read and manipulate instead of refs/notes/commits.
296 Must be an unabbreviated ref name. This setting can be overridden
297 through the environment and command line.
298 Everything above this line in this section isn’t included from the git-
300 config(1) documentation. The content that follows is the same as what’s
301 found there:
302 notes.mergeStrategy
304 Which merge strategy to choose by default when resolving notes
305 conflicts. Must be one of manual, ours, theirs, union, or
306 cat_sort_uniq. Defaults to manual. See the "NOTES MERGE STRATEGIES"
307 section of git-notes(1) for more information on each strategy.
308 This setting can be overridden by passing the --strategy option to
310 git-notes(1).
311 notes.<name>.mergeStrategy
313 Which merge strategy to choose when doing a notes merge into
314 refs/notes/<name>. This overrides the more general
315 "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in
316 git-notes(1) for more information on the available strategies.
317 notes.displayRef
319 Which ref (or refs, if a glob or specified more than once), in
320 addition to the default set by core.notesRef or GIT_NOTES_REF, to
321 read notes from when showing commit messages with the git log
322 family of commands.
323 This setting can be overridden with the GIT_NOTES_DISPLAY_REF
325 environment variable, which must be a colon separated list of refs
326 or globs.
327 A warning will be issued for refs that do not exist, but a glob
329 that does not match any refs is silently ignored.
330 This setting can be disabled by the --no-notes option to the git
332 log family of commands, or by the --notes=<ref> option accepted by
333 those commands.
334 The effective value of "core.notesRef" (possibly overridden by
336 GIT_NOTES_REF) is also implicitly added to the list of refs to be
337 displayed.
338 notes.rewrite.<command>
340 When rewriting commits with <command> (currently amend or rebase),
341 if this variable is false, git will not copy notes from the
342 original to the rewritten commit. Defaults to true. See also
343 "notes.rewriteRef" below.
344 This setting can be overridden with the GIT_NOTES_REWRITE_REF
346 environment variable, which must be a colon separated list of refs
347 or globs.
348 notes.rewriteMode
350 When copying notes during a rewrite (see the
351 "notes.rewrite.<command>" option), determines what to do if the
352 target commit already has a note. Must be one of overwrite,
353 concatenate, cat_sort_uniq, or ignore. Defaults to concatenate.
354 This setting can be overridden with the GIT_NOTES_REWRITE_MODE
356 environment variable.
357 notes.rewriteRef
359 When copying notes during a rewrite, specifies the (fully
360 qualified) ref whose notes should be copied. May be a glob, in
361 which case notes in all matching refs will be copied. You may also
362 specify this configuration several times.
363 Does not have a default value; you must configure this variable to
365 enable note rewriting. Set it to refs/notes/commits to enable
366 rewriting for the default commit notes.
367 Can be overridden with the GIT_NOTES_REWRITE_REF environment
369 variable. See notes.rewrite.<command> above for a further
370 description of its format.
371
373 GIT_NOTES_REF
374 Which ref to manipulate notes from, instead of refs/notes/commits.
375 This overrides the core.notesRef setting.
376 GIT_NOTES_DISPLAY_REF
378 Colon-delimited list of refs or globs indicating which refs, in
379 addition to the default from core.notesRef or GIT_NOTES_REF, to
380 read notes from when showing commit messages. This overrides the
381 notes.displayRef setting.
382 A warning will be issued for refs that do not exist, but a glob
384 that does not match any refs is silently ignored.
385 GIT_NOTES_REWRITE_MODE
387 When copying notes during a rewrite, what to do if the target
388 commit already has a note. Must be one of overwrite, concatenate,
389 cat_sort_uniq, or ignore. This overrides the core.rewriteMode
390 setting.
391 GIT_NOTES_REWRITE_REF
393 When rewriting commits, which notes to copy from the original to
394 the rewritten commit. Must be a colon-delimited list of refs or
395 globs.
396 If not set in the environment, the list of notes to copy depends on
398 the notes.rewrite.<command> and notes.rewriteRef settings.
399
401 Part of the git(1) suite
402
404 1. Permitted pathnames have the form bf/fe/30/.../680d5a...: a
405 sequence of directory names of two hexadecimal digits each followed
406 by a filename with the rest of the object ID.
407Git 2.43.0 11/20/2023 GIT-NOTES(1)