]>
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] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] | |
13 | 'git notes' copy [-f] ( --stdin | <from-object> <to-object> ) | |
14 | 'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] | |
15 | 'git notes' edit [<object>] | |
16 | 'git notes' show [<object>] | |
17 | 'git notes' remove [<object>] | |
18 | 'git notes' prune [-n | -v] | |
19 | ||
20 | ||
21 | DESCRIPTION | |
22 | ----------- | |
23 | Adds, removes, or reads notes attached to objects, without touching | |
24 | the objects themselves. | |
25 | ||
26 | By default, notes are saved to and read from `refs/notes/commits`, but | |
27 | this default can be overridden. See the OPTIONS, CONFIGURATION, and | |
28 | ENVIRONMENT sections below. If this ref does not exist, it will be | |
29 | quietly created when it is first needed to store a note. | |
30 | ||
31 | A typical use of notes is to supplement a commit message without | |
32 | changing the commit itself. Notes can be shown by 'git log' along with | |
33 | the original commit message. To distinguish these notes from the | |
34 | message stored in the commit object, the notes are indented like the | |
35 | message, after an unindented line saying "Notes (<refname>):" (or | |
36 | "Notes:" for `refs/notes/commits`). | |
37 | ||
38 | To change which notes are shown by 'git log', see the | |
39 | "notes.displayRef" configuration in linkgit:git-log[1]. | |
40 | ||
41 | See the "notes.rewrite.<command>" configuration for a way to carry | |
42 | notes across commands that rewrite commits. | |
43 | ||
44 | ||
45 | SUBCOMMANDS | |
46 | ----------- | |
47 | ||
48 | list:: | |
49 | List the notes object for a given object. If no object is | |
50 | given, show a list of all note objects and the objects they | |
51 | annotate (in the format "<note object> <annotated object>"). | |
52 | This is the default subcommand if no subcommand is given. | |
53 | ||
54 | add:: | |
55 | Add notes for a given object (defaults to HEAD). Abort if the | |
56 | object already has notes (use `-f` to overwrite an | |
57 | existing note). | |
58 | ||
59 | copy:: | |
60 | Copy the notes for the first object onto the second object. | |
61 | Abort if the second object already has notes, or if the first | |
62 | object has none (use -f to overwrite existing notes to the | |
63 | second object). This subcommand is equivalent to: | |
64 | `git notes add [-f] -C $(git notes list <from-object>) <to-object>` | |
65 | + | |
66 | In `\--stdin` mode, take lines in the format | |
67 | + | |
68 | ---------- | |
69 | <from-object> SP <to-object> [ SP <rest> ] LF | |
70 | ---------- | |
71 | + | |
72 | on standard input, and copy the notes from each <from-object> to its | |
73 | corresponding <to-object>. (The optional `<rest>` is ignored so that | |
74 | the command can read the input given to the `post-rewrite` hook.) | |
75 | ||
76 | append:: | |
77 | Append to the notes of an existing object (defaults to HEAD). | |
78 | Creates a new notes object if needed. | |
79 | ||
80 | edit:: | |
81 | Edit the notes for a given object (defaults to HEAD). | |
82 | ||
83 | show:: | |
84 | Show the notes for a given object (defaults to HEAD). | |
85 | ||
86 | remove:: | |
87 | Remove the notes for a given object (defaults to HEAD). | |
88 | This is equivalent to specifying an empty note message to | |
89 | the `edit` subcommand. | |
90 | ||
91 | prune:: | |
92 | Remove all notes for non-existing/unreachable objects. | |
93 | ||
94 | OPTIONS | |
95 | ------- | |
96 | -f:: | |
97 | --force:: | |
98 | When adding notes to an object that already has notes, | |
99 | overwrite the existing notes (instead of aborting). | |
100 | ||
101 | -m <msg>:: | |
102 | --message=<msg>:: | |
103 | Use the given note message (instead of prompting). | |
104 | If multiple `-m` options are given, their values | |
105 | are concatenated as separate paragraphs. | |
106 | Lines starting with `#` and empty lines other than a | |
107 | single line between paragraphs will be stripped out. | |
108 | ||
109 | -F <file>:: | |
110 | --file=<file>:: | |
111 | Take the note message from the given file. Use '-' to | |
112 | read the note message from the standard input. | |
113 | Lines starting with `#` and empty lines other than a | |
114 | single line between paragraphs will be stripped out. | |
115 | ||
116 | -C <object>:: | |
117 | --reuse-message=<object>:: | |
118 | Take the note message from the given blob object (for | |
119 | example, another note). | |
120 | ||
121 | -c <object>:: | |
122 | --reedit-message=<object>:: | |
123 | Like '-C', but with '-c' the editor is invoked, so that | |
124 | the user can further edit the note message. | |
125 | ||
126 | --ref <ref>:: | |
127 | Manipulate the notes tree in <ref>. This overrides | |
128 | 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref | |
129 | is taken to be in `refs/notes/` if it is not qualified. | |
130 | ||
131 | -n:: | |
132 | --dry-run:: | |
133 | Do not remove anything; just report the object names whose notes | |
134 | would be removed. | |
135 | ||
136 | -v:: | |
137 | --verbose:: | |
138 | Report all object names whose notes are removed. | |
139 | ||
140 | ||
141 | DISCUSSION | |
142 | ---------- | |
143 | ||
144 | Commit notes are blobs containing extra information about an object | |
145 | (usually information to supplement a commit's message). These blobs | |
146 | are taken from notes refs. A notes ref is usually a branch which | |
147 | contains "files" whose paths are the object names for the objects | |
148 | they describe, with some directory separators included for performance | |
149 | reasons footnote:[Permitted pathnames have the form | |
150 | 'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory | |
151 | names of two hexadecimal digits each followed by a filename with the | |
152 | rest of the object ID.]. | |
153 | ||
154 | Every notes change creates a new commit at the specified notes ref. | |
155 | You can therefore inspect the history of the notes by invoking, e.g., | |
156 | `git log -p notes/commits`. Currently the commit message only records | |
157 | which operation triggered the update, and the commit authorship is | |
158 | determined according to the usual rules (see linkgit:git-commit[1]). | |
159 | These details may change in the future. | |
160 | ||
161 | It is also permitted for a notes ref to point directly to a tree | |
162 | object, in which case the history of the notes can be read with | |
163 | `git log -p -g <refname>`. | |
164 | ||
165 | ||
166 | EXAMPLES | |
167 | -------- | |
168 | ||
169 | You can use notes to add annotations with information that was not | |
170 | available at the time a commit was written. | |
171 | ||
172 | ------------ | |
173 | $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 | |
174 | $ git show -s 72a144e | |
175 | [...] | |
176 | Signed-off-by: Junio C Hamano <gitster@pobox.com> | |
177 | ||
178 | Notes: | |
179 | Tested-by: Johannes Sixt <j6t@kdbg.org> | |
180 | ------------ | |
181 | ||
182 | In principle, a note is a regular Git blob, and any kind of | |
183 | (non-)format is accepted. You can binary-safely create notes from | |
184 | arbitrary files using 'git hash-object': | |
185 | ||
186 | ------------ | |
187 | $ cc *.c | |
188 | $ blob=$(git hash-object -w a.out) | |
189 | $ git notes --ref=built add -C "$blob" HEAD | |
190 | ------------ | |
191 | ||
192 | Of course, it doesn't make much sense to display non-text-format notes | |
193 | with 'git log', so if you use such notes, you'll probably need to write | |
194 | some special-purpose tools to do something useful with them. | |
195 | ||
196 | ||
197 | CONFIGURATION | |
198 | ------------- | |
199 | ||
200 | core.notesRef:: | |
201 | Notes ref to read and manipulate instead of | |
202 | `refs/notes/commits`. Must be an unabbreviated ref name. | |
203 | This setting can be overridden through the environment and | |
204 | command line. | |
205 | ||
206 | notes.displayRef:: | |
207 | Which ref (or refs, if a glob or specified more than once), in | |
208 | addition to the default set by `core.notesRef` or | |
209 | 'GIT_NOTES_REF', to read notes from when showing commit | |
210 | messages with the 'git log' family of commands. | |
211 | This setting can be overridden on the command line or by the | |
212 | 'GIT_NOTES_DISPLAY_REF' environment variable. | |
213 | See linkgit:git-log[1]. | |
214 | ||
215 | notes.rewrite.<command>:: | |
216 | When rewriting commits with <command> (currently `amend` or | |
217 | `rebase`), if this variable is `false`, git will not copy | |
218 | notes from the original to the rewritten commit. Defaults to | |
219 | `true`. See also "`notes.rewriteRef`" below. | |
220 | + | |
221 | This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' | |
222 | environment variable. | |
223 | ||
224 | notes.rewriteMode:: | |
225 | When copying notes during a rewrite, what to do if the target | |
226 | commit already has a note. Must be one of `overwrite`, | |
227 | `concatenate`, and `ignore`. Defaults to `concatenate`. | |
228 | + | |
229 | This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` | |
230 | environment variable. | |
231 | ||
232 | notes.rewriteRef:: | |
233 | When copying notes during a rewrite, specifies the (fully | |
234 | qualified) ref whose notes should be copied. May be a glob, | |
235 | in which case notes in all matching refs will be copied. You | |
236 | may also specify this configuration several times. | |
237 | + | |
238 | Does not have a default value; you must configure this variable to | |
239 | enable note rewriting. | |
240 | + | |
241 | Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. | |
242 | ||
243 | ||
244 | ENVIRONMENT | |
245 | ----------- | |
246 | ||
247 | 'GIT_NOTES_REF':: | |
248 | Which ref to manipulate notes from, instead of `refs/notes/commits`. | |
249 | This overrides the `core.notesRef` setting. | |
250 | ||
251 | 'GIT_NOTES_DISPLAY_REF':: | |
252 | Colon-delimited list of refs or globs indicating which refs, | |
253 | in addition to the default from `core.notesRef` or | |
254 | 'GIT_NOTES_REF', to read notes from when showing commit | |
255 | messages. | |
256 | This overrides the `notes.displayRef` setting. | |
257 | + | |
258 | A warning will be issued for refs that do not exist, but a glob that | |
259 | does not match any refs is silently ignored. | |
260 | ||
261 | 'GIT_NOTES_REWRITE_MODE':: | |
262 | When copying notes during a rewrite, what to do if the target | |
263 | commit already has a note. | |
264 | Must be one of `overwrite`, `concatenate`, and `ignore`. | |
265 | This overrides the `core.rewriteMode` setting. | |
266 | ||
267 | 'GIT_NOTES_REWRITE_REF':: | |
268 | When rewriting commits, which notes to copy from the original | |
269 | to the rewritten commit. Must be a colon-delimited list of | |
270 | refs or globs. | |
271 | + | |
272 | If not set in the environment, the list of notes to copy depends | |
273 | on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. | |
274 | ||
275 | ||
276 | Author | |
277 | ------ | |
278 | Written by Johannes Schindelin <johannes.schindelin@gmx.de> and | |
279 | Johan Herland <johan@herland.net> | |
280 | ||
281 | Documentation | |
282 | ------------- | |
283 | Documentation by Johannes Schindelin and Johan Herland | |
284 | ||
285 | GIT | |
286 | --- | |
287 | Part of the linkgit:git[7] suite |