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