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] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
11 git notes copy [-f] ( --stdin | <from-object> [<to-object>] )
12 git notes append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
13 git notes edit [--allow-empty] [<object>]
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).
62 copy
64 Copy the notes for the first object onto the second object
65 (defaults to HEAD). Abort if the second object already has notes,
66 or if the first object has none (use -f to overwrite existing notes
67 to the second object). This subcommand is equivalent to: git notes
68 add [-f] -C $(git notes list <from-object>) <to-object>
69 In --stdin mode, take lines in the format
71 <from-object> SP <to-object> [ SP <rest> ] LF
73 on standard input, and copy the notes from each <from-object> to
75 its corresponding <to-object>. (The optional <rest> is ignored so
76 that the command can read the input given to the post-rewrite
77 hook.)
78 append
80 Append to the notes of an existing object (defaults to HEAD).
81 Creates a new notes object if needed.
82 edit
84 Edit the notes for a given object (defaults to HEAD).
85 show
87 Show the notes for a given object (defaults to HEAD).
88 merge
90 Merge the given notes ref into the current notes ref. This will try
91 to merge the changes made by the given notes ref (called "remote")
92 since the merge-base (if any) into the current notes ref (called
93 "local").
94 If conflicts arise and a strategy for automatically resolving
96 conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not
97 given, the "manual" resolver is used. This resolver checks out the
98 conflicting notes in a special worktree
99 (.git/NOTES_MERGE_WORKTREE), and instructs the user to manually
100 resolve the conflicts there. When done, the user can either
101 finalize the merge with git notes merge --commit, or abort the
102 merge with git notes merge --abort.
103 remove
105 Remove the notes for given objects (defaults to HEAD). When giving
106 zero or one object from the command line, this is equivalent to
107 specifying an empty note message to the edit subcommand.
108 prune
110 Remove all notes for non-existing/unreachable objects.
111 get-ref
113 Print the current notes ref. This provides an easy way to retrieve
114 the current notes ref (e.g. from scripts).
115
117 -f, --force
118 When adding notes to an object that already has notes, overwrite
119 the existing notes (instead of aborting).
120 -m <msg>, --message=<msg>
122 Use the given note message (instead of prompting). If multiple -m
123 options are given, their values are concatenated as separate
124 paragraphs. Lines starting with # and empty lines other than a
125 single line between paragraphs will be stripped out.
126 -F <file>, --file=<file>
128 Take the note message from the given file. Use - to read the note
129 message from the standard input. Lines starting with # and empty
130 lines other than a single line between paragraphs will be stripped
131 out.
132 -C <object>, --reuse-message=<object>
134 Take the given blob object (for example, another note) as the note
135 message. (Use git notes copy <object> instead to copy notes between
136 objects.)
137 -c <object>, --reedit-message=<object>
139 Like -C, but with -c the editor is invoked, so that the user can
140 further edit the note message.
141 --allow-empty
143 Allow an empty note object to be stored. The default behavior is to
144 automatically remove empty notes.
145 --ref <ref>
147 Manipulate the notes tree in <ref>. This overrides GIT_NOTES_REF
148 and the "core.notesRef" configuration. The ref specifies the full
149 refname when it begins with refs/notes/; when it begins with
150 notes/, refs/ and otherwise refs/notes/ is prefixed to form a full
151 name of the ref.
152 --ignore-missing
154 Do not consider it an error to request removing notes from an
155 object that does not have notes attached to it.
156 --stdin
158 Also read the object names to remove notes from the standard input
159 (there is no reason you cannot combine this with object names from
160 the command line).
161 -n, --dry-run
163 Do not remove anything; just report the object names whose notes
164 would be removed.
165 -s <strategy>, --strategy=<strategy>
167 When merging notes, resolve notes conflicts using the given
168 strategy. The following strategies are recognized: "manual"
169 (default), "ours", "theirs", "union" and "cat_sort_uniq". This
170 option overrides the "notes.mergeStrategy" configuration setting.
171 See the "NOTES MERGE STRATEGIES" section below for more information
172 on each notes merge strategy.
173 --commit
175 Finalize an in-progress git notes merge. Use this option when you
176 have resolved the conflicts that git notes merge stored in
177 .git/NOTES_MERGE_WORKTREE. This amends the partial merge commit
178 created by git notes merge (stored in .git/NOTES_MERGE_PARTIAL) by
179 adding the notes in .git/NOTES_MERGE_WORKTREE. The notes ref stored
180 in the .git/NOTES_MERGE_REF symref is updated to the resulting
181 commit.
182 --abort
184 Abort/reset an in-progress git notes merge, i.e. a notes merge with
185 conflicts. This simply removes all files related to the notes
186 merge.
187 -q, --quiet
189 When merging notes, operate quietly.
190 -v, --verbose
192 When merging notes, be more verbose. When pruning notes, report all
193 object names whose notes are removed.
194
196 Commit notes are blobs containing extra information about an object
197 (usually information to supplement a commit’s message). These blobs are
198 taken from notes refs. A notes ref is usually a branch which contains
199 "files" whose paths are the object names for the objects they describe,
200 with some directory separators included for performance reasons [1].
201 Every notes change creates a new commit at the specified notes ref. You
203 can therefore inspect the history of the notes by invoking, e.g., git
204 log -p notes/commits. Currently the commit message only records which
205 operation triggered the update, and the commit authorship is determined
206 according to the usual rules (see git-commit(1)). These details may
207 change in the future.
208 It is also permitted for a notes ref to point directly to a tree
210 object, in which case the history of the notes can be read with git log
211 -p -g <refname>.
212
214 The default notes merge strategy is "manual", which checks out
215 conflicting notes in a special work tree for resolving notes conflicts
216 (.git/NOTES_MERGE_WORKTREE), and instructs the user to resolve the
217 conflicts in that work tree. When done, the user can either finalize
218 the merge with git notes merge --commit, or abort the merge with git
219 notes merge --abort.
220 Users may select an automated merge strategy from among the following
222 using either -s/--strategy option or configuring notes.mergeStrategy
223 accordingly:
224 "ours" automatically resolves conflicting notes in favor of the local
226 version (i.e. the current notes ref).
227 "theirs" automatically resolves notes conflicts in favor of the remote
229 version (i.e. the given notes ref being merged into the current notes
230 ref).
231 "union" automatically resolves notes conflicts by concatenating the
233 local and remote versions.
234 "cat_sort_uniq" is similar to "union", but in addition to concatenating
236 the local and remote versions, this strategy also sorts the resulting
237 lines, and removes duplicate lines from the result. This is equivalent
238 to applying the "cat | sort | uniq" shell pipeline to the local and
239 remote versions. This strategy is useful if the notes follow a
240 line-based format where one wants to avoid duplicated lines in the
241 merge result. Note that if either the local or remote version contain
242 duplicate lines prior to the merge, these will also be removed by this
243 notes merge strategy.
244
246 You can use notes to add annotations with information that was not
247 available at the time a commit was written.
248 $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
250 $ git show -s 72a144e
251 [...]
252 Signed-off-by: Junio C Hamano <gitster@pobox.com>
253 Notes:
255 Tested-by: Johannes Sixt <j6t@kdbg.org>
256 In principle, a note is a regular Git blob, and any kind of
258 (non-)format is accepted. You can binary-safely create notes from
259 arbitrary files using git hash-object:
260 $ cc *.c
262 $ blob=$(git hash-object -w a.out)
263 $ git notes --ref=built add --allow-empty -C "$blob" HEAD
264 (You cannot simply use git notes --ref=built add -F a.out HEAD because
266 that is not binary-safe.) Of course, it doesn’t make much sense to
267 display non-text-format notes with git log, so if you use such notes,
268 you’ll probably need to write some special-purpose tools to do
269 something useful with them.
270
272 core.notesRef
273 Notes ref to read and manipulate instead of refs/notes/commits.
274 Must be an unabbreviated ref name. This setting can be overridden
275 through the environment and command line.
276 Everything above this line in this section isn’t included from the git-
278 config(1) documentation. The content that follows is the same as what’s
279 found there:
280 notes.mergeStrategy
282 Which merge strategy to choose by default when resolving notes
283 conflicts. Must be one of manual, ours, theirs, union, or
284 cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES"
285 section of git-notes(1) for more information on each strategy.
286 This setting can be overridden by passing the --strategy option to
288 git-notes(1).
289 notes.<name>.mergeStrategy
291 Which merge strategy to choose when doing a notes merge into
292 refs/notes/<name>. This overrides the more general
293 "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in
294 git-notes(1) for more information on the available strategies.
295 notes.displayRef
297 Which ref (or refs, if a glob or specified more than once), in
298 addition to the default set by core.notesRef or GIT_NOTES_REF, to
299 read notes from when showing commit messages with the git log
300 family of commands.
301 This setting can be overridden with the GIT_NOTES_DISPLAY_REF
303 environment variable, which must be a colon separated list of refs
304 or globs.
305 A warning will be issued for refs that do not exist, but a glob
307 that does not match any refs is silently ignored.
308 This setting can be disabled by the --no-notes option to the git
310 log family of commands, or by the --notes=<ref> option accepted by
311 those commands.
312 The effective value of "core.notesRef" (possibly overridden by
314 GIT_NOTES_REF) is also implicitly added to the list of refs to be
315 displayed.
316 notes.rewrite.<command>
318 When rewriting commits with <command> (currently amend or rebase),
319 if this variable is false, git will not copy notes from the
320 original to the rewritten commit. Defaults to true. See also
321 "notes.rewriteRef" below.
322 This setting can be overridden with the GIT_NOTES_REWRITE_REF
324 environment variable, which must be a colon separated list of refs
325 or globs.
326 notes.rewriteMode
328 When copying notes during a rewrite (see the
329 "notes.rewrite.<command>" option), determines what to do if the
330 target commit already has a note. Must be one of overwrite,
331 concatenate, cat_sort_uniq, or ignore. Defaults to concatenate.
332 This setting can be overridden with the GIT_NOTES_REWRITE_MODE
334 environment variable.
335 notes.rewriteRef
337 When copying notes during a rewrite, specifies the (fully
338 qualified) ref whose notes should be copied. May be a glob, in
339 which case notes in all matching refs will be copied. You may also
340 specify this configuration several times.
341 Does not have a default value; you must configure this variable to
343 enable note rewriting. Set it to refs/notes/commits to enable
344 rewriting for the default commit notes.
345 Can be overridden with the GIT_NOTES_REWRITE_REF environment
347 variable. See notes.rewrite.<command> above for a further
348 description of its format.
349
351 GIT_NOTES_REF
352 Which ref to manipulate notes from, instead of refs/notes/commits.
353 This overrides the core.notesRef setting.
354 GIT_NOTES_DISPLAY_REF
356 Colon-delimited list of refs or globs indicating which refs, in
357 addition to the default from core.notesRef or GIT_NOTES_REF, to
358 read notes from when showing commit messages. This overrides the
359 notes.displayRef setting.
360 A warning will be issued for refs that do not exist, but a glob
362 that does not match any refs is silently ignored.
363 GIT_NOTES_REWRITE_MODE
365 When copying notes during a rewrite, what to do if the target
366 commit already has a note. Must be one of overwrite, concatenate,
367 cat_sort_uniq, or ignore. This overrides the core.rewriteMode
368 setting.
369 GIT_NOTES_REWRITE_REF
371 When rewriting commits, which notes to copy from the original to
372 the rewritten commit. Must be a colon-delimited list of refs or
373 globs.
374 If not set in the environment, the list of notes to copy depends on
376 the notes.rewrite.<command> and notes.rewriteRef settings.
377
379 Part of the git(1) suite
380
382 1. Permitted pathnames have the form bf/fe/30/.../680d5a...: a
383 sequence of directory names of two hexadecimal digits each followed
384 by a filename with the rest of the object ID.
385Git 2.39.1 2023-01-13 GIT-NOTES(1)