Documentation/git-notes.txt

   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] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
  13 'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] )
  14 'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
  15 'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace]
  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" discussion in <<CONFIGURATION>>.
  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). 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.
  71
  72 copy::
  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
  75         object has none (use -f to overwrite existing notes to the
  76         second object). This subcommand is equivalent to:
  77         `git notes add [-f] -C $(git notes list <from-object>) <to-object>`
  78 +
  79 In `--stdin` mode, take lines in the format
  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.)
  88
  89 append::
  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.
  96
  97 edit::
  98         Edit the notes for a given object (defaults to HEAD).
  99
 100 show::
 101         Show the notes for a given object (defaults to HEAD).
 102
 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
 110 conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given,
 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.
 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'.
 117
 118 remove::
 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
 122         the `edit` subcommand.
 123
 124 prune::
 125         Remove all notes for non-existing/unreachable objects.
 126
 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
 131 OPTIONS
 132 -------
 133 -f::
 134 --force::
 135         When adding notes to an object that already has notes,
 136         overwrite the existing notes (instead of aborting).
 137
 138 -m <msg>::
 139 --message=<msg>::
 140         Use the given note message (instead of prompting).
 141         If multiple `-m` options are given, their values
 142         are concatenated as separate paragraphs.
 143         Lines starting with `#` and empty lines other than a
 144         single line between paragraphs will be stripped out,
 145         if you wish to keep them verbatim, use `--no-stripspace`.
 146
 147 -F <file>::
 148 --file=<file>::
 149         Take the note message from the given file.  Use '-' to
 150         read the note message from the standard input.
 151         Lines starting with `#` and empty lines other than a
 152         single line between paragraphs will be stripped out,
 153         if you wish to keep them verbatim, use with
 154         `--no-stripspace` option.
 155
 156 -C <object>::
 157 --reuse-message=<object>::
 158         Take the given blob object (for example, another note) as the
 159         note message. (Use `git notes copy <object>` instead to
 160         copy notes between objects.).  By default, message will be
 161         copied verbatim, but if you wish to strip out the lines
 162         starting with `#` and empty lines other than a single line
 163         between paragraphs, use with`--stripspace` option.
 164
 165 -c <object>::
 166 --reedit-message=<object>::
 167         Like '-C', but with `-c` the editor is invoked, so that
 168         the user can further edit the note message.
 169
 170 --allow-empty::
 171         Allow an empty note object to be stored. The default behavior is
 172         to automatically remove empty notes.
 173
 174 --[no-]separator, --separator=<paragraph-break>::
 175         Specify a string used as a custom inter-paragraph separator
 176         (a newline is added at the end as needed). If `--no-separator`, no
 177         separators will be added between paragraphs.  Defaults to a blank
 178         line.
 179
 180 --[no-]stripspace::
 181         Strip leading and trailing whitespace from the note message.
 182         Also strip out empty lines other than a single line between
 183         paragraphs. For lines starting with `#` will be stripped out
 184         in non-editor cases like "-m", "-F" and "-C", but not in
 185         editor case like "git notes edit", "-c", etc.
 186
 187 --ref <ref>::
 188         Manipulate the notes tree in <ref>.  This overrides
 189         `GIT_NOTES_REF` and the "core.notesRef" configuration.  The ref
 190         specifies the full refname when it begins with `refs/notes/`; when it
 191         begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed
 192         to form a full name of the ref.
 193
 194 --ignore-missing::
 195         Do not consider it an error to request removing notes from an
 196         object that does not have notes attached to it.
 197
 198 --stdin::
 199         Also read the object names to remove notes from the standard
 200         input (there is no reason you cannot combine this with object
 201         names from the command line).
 202
 203 -n::
 204 --dry-run::
 205         Do not remove anything; just report the object names whose notes
 206         would be removed.
 207
 208 -s <strategy>::
 209 --strategy=<strategy>::
 210         When merging notes, resolve notes conflicts using the given
 211         strategy. The following strategies are recognized: "manual"
 212         (default), "ours", "theirs", "union" and "cat_sort_uniq".
 213         This option overrides the "notes.mergeStrategy" configuration setting.
 214         See the "NOTES MERGE STRATEGIES" section below for more
 215         information on each notes merge strategy.
 216
 217 --commit::
 218         Finalize an in-progress 'git notes merge'. Use this option
 219         when you have resolved the conflicts that 'git notes merge'
 220         stored in .git/NOTES_MERGE_WORKTREE. This amends the partial
 221         merge commit created by 'git notes merge' (stored in
 222         .git/NOTES_MERGE_PARTIAL) by adding the notes in
 223         .git/NOTES_MERGE_WORKTREE. The notes ref stored in the
 224         .git/NOTES_MERGE_REF symref is updated to the resulting commit.
 225
 226 --abort::
 227         Abort/reset an in-progress 'git notes merge', i.e. a notes merge
 228         with conflicts. This simply removes all files related to the
 229         notes merge.
 230
 231 -q::
 232 --quiet::
 233         When merging notes, operate quietly.
 234
 235 -v::
 236 --verbose::
 237         When merging notes, be more verbose.
 238         When pruning notes, report all object names whose notes are
 239         removed.
 240
 241
 242 DISCUSSION
 243 ----------
 244
 245 Commit notes are blobs containing extra information about an object
 246 (usually information to supplement a commit's message).  These blobs
 247 are taken from notes refs.  A notes ref is usually a branch which
 248 contains "files" whose paths are the object names for the objects
 249 they describe, with some directory separators included for performance
 250 reasons footnote:[Permitted pathnames have the form
 251 'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': a sequence of directory
 252 names of two hexadecimal digits each followed by a filename with the
 253 rest of the object ID.].
 254
 255 Every notes change creates a new commit at the specified notes ref.
 256 You can therefore inspect the history of the notes by invoking, e.g.,
 257 `git log -p notes/commits`.  Currently the commit message only records
 258 which operation triggered the update, and the commit authorship is
 259 determined according to the usual rules (see linkgit:git-commit[1]).
 260 These details may change in the future.
 261
 262 It is also permitted for a notes ref to point directly to a tree
 263 object, in which case the history of the notes can be read with
 264 `git log -p -g <refname>`.
 265
 266
 267 NOTES MERGE STRATEGIES
 268 ----------------------
 269
 270 The default notes merge strategy is "manual", which checks out
 271 conflicting notes in a special work tree for resolving notes conflicts
 272 (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the
 273 conflicts in that work tree.
 274 When done, the user can either finalize the merge with
 275 'git notes merge --commit', or abort the merge with
 276 'git notes merge --abort'.
 277
 278 Users may select an automated merge strategy from among the following using
 279 either -s/--strategy option or configuring notes.mergeStrategy accordingly:
 280
 281 "ours" automatically resolves conflicting notes in favor of the local
 282 version (i.e. the current notes ref).
 283
 284 "theirs" automatically resolves notes conflicts in favor of the remote
 285 version (i.e. the given notes ref being merged into the current notes
 286 ref).
 287
 288 "union" automatically resolves notes conflicts by concatenating the
 289 local and remote versions.
 290
 291 "cat_sort_uniq" is similar to "union", but in addition to concatenating
 292 the local and remote versions, this strategy also sorts the resulting
 293 lines, and removes duplicate lines from the result. This is equivalent
 294 to applying the "cat | sort | uniq" shell pipeline to the local and
 295 remote versions. This strategy is useful if the notes follow a line-based
 296 format where one wants to avoid duplicated lines in the merge result.
 297 Note that if either the local or remote version contain duplicate lines
 298 prior to the merge, these will also be removed by this notes merge
 299 strategy.
 300
 301
 302 EXAMPLES
 303 --------
 304
 305 You can use notes to add annotations with information that was not
 306 available at the time a commit was written.
 307
 308 ------------
 309 $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
 310 $ git show -s 72a144e
 311 [...]
 312     Signed-off-by: Junio C Hamano <gitster@pobox.com>
 313
 314 Notes:
 315     Tested-by: Johannes Sixt <j6t@kdbg.org>
 316 ------------
 317
 318 In principle, a note is a regular Git blob, and any kind of
 319 (non-)format is accepted.  You can binary-safely create notes from
 320 arbitrary files using 'git hash-object':
 321
 322 ------------
 323 $ cc *.c
 324 $ blob=$(git hash-object -w a.out)
 325 $ git notes --ref=built add --allow-empty -C "$blob" HEAD
 326 ------------
 327
 328 (You cannot simply use `git notes --ref=built add -F a.out HEAD`
 329 because that is not binary-safe.)
 330 Of course, it doesn't make much sense to display non-text-format notes
 331 with 'git log', so if you use such notes, you'll probably need to write
 332 some special-purpose tools to do something useful with them.
 333
 334
 335 [[CONFIGURATION]]
 336 CONFIGURATION
 337 -------------
 338
 339 core.notesRef::
 340         Notes ref to read and manipulate instead of
 341         `refs/notes/commits`.  Must be an unabbreviated ref name.
 342         This setting can be overridden through the environment and
 343         command line.
 344
 345 include::includes/cmd-config-section-rest.txt[]
 346
 347 include::config/notes.txt[]
 348
 349
 350 ENVIRONMENT
 351 -----------
 352
 353 `GIT_NOTES_REF`::
 354         Which ref to manipulate notes from, instead of `refs/notes/commits`.
 355         This overrides the `core.notesRef` setting.
 356
 357 `GIT_NOTES_DISPLAY_REF`::
 358         Colon-delimited list of refs or globs indicating which refs,
 359         in addition to the default from `core.notesRef` or
 360         `GIT_NOTES_REF`, to read notes from when showing commit
 361         messages.
 362         This overrides the `notes.displayRef` setting.
 363 +
 364 A warning will be issued for refs that do not exist, but a glob that
 365 does not match any refs is silently ignored.
 366
 367 `GIT_NOTES_REWRITE_MODE`::
 368         When copying notes during a rewrite, what to do if the target
 369         commit already has a note.
 370         Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
 371         This overrides the `core.rewriteMode` setting.
 372
 373 `GIT_NOTES_REWRITE_REF`::
 374         When rewriting commits, which notes to copy from the original
 375         to the rewritten commit.  Must be a colon-delimited list of
 376         refs or globs.
 377 +
 378 If not set in the environment, the list of notes to copy depends
 379 on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
 380
 381 GIT
 382 ---
 383 Part of the linkgit:git[1] suite