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 configuration in git-log(1).
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 notes.mergeStrategy
278 Which merge strategy to choose by default when resolving notes
279 conflicts. Must be one of manual, ours, theirs, union, or
280 cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES"
281 section above for more information on each strategy.
282 This setting can be overridden by passing the --strategy option.
284 notes.<name>.mergeStrategy
286 Which merge strategy to choose when doing a notes merge into
287 refs/notes/<name>. This overrides the more general
288 "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section
289 above for more information on each available strategy.
290 notes.displayRef
292 Which ref (or refs, if a glob or specified more than once), in
293 addition to the default set by core.notesRef or GIT_NOTES_REF, to
294 read notes from when showing commit messages with the git log
295 family of commands. This setting can be overridden on the command
296 line or by the GIT_NOTES_DISPLAY_REF environment variable. See git-
297 log(1).
298 notes.rewrite.<command>
300 When rewriting commits with <command> (currently amend or rebase),
301 if this variable is false, git will not copy notes from the
302 original to the rewritten commit. Defaults to true. See also
303 "notes.rewriteRef" below.
304 This setting can be overridden by the GIT_NOTES_REWRITE_REF
306 environment variable.
307 notes.rewriteMode
309 When copying notes during a rewrite, what to do if the target
310 commit already has a note. Must be one of overwrite, concatenate,
311 cat_sort_uniq, or ignore. Defaults to concatenate.
312 This setting can be overridden with the GIT_NOTES_REWRITE_MODE
314 environment variable.
315 notes.rewriteRef
317 When copying notes during a rewrite, specifies the (fully
318 qualified) ref whose notes should be copied. May be a glob, in
319 which case notes in all matching refs will be copied. You may also
320 specify this configuration several times.
321 Does not have a default value; you must configure this variable to
323 enable note rewriting.
324 Can be overridden with the GIT_NOTES_REWRITE_REF environment
326 variable.
327
329 GIT_NOTES_REF
330 Which ref to manipulate notes from, instead of refs/notes/commits.
331 This overrides the core.notesRef setting.
332 GIT_NOTES_DISPLAY_REF
334 Colon-delimited list of refs or globs indicating which refs, in
335 addition to the default from core.notesRef or GIT_NOTES_REF, to
336 read notes from when showing commit messages. This overrides the
337 notes.displayRef setting.
338 A warning will be issued for refs that do not exist, but a glob
340 that does not match any refs is silently ignored.
341 GIT_NOTES_REWRITE_MODE
343 When copying notes during a rewrite, what to do if the target
344 commit already has a note. Must be one of overwrite, concatenate,
345 cat_sort_uniq, or ignore. This overrides the core.rewriteMode
346 setting.
347 GIT_NOTES_REWRITE_REF
349 When rewriting commits, which notes to copy from the original to
350 the rewritten commit. Must be a colon-delimited list of refs or
351 globs.
352 If not set in the environment, the list of notes to copy depends on
354 the notes.rewrite.<command> and notes.rewriteRef settings.
355
357 Part of the git(1) suite
358
360 1. Permitted pathnames have the form bf/fe/30/.../680d5a...: a
361 sequence of directory names of two hexadecimal digits each followed
362 by a filename with the rest of the object ID.
363Git 2.36.1 2022-05-05 GIT-NOTES(1)