1GIT-NOTES(1)                      Git Manual                      GIT-NOTES(1)
2
3
4

NAME

6       git-notes - Add or inspect object notes
7

SYNOPSIS

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

DESCRIPTION

23       Adds, removes, or reads notes attached to objects, without touching the
24       objects themselves.
25
26       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
31       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
38       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
42       To change which notes are shown by git log, see the "notes.displayRef"
43       configuration in git-log(1).
44
45       See the "notes.rewrite.<command>" configuration for a way to carry
46       notes across commands that rewrite commits.
47

SUBCOMMANDS

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
55       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
63       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
70           In --stdin mode, take lines in the format
71
72               <from-object> SP <to-object> [ SP <rest> ] LF
73
74           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
79       append
80           Append to the notes of an existing object (defaults to HEAD).
81           Creates a new notes object if needed.
82
83       edit
84           Edit the notes for a given object (defaults to HEAD).
85
86       show
87           Show the notes for a given object (defaults to HEAD).
88
89       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
95           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
104       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
109       prune
110           Remove all notes for non-existing/unreachable objects.
111
112       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

OPTIONS

117       -f, --force
118           When adding notes to an object that already has notes, overwrite
119           the existing notes (instead of aborting).
120
121       -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
127       -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
133       -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
138       -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
142       --allow-empty
143           Allow an empty note object to be stored. The default behavior is to
144           automatically remove empty notes.
145
146       --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
153       --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
157       --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
162       -n, --dry-run
163           Do not remove anything; just report the object names whose notes
164           would be removed.
165
166       -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
174       --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
183       --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
188       -q, --quiet
189           When merging notes, operate quietly.
190
191       -v, --verbose
192           When merging notes, be more verbose. When pruning notes, report all
193           object names whose notes are removed.
194

DISCUSSION

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
202       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
209       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

NOTES MERGE STRATEGIES

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
221       Users may select an automated merge strategy from among the following
222       using either -s/--strategy option or configuring notes.mergeStrategy
223       accordingly:
224
225       "ours" automatically resolves conflicting notes in favor of the local
226       version (i.e. the current notes ref).
227
228       "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
232       "union" automatically resolves notes conflicts by concatenating the
233       local and remote versions.
234
235       "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

EXAMPLES

246       You can use notes to add annotations with information that was not
247       available at the time a commit was written.
248
249           $ 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
254           Notes:
255               Tested-by: Johannes Sixt <j6t@kdbg.org>
256
257       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
261           $ cc *.c
262           $ blob=$(git hash-object -w a.out)
263           $ git notes --ref=built add --allow-empty -C "$blob" HEAD
264
265       (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

CONFIGURATION

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
277       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
283           This setting can be overridden by passing the --strategy option.
284
285       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
291       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
299       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
305           This setting can be overridden by the GIT_NOTES_REWRITE_REF
306           environment variable.
307
308       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
313           This setting can be overridden with the GIT_NOTES_REWRITE_MODE
314           environment variable.
315
316       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
322           Does not have a default value; you must configure this variable to
323           enable note rewriting.
324
325           Can be overridden with the GIT_NOTES_REWRITE_REF environment
326           variable.
327

ENVIRONMENT

329       GIT_NOTES_REF
330           Which ref to manipulate notes from, instead of refs/notes/commits.
331           This overrides the core.notesRef setting.
332
333       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
339           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
342       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
348       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
353           If not set in the environment, the list of notes to copy depends on
354           the notes.rewrite.<command> and notes.rewriteRef settings.
355

GIT

357       Part of the git(1) suite
358

NOTES

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.
363
364
365
366
367Git 2.36.1                        2022-05-05                      GIT-NOTES(1)
Impressum