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