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