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