1GIT-NOTES(1) Git Manual GIT-NOTES(1)
2
3
4
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
22
24 Adds, removes, or reads notes attached to objects, without touching the
25 objects themselves.
26
27 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
32 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
39 To change which notes are shown by git log, see the "notes.displayRef"
40 configuration in git-log(1).
41
42 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
52 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
56 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
63 In --stdin mode, take lines in the format
64
65 <from-object> SP <to-object> [ SP <rest> ] LF
66
67 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
72 append
73 Append to the notes of an existing object (defaults to HEAD).
74 Creates a new notes object if needed.
75
76 edit
77 Edit the notes for a given object (defaults to HEAD).
78
79 show
80 Show the notes for a given object (defaults to HEAD).
81
82 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
88 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
96 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
101 prune
102 Remove all notes for non-existing/unreachable objects.
103
104 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
113 -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
119 -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
125 -C <object>, --reuse-message=<object>
126 Take the note message from the given blob object (for example,
127 another note).
128
129 -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
133 --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
138 -n, --dry-run
139 Do not remove anything; just report the object names whose notes
140 would be removed.
141
142 -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
149 --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
158 --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
163 -q, --quiet
164 When merging notes, operate quietly.
165
166 -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
177 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
184 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
196 "ours" automatically resolves conflicting notes in favor of the local
197 version (i.e. the current notes ref).
198
199 "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
203 "union" automatically resolves notes conflicts by concatenating the
204 local and remote versions.
205
206 "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
220 $ 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
225 Notes:
226 Tested-by: Johannes Sixt <j6t@kdbg.org>
227
228
229 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
233 $ cc *.c
234 $ blob=$(git hash-object -w a.out)
235 $ git notes --ref=built add -C "$blob" HEAD
236
237
238 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
248 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
256 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
262 This setting can be overridden by the GIT_NOTES_REWRITE_REF
263 environment variable.
264
265 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
270 This setting can be overridden with the GIT_NOTES_REWRITE_MODE
271 environment variable.
272
273 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
279 Does not have a default value; you must configure this variable to
280 enable note rewriting.
281
282 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
290 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
296 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
299 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
304 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
309 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
327 2. johannes.schindelin@gmx.de
328 mailto:johannes.schindelin@gmx.de
329
330 3. johan@herland.net
331 mailto:johan@herland.net
332
333
334
335Git 1.7.4.4 04/11/2011 GIT-NOTES(1)