]>
Commit | Line | Data |
---|---|---|
65d9fb48 JS |
1 | git-notes(1) |
2 | ============ | |
3 | ||
4 | NAME | |
5 | ---- | |
1a3eb9a0 | 6 | git-notes - Add or inspect object notes |
65d9fb48 JS |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
e397421a | 11 | 'git notes' [list [<object>]] |
3d6a3164 | 12 | 'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] |
d58deb9c | 13 | 'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] ) |
3d6a3164 | 14 | 'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] |
c4e2aa7d | 15 | 'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace] |
e397421a | 16 | 'git notes' show [<object>] |
e703d711 | 17 | 'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref> |
6abb3655 JH |
18 | 'git notes' merge --commit [-v | -q] |
19 | 'git notes' merge --abort [-v | -q] | |
46538012 | 20 | 'git notes' remove [--ignore-missing] [--stdin] [<object>...] |
e54b6335 | 21 | 'git notes' prune [-n] [-v] |
618cd757 | 22 | 'git notes' get-ref |
e397421a | 23 | |
65d9fb48 JS |
24 | |
25 | DESCRIPTION | |
26 | ----------- | |
1a3eb9a0 JN |
27 | Adds, removes, or reads notes attached to objects, without touching |
28 | the objects themselves. | |
65d9fb48 | 29 | |
00979710 JN |
30 | By default, notes are saved to and read from `refs/notes/commits`, but |
31 | this default can be overridden. See the OPTIONS, CONFIGURATION, and | |
32 | ENVIRONMENT sections below. If this ref does not exist, it will be | |
33 | quietly created when it is first needed to store a note. | |
34 | ||
1a3eb9a0 JN |
35 | A typical use of notes is to supplement a commit message without |
36 | changing the commit itself. Notes can be shown by 'git log' along with | |
37 | the original commit message. To distinguish these notes from the | |
7d541174 | 38 | message stored in the commit object, the notes are indented like the |
894a9d33 | 39 | message, after an unindented line saying "Notes (<refname>):" (or |
9eb3f816 | 40 | "Notes:" for `refs/notes/commits`). |
7d541174 | 41 | |
e39b307d PO |
42 | Notes can also be added to patches prepared with `git format-patch` by |
43 | using the `--notes` option. Such notes are added as a patch commentary | |
44 | after a three dash separator line. | |
45 | ||
66c4c32d | 46 | To change which notes are shown by 'git log', see the |
5bd277e2 | 47 | "notes.displayRef" discussion in <<CONFIGURATION>>. |
65d9fb48 | 48 | |
c5ce1836 JN |
49 | See the "notes.rewrite.<command>" configuration for a way to carry |
50 | notes across commands that rewrite commits. | |
65d9fb48 JS |
51 | |
52 | ||
53 | SUBCOMMANDS | |
54 | ----------- | |
55 | ||
e397421a JH |
56 | list:: |
57 | List the notes object for a given object. If no object is | |
58 | given, show a list of all note objects and the objects they | |
2162f9f6 | 59 | annotate (in the format "<note-object> <annotated-object>"). |
e397421a JH |
60 | This is the default subcommand if no subcommand is given. |
61 | ||
7aa4754e JH |
62 | add:: |
63 | Add notes for a given object (defaults to HEAD). Abort if the | |
84a7e35e JH |
64 | object already has notes (use `-f` to overwrite existing notes). |
65 | However, if you're using `add` interactively (using an editor | |
66 | to supply the notes contents), then - instead of aborting - | |
67 | the existing notes will be opened in the editor (like the `edit` | |
90bc19b3 TL |
68 | subcommand). If you specify multiple `-m` and `-F`, a blank |
69 | line will be inserted between the messages. Use the `--separator` | |
70 | option to insert other delimiters. | |
7aa4754e | 71 | |
e73bbd96 | 72 | copy:: |
d58deb9c ĐTCD |
73 | Copy the notes for the first object onto the second object (defaults to |
74 | HEAD). Abort if the second object already has notes, or if the first | |
48716a23 | 75 | object has none (use -f to overwrite existing notes to the |
e73bbd96 JH |
76 | second object). This subcommand is equivalent to: |
77 | `git notes add [-f] -C $(git notes list <from-object>) <to-object>` | |
160baa0d | 78 | + |
6cf378f0 | 79 | In `--stdin` mode, take lines in the format |
160baa0d TR |
80 | + |
81 | ---------- | |
82 | <from-object> SP <to-object> [ SP <rest> ] LF | |
83 | ---------- | |
84 | + | |
85 | on standard input, and copy the notes from each <from-object> to its | |
86 | corresponding <to-object>. (The optional `<rest>` is ignored so that | |
87 | the command can read the input given to the `post-rewrite` hook.) | |
e73bbd96 | 88 | |
2347fae5 | 89 | append:: |
90bc19b3 TL |
90 | Append new message(s) given by `-m` or `-F` options to an |
91 | existing note, or add them as a new note if one does not | |
92 | exist, for the object (defaults to HEAD). When appending to | |
93 | an existing note, a blank line is added before each new | |
94 | message as an inter-paragraph separator. The separator can | |
95 | be customized with the `--separator` option. | |
2347fae5 | 96 | |
65d9fb48 | 97 | edit:: |
7d541174 | 98 | Edit the notes for a given object (defaults to HEAD). |
65d9fb48 JS |
99 | |
100 | show:: | |
7d541174 | 101 | Show the notes for a given object (defaults to HEAD). |
65d9fb48 | 102 | |
00f03061 JH |
103 | merge:: |
104 | Merge the given notes ref into the current notes ref. | |
105 | This will try to merge the changes made by the given | |
106 | notes ref (called "remote") since the merge-base (if | |
107 | any) into the current notes ref (called "local"). | |
108 | + | |
109 | If conflicts arise and a strategy for automatically resolving | |
d2d68d99 | 110 | conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given, |
809f38c8 JH |
111 | the "manual" resolver is used. This resolver checks out the |
112 | conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), | |
113 | and instructs the user to manually resolve the conflicts there. | |
6abb3655 JH |
114 | When done, the user can either finalize the merge with |
115 | 'git notes merge --commit', or abort the merge with | |
116 | 'git notes merge --abort'. | |
00f03061 | 117 | |
92b3385f | 118 | remove:: |
c3ab1a8e JH |
119 | Remove the notes for given objects (defaults to HEAD). When |
120 | giving zero or one object from the command line, this is | |
121 | equivalent to specifying an empty note message to | |
92b3385f JH |
122 | the `edit` subcommand. |
123 | ||
d6576e1f JH |
124 | prune:: |
125 | Remove all notes for non-existing/unreachable objects. | |
65d9fb48 | 126 | |
618cd757 JH |
127 | get-ref:: |
128 | Print the current notes ref. This provides an easy way to | |
129 | retrieve the current notes ref (e.g. from scripts). | |
130 | ||
d9246d43 JH |
131 | OPTIONS |
132 | ------- | |
7aa4754e JH |
133 | -f:: |
134 | --force:: | |
135 | When adding notes to an object that already has notes, | |
136 | overwrite the existing notes (instead of aborting). | |
137 | ||
d9246d43 | 138 | -m <msg>:: |
ba20f15e | 139 | --message=<msg>:: |
d9246d43 | 140 | Use the given note message (instead of prompting). |
cd067d3b JH |
141 | If multiple `-m` options are given, their values |
142 | are concatenated as separate paragraphs. | |
8d6888ec | 143 | Lines starting with `#` and empty lines other than a |
95b6ae9d MÅ |
144 | single line between paragraphs will be stripped out. |
145 | If you wish to keep them verbatim, use `--no-stripspace`. | |
d9246d43 JH |
146 | |
147 | -F <file>:: | |
ba20f15e | 148 | --file=<file>:: |
d9246d43 JH |
149 | Take the note message from the given file. Use '-' to |
150 | read the note message from the standard input. | |
8d6888ec | 151 | Lines starting with `#` and empty lines other than a |
95b6ae9d MÅ |
152 | single line between paragraphs will be stripped out. |
153 | If you wish to keep them verbatim, use `--no-stripspace`. | |
d9246d43 | 154 | |
0691cff7 JH |
155 | -C <object>:: |
156 | --reuse-message=<object>:: | |
8d75a1d1 | 157 | Take the given blob object (for example, another note) as the |
11432bb4 | 158 | note message. (Use `git notes copy <object>` instead to |
c4e2aa7d TL |
159 | copy notes between objects.). By default, message will be |
160 | copied verbatim, but if you wish to strip out the lines | |
161 | starting with `#` and empty lines other than a single line | |
162 | between paragraphs, use with`--stripspace` option. | |
0691cff7 JH |
163 | |
164 | -c <object>:: | |
165 | --reedit-message=<object>:: | |
23f8239b | 166 | Like '-C', but with `-c` the editor is invoked, so that |
0691cff7 | 167 | the user can further edit the note message. |
d9246d43 | 168 | |
d73a5b93 JH |
169 | --allow-empty:: |
170 | Allow an empty note object to be stored. The default behavior is | |
171 | to automatically remove empty notes. | |
172 | ||
3d6a3164 | 173 | --[no-]separator, --separator=<paragraph-break>:: |
90bc19b3 | 174 | Specify a string used as a custom inter-paragraph separator |
3d6a3164 TL |
175 | (a newline is added at the end as needed). If `--no-separator`, no |
176 | separators will be added between paragraphs. Defaults to a blank | |
177 | line. | |
90bc19b3 | 178 | |
c4e2aa7d TL |
179 | --[no-]stripspace:: |
180 | Strip leading and trailing whitespace from the note message. | |
181 | Also strip out empty lines other than a single line between | |
3a6e1ad8 MÅ |
182 | paragraphs. Lines starting with `#` will be stripped out |
183 | in non-editor cases like `-m`, `-F` and `-C`, but not in | |
184 | editor case like `git notes edit`, `-c`, etc. | |
c4e2aa7d | 185 | |
dcf783a2 | 186 | --ref <ref>:: |
00979710 | 187 | Manipulate the notes tree in <ref>. This overrides |
eee7f4a2 | 188 | `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref |
e14c92e8 JK |
189 | specifies the full refname when it begins with `refs/notes/`; when it |
190 | begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed | |
191 | to form a full name of the ref. | |
dcf783a2 | 192 | |
2d370d2f JH |
193 | --ignore-missing:: |
194 | Do not consider it an error to request removing notes from an | |
195 | object that does not have notes attached to it. | |
196 | ||
46538012 | 197 | --stdin:: |
be94568b | 198 | Also read the object names to remove notes from the standard |
46538012 JH |
199 | input (there is no reason you cannot combine this with object |
200 | names from the command line). | |
201 | ||
a9f2adff | 202 | -n:: |
e93487d2 | 203 | --dry-run:: |
a9f2adff MG |
204 | Do not remove anything; just report the object names whose notes |
205 | would be removed. | |
206 | ||
00f03061 JH |
207 | -s <strategy>:: |
208 | --strategy=<strategy>:: | |
209 | When merging notes, resolve notes conflicts using the given | |
210 | strategy. The following strategies are recognized: "manual" | |
a6a09095 | 211 | (default), "ours", "theirs", "union" and "cat_sort_uniq". |
d2d68d99 | 212 | This option overrides the "notes.mergeStrategy" configuration setting. |
00f03061 JH |
213 | See the "NOTES MERGE STRATEGIES" section below for more |
214 | information on each notes merge strategy. | |
215 | ||
6abb3655 JH |
216 | --commit:: |
217 | Finalize an in-progress 'git notes merge'. Use this option | |
218 | when you have resolved the conflicts that 'git notes merge' | |
219 | stored in .git/NOTES_MERGE_WORKTREE. This amends the partial | |
220 | merge commit created by 'git notes merge' (stored in | |
221 | .git/NOTES_MERGE_PARTIAL) by adding the notes in | |
222 | .git/NOTES_MERGE_WORKTREE. The notes ref stored in the | |
223 | .git/NOTES_MERGE_REF symref is updated to the resulting commit. | |
224 | ||
225 | --abort:: | |
928f0ab4 | 226 | Abort/reset an in-progress 'git notes merge', i.e. a notes merge |
6abb3655 JH |
227 | with conflicts. This simply removes all files related to the |
228 | notes merge. | |
229 | ||
00f03061 JH |
230 | -q:: |
231 | --quiet:: | |
232 | When merging notes, operate quietly. | |
233 | ||
a9f2adff | 234 | -v:: |
e93487d2 | 235 | --verbose:: |
00f03061 JH |
236 | When merging notes, be more verbose. |
237 | When pruning notes, report all object names whose notes are | |
238 | removed. | |
a9f2adff | 239 | |
66d68199 | 240 | |
9eb3f816 JN |
241 | DISCUSSION |
242 | ---------- | |
243 | ||
244 | Commit notes are blobs containing extra information about an object | |
245 | (usually information to supplement a commit's message). These blobs | |
246 | are taken from notes refs. A notes ref is usually a branch which | |
247 | contains "files" whose paths are the object names for the objects | |
248 | they describe, with some directory separators included for performance | |
249 | reasons footnote:[Permitted pathnames have the form | |
de20baf2 | 250 | 'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': a sequence of directory |
9eb3f816 JN |
251 | names of two hexadecimal digits each followed by a filename with the |
252 | rest of the object ID.]. | |
66d68199 TR |
253 | |
254 | Every notes change creates a new commit at the specified notes ref. | |
255 | You can therefore inspect the history of the notes by invoking, e.g., | |
9eb3f816 JN |
256 | `git log -p notes/commits`. Currently the commit message only records |
257 | which operation triggered the update, and the commit authorship is | |
258 | determined according to the usual rules (see linkgit:git-commit[1]). | |
259 | These details may change in the future. | |
260 | ||
261 | It is also permitted for a notes ref to point directly to a tree | |
262 | object, in which case the history of the notes can be read with | |
263 | `git log -p -g <refname>`. | |
66d68199 TR |
264 | |
265 | ||
00f03061 JH |
266 | NOTES MERGE STRATEGIES |
267 | ---------------------- | |
268 | ||
809f38c8 JH |
269 | The default notes merge strategy is "manual", which checks out |
270 | conflicting notes in a special work tree for resolving notes conflicts | |
271 | (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the | |
272 | conflicts in that work tree. | |
6abb3655 JH |
273 | When done, the user can either finalize the merge with |
274 | 'git notes merge --commit', or abort the merge with | |
275 | 'git notes merge --abort'. | |
00f03061 | 276 | |
d2d68d99 JK |
277 | Users may select an automated merge strategy from among the following using |
278 | either -s/--strategy option or configuring notes.mergeStrategy accordingly: | |
279 | ||
00f03061 JH |
280 | "ours" automatically resolves conflicting notes in favor of the local |
281 | version (i.e. the current notes ref). | |
282 | ||
283 | "theirs" automatically resolves notes conflicts in favor of the remote | |
284 | version (i.e. the given notes ref being merged into the current notes | |
285 | ref). | |
286 | ||
287 | "union" automatically resolves notes conflicts by concatenating the | |
288 | local and remote versions. | |
289 | ||
a6a09095 JH |
290 | "cat_sort_uniq" is similar to "union", but in addition to concatenating |
291 | the local and remote versions, this strategy also sorts the resulting | |
292 | lines, and removes duplicate lines from the result. This is equivalent | |
293 | to applying the "cat | sort | uniq" shell pipeline to the local and | |
294 | remote versions. This strategy is useful if the notes follow a line-based | |
295 | format where one wants to avoid duplicated lines in the merge result. | |
296 | Note that if either the local or remote version contain duplicate lines | |
297 | prior to the merge, these will also be removed by this notes merge | |
298 | strategy. | |
299 | ||
00f03061 | 300 | |
8d6888ec JN |
301 | EXAMPLES |
302 | -------- | |
303 | ||
304 | You can use notes to add annotations with information that was not | |
305 | available at the time a commit was written. | |
306 | ||
307 | ------------ | |
308 | $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 | |
309 | $ git show -s 72a144e | |
310 | [...] | |
311 | Signed-off-by: Junio C Hamano <gitster@pobox.com> | |
312 | ||
313 | Notes: | |
314 | Tested-by: Johannes Sixt <j6t@kdbg.org> | |
315 | ------------ | |
316 | ||
317 | In principle, a note is a regular Git blob, and any kind of | |
318 | (non-)format is accepted. You can binary-safely create notes from | |
319 | arbitrary files using 'git hash-object': | |
320 | ||
321 | ------------ | |
322 | $ cc *.c | |
323 | $ blob=$(git hash-object -w a.out) | |
d73a5b93 | 324 | $ git notes --ref=built add --allow-empty -C "$blob" HEAD |
8d6888ec JN |
325 | ------------ |
326 | ||
11432bb4 MG |
327 | (You cannot simply use `git notes --ref=built add -F a.out HEAD` |
328 | because that is not binary-safe.) | |
8d6888ec JN |
329 | Of course, it doesn't make much sense to display non-text-format notes |
330 | with 'git log', so if you use such notes, you'll probably need to write | |
331 | some special-purpose tools to do something useful with them. | |
332 | ||
333 | ||
5bd277e2 | 334 | [[CONFIGURATION]] |
ed9098fd JN |
335 | CONFIGURATION |
336 | ------------- | |
337 | ||
338 | core.notesRef:: | |
00979710 JN |
339 | Notes ref to read and manipulate instead of |
340 | `refs/notes/commits`. Must be an unabbreviated ref name. | |
341 | This setting can be overridden through the environment and | |
342 | command line. | |
ed9098fd | 343 | |
5bd277e2 ÆAB |
344 | include::includes/cmd-config-section-rest.txt[] |
345 | ||
346 | include::config/notes.txt[] | |
ed9098fd | 347 | |
00979710 JN |
348 | |
349 | ENVIRONMENT | |
350 | ----------- | |
351 | ||
eee7f4a2 | 352 | `GIT_NOTES_REF`:: |
00979710 JN |
353 | Which ref to manipulate notes from, instead of `refs/notes/commits`. |
354 | This overrides the `core.notesRef` setting. | |
355 | ||
eee7f4a2 | 356 | `GIT_NOTES_DISPLAY_REF`:: |
66c4c32d JN |
357 | Colon-delimited list of refs or globs indicating which refs, |
358 | in addition to the default from `core.notesRef` or | |
eee7f4a2 | 359 | `GIT_NOTES_REF`, to read notes from when showing commit |
66c4c32d JN |
360 | messages. |
361 | This overrides the `notes.displayRef` setting. | |
362 | + | |
363 | A warning will be issued for refs that do not exist, but a glob that | |
364 | does not match any refs is silently ignored. | |
365 | ||
eee7f4a2 | 366 | `GIT_NOTES_REWRITE_MODE`:: |
c5ce1836 JN |
367 | When copying notes during a rewrite, what to do if the target |
368 | commit already has a note. | |
e48ad1b9 | 369 | Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. |
c5ce1836 JN |
370 | This overrides the `core.rewriteMode` setting. |
371 | ||
eee7f4a2 | 372 | `GIT_NOTES_REWRITE_REF`:: |
c5ce1836 JN |
373 | When rewriting commits, which notes to copy from the original |
374 | to the rewritten commit. Must be a colon-delimited list of | |
375 | refs or globs. | |
376 | + | |
377 | If not set in the environment, the list of notes to copy depends | |
378 | on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. | |
379 | ||
65d9fb48 JS |
380 | GIT |
381 | --- | |
1cca17df | 382 | Part of the linkgit:git[1] suite |