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       discussion in the section called “CONFIGURATION”.
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       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
281       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
287           This setting can be overridden by passing the --strategy option to
288           git-notes(1).
289
290       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
296       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
302           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
306           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
309           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
313           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
317       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
323           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
327       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
333           This setting can be overridden with the GIT_NOTES_REWRITE_MODE
334           environment variable.
335
336       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
342           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
346           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

ENVIRONMENT

351       GIT_NOTES_REF
352           Which ref to manipulate notes from, instead of refs/notes/commits.
353           This overrides the core.notesRef setting.
354
355       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
361           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
364       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
370       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
375           If not set in the environment, the list of notes to copy depends on
376           the notes.rewrite.<command> and notes.rewriteRef settings.
377

GIT

379       Part of the git(1) suite
380

NOTES

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.
385
386
387
388
389Git 2.39.1                        2023-01-13                      GIT-NOTES(1)
Impressum