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