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] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
11 git notes copy [-f] ( --stdin | <from-object> <to-object> )
12 git notes append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
13 git notes edit [<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 [<object>]
19 git notes prune [-n | -v]
20 git notes get-ref
21
24 Adds, removes, or reads notes attached to objects, without touching the
25 objects themselves.
26 By default, notes are saved to and read from refs/notes/commits, but
28 this default can be overridden. See the OPTIONS, CONFIGURATION, and
29 ENVIRONMENT sections below. If this ref does not exist, it will be
30 quietly created when it is first needed to store a note.
31 A typical use of notes is to supplement a commit message without
33 changing the commit itself. Notes can be shown by git log along with
34 the original commit message. To distinguish these notes from the
35 message stored in the commit object, the notes are indented like the
36 message, after an unindented line saying "Notes (<refname>):" (or
37 "Notes:" for refs/notes/commits).
38 To change which notes are shown by git log, see the "notes.displayRef"
40 configuration in git-log(1).
41 See the "notes.rewrite.<command>" configuration for a way to carry
43 notes across commands that rewrite commits.
44
46 list
47 List the notes object for a given object. If no object is given,
48 show a list of all note objects and the objects they annotate (in
49 the format "<note object> <annotated object>"). This is the default
50 subcommand if no subcommand is given.
51 add
53 Add notes for a given object (defaults to HEAD). Abort if the
54 object already has notes (use -f to overwrite an existing note).
55 copy
57 Copy the notes for the first object onto the second object. Abort
58 if the second object already has notes, or if the first object has
59 none (use -f to overwrite existing notes to the second object).
60 This subcommand is equivalent to: git notes add [-f] -C $(git notes
61 list <from-object>) <to-object>
62 In --stdin mode, take lines in the format
64 <from-object> SP <to-object> [ SP <rest> ] LF
66 on standard input, and copy the notes from each <from-object> to
68 its corresponding <to-object>. (The optional <rest> is ignored so
69 that the command can read the input given to the post-rewrite
70 hook.)
71 append
73 Append to the notes of an existing object (defaults to HEAD).
74 Creates a new notes object if needed.
75 edit
77 Edit the notes for a given object (defaults to HEAD).
78 show
80 Show the notes for a given object (defaults to HEAD).
81 merge
83 Merge the given notes ref into the current notes ref. This will try
84 to merge the changes made by the given notes ref (called "remote")
85 since the merge-base (if any) into the current notes ref (called
86 "local").
87 If conflicts arise and a strategy for automatically resolving
89 conflicting notes (see the -s/--strategy option) is not given, the
90 "manual" resolver is used. This resolver checks out the conflicting
91 notes in a special worktree (.git/NOTES_MERGE_WORKTREE), and
92 instructs the user to manually resolve the conflicts there. When
93 done, the user can either finalize the merge with git notes merge
94 --commit, or abort the merge with git notes merge --abort.
95 remove
97 Remove the notes for a given object (defaults to HEAD). This is
98 equivalent to specifying an empty note message to the edit
99 subcommand.
100 prune
102 Remove all notes for non-existing/unreachable objects.
103 get-ref
105 Print the current notes ref. This provides an easy way to retrieve
106 the current notes ref (e.g. from scripts).
107
109 -f, --force
110 When adding notes to an object that already has notes, overwrite
111 the existing notes (instead of aborting).
112 -m <msg>, --message=<msg>
114 Use the given note message (instead of prompting). If multiple -m
115 options are given, their values are concatenated as separate
116 paragraphs. Lines starting with # and empty lines other than a
117 single line between paragraphs will be stripped out.
118 -F <file>, --file=<file>
120 Take the note message from the given file. Use - to read the note
121 message from the standard input. Lines starting with # and empty
122 lines other than a single line between paragraphs will be stripped
123 out.
124 -C <object>, --reuse-message=<object>
126 Take the note message from the given blob object (for example,
127 another note).
128 -c <object>, --reedit-message=<object>
130 Like -C, but with -c the editor is invoked, so that the user can
131 further edit the note message.
132 --ref <ref>
134 Manipulate the notes tree in <ref>. This overrides GIT_NOTES_REF
135 and the "core.notesRef" configuration. The ref is taken to be in
136 refs/notes/ if it is not qualified.
137 -n, --dry-run
139 Do not remove anything; just report the object names whose notes
140 would be removed.
141 -s <strategy>, --strategy=<strategy>
143 When merging notes, resolve notes conflicts using the given
144 strategy. The following strategies are recognized: "manual"
145 (default), "ours", "theirs", "union" and "cat_sort_uniq". See the
146 "NOTES MERGE STRATEGIES" section below for more information on each
147 notes merge strategy.
148 --commit
150 Finalize an in-progress git notes merge. Use this option when you
151 have resolved the conflicts that git notes merge stored in
152 .git/NOTES_MERGE_WORKTREE. This amends the partial merge commit
153 created by git notes merge (stored in .git/NOTES_MERGE_PARTIAL) by
154 adding the notes in .git/NOTES_MERGE_WORKTREE. The notes ref stored
155 in the .git/NOTES_MERGE_REF symref is updated to the resulting
156 commit.
157 --abort
159 Abort/reset a in-progress git notes merge, i.e. a notes merge with
160 conflicts. This simply removes all files related to the notes
161 merge.
162 -q, --quiet
164 When merging notes, operate quietly.
165 -v, --verbose
167 When merging notes, be more verbose. When pruning notes, report all
168 object names whose notes are removed.
169
171 Commit notes are blobs containing extra information about an object
172 (usually information to supplement a commit’s message). These blobs are
173 taken from notes refs. A notes ref is usually a branch which contains
174 "files" whose paths are the object names for the objects they describe,
175 with some directory separators included for performance reasons [1].
176 Every notes change creates a new commit at the specified notes ref. You
178 can therefore inspect the history of the notes by invoking, e.g., git
179 log -p notes/commits. Currently the commit message only records which
180 operation triggered the update, and the commit authorship is determined
181 according to the usual rules (see git-commit(1)). These details may
182 change in the future.
183 It is also permitted for a notes ref to point directly to a tree
185 object, in which case the history of the notes can be read with git log
186 -p -g <refname>.
187
189 The default notes merge strategy is "manual", which checks out
190 conflicting notes in a special work tree for resolving notes conflicts
191 (.git/NOTES_MERGE_WORKTREE), and instructs the user to resolve the
192 conflicts in that work tree. When done, the user can either finalize
193 the merge with git notes merge --commit, or abort the merge with git
194 notes merge --abort.
195 "ours" automatically resolves conflicting notes in favor of the local
197 version (i.e. the current notes ref).
198 "theirs" automatically resolves notes conflicts in favor of the remote
200 version (i.e. the given notes ref being merged into the current notes
201 ref).
202 "union" automatically resolves notes conflicts by concatenating the
204 local and remote versions.
205 "cat_sort_uniq" is similar to "union", but in addition to concatenating
207 the local and remote versions, this strategy also sorts the resulting
208 lines, and removes duplicate lines from the result. This is equivalent
209 to applying the "cat | sort | uniq" shell pipeline to the local and
210 remote versions. This strategy is useful if the notes follow a
211 line-based format where one wants to avoid duplicated lines in the
212 merge result. Note that if either the local or remote version contain
213 duplicate lines prior to the merge, these will also be removed by this
214 notes merge strategy.
215
217 You can use notes to add annotations with information that was not
218 available at the time a commit was written.
219 $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
221 $ git show -s 72a144e
222 [...]
223 Signed-off-by: Junio C Hamano <gitster@pobox.com>
224 Notes:
226 Tested-by: Johannes Sixt <j6t@kdbg.org>
227 In principle, a note is a regular Git blob, and any kind of
230 (non-)format is accepted. You can binary-safely create notes from
231 arbitrary files using git hash-object:
232 $ cc *.c
234 $ blob=$(git hash-object -w a.out)
235 $ git notes --ref=built add -C "$blob" HEAD
236 Of course, it doesn’t make much sense to display non-text-format notes
239 with git log, so if you use such notes, you’ll probably need to write
240 some special-purpose tools to do something useful with them.
241
243 core.notesRef
244 Notes ref to read and manipulate instead of refs/notes/commits.
245 Must be an unabbreviated ref name. This setting can be overridden
246 through the environment and command line.
247 notes.displayRef
249 Which ref (or refs, if a glob or specified more than once), in
250 addition to the default set by core.notesRef or GIT_NOTES_REF, to
251 read notes from when showing commit messages with the git log
252 family of commands. This setting can be overridden on the command
253 line or by the GIT_NOTES_DISPLAY_REF environment variable. See git-
254 log(1).
255 notes.rewrite.<command>
257 When rewriting commits with <command> (currently amend or rebase),
258 if this variable is false, git will not copy notes from the
259 original to the rewritten commit. Defaults to true. See also
260 "notes.rewriteRef" below.
261 This setting can be overridden by the GIT_NOTES_REWRITE_REF
263 environment variable.
264 notes.rewriteMode
266 When copying notes during a rewrite, what to do if the target
267 commit already has a note. Must be one of overwrite, concatenate,
268 and ignore. Defaults to concatenate.
269 This setting can be overridden with the GIT_NOTES_REWRITE_MODE
271 environment variable.
272 notes.rewriteRef
274 When copying notes during a rewrite, specifies the (fully
275 qualified) ref whose notes should be copied. May be a glob, in
276 which case notes in all matching refs will be copied. You may also
277 specify this configuration several times.
278 Does not have a default value; you must configure this variable to
280 enable note rewriting.
281 Can be overridden with the GIT_NOTES_REWRITE_REF environment
283 variable.
284
286 GIT_NOTES_REF
287 Which ref to manipulate notes from, instead of refs/notes/commits.
288 This overrides the core.notesRef setting.
289 GIT_NOTES_DISPLAY_REF
291 Colon-delimited list of refs or globs indicating which refs, in
292 addition to the default from core.notesRef or GIT_NOTES_REF, to
293 read notes from when showing commit messages. This overrides the
294 notes.displayRef setting.
295 A warning will be issued for refs that do not exist, but a glob
297 that does not match any refs is silently ignored.
298 GIT_NOTES_REWRITE_MODE
300 When copying notes during a rewrite, what to do if the target
301 commit already has a note. Must be one of overwrite, concatenate,
302 and ignore. This overrides the core.rewriteMode setting.
303 GIT_NOTES_REWRITE_REF
305 When rewriting commits, which notes to copy from the original to
306 the rewritten commit. Must be a colon-delimited list of refs or
307 globs.
308 If not set in the environment, the list of notes to copy depends on
310 the notes.rewrite.<command> and notes.rewriteRef settings.
311
313 Written by Johannes Schindelin <johannes.schindelin@gmx.de[2]> and
314 Johan Herland <johan@herland.net[3]>
315
317 Documentation by Johannes Schindelin and Johan Herland
318
320 Part of the git(7) suite
321
323 1. Permitted pathnames have the form ab/cd/ef/.../abcdef...: a
324 sequence of directory names of two hexadecimal digits each followed
325 by a filename with the rest of the object ID.
326 2. johannes.schindelin@gmx.de
328 mailto:johannes.schindelin@gmx.de
329 3. johan@herland.net
331 mailto:johan@herland.net
332Git 1.7.4.4 04/11/2011 GIT-NOTES(1)