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' remove [<object>]
  19 'git notes' prune [-n | -v]
  20
  21
  22 DESCRIPTION
  23 -----------
  24 Adds, removes, or reads notes attached to objects, without touching
  25 the objects themselves.
  26
  27 By default, notes are saved to and read from `refs/notes/commits`, but
  28 this default can be overridden.  See the OPTIONS, CONFIGURATION, and
  29 ENVIRONMENT sections below.  If this ref does not exist, it will be
  30 quietly created when it is first needed to store a note.
  31
  32 A typical use of notes is to supplement a commit message without
  33 changing the commit itself. Notes can be shown by 'git log' along with
  34 the original commit message. To distinguish these notes from the
  35 message stored in the commit object, the notes are indented like the
  36 message, after an unindented line saying "Notes (<refname>):" (or
  37 "Notes:" for `refs/notes/commits`).
  38
  39 To change which notes are shown by 'git log', see the
  40 "notes.displayRef" configuration in linkgit:git-log[1].
  41
  42 See the "notes.rewrite.<command>" configuration for a way to carry
  43 notes across commands that rewrite commits.
  44
  45
  46 SUBCOMMANDS
  47 -----------
  48
  49 list::
  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
  55 add::
  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
  60 copy::
  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 +
  67 In `\--stdin` mode, take lines in the format
  68 +
  69 ----------
  70 <from-object> SP <to-object> [ SP <rest> ] LF
  71 ----------
  72 +
  73 on standard input, and copy the notes from each <from-object> to its
  74 corresponding <to-object>.  (The optional `<rest>` is ignored so that
  75 the command can read the input given to the `post-rewrite` hook.)
  76
  77 append::
  78         Append to the notes of an existing object (defaults to HEAD).
  79         Creates a new notes object if needed.
  80
  81 edit::
  82         Edit the notes for a given object (defaults to HEAD).
  83
  84 show::
  85         Show the notes for a given object (defaults to HEAD).
  86
  87 merge::
  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 +
  93 If conflicts arise and a strategy for automatically resolving
  94 conflicting notes (see the -s/--strategy option) is not given,
  95 the "manual" resolver is used. This resolver checks out the
  96 conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),
  97 and instructs the user to manually resolve the conflicts there.
  98
  99 remove::
 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
 104 prune::
 105         Remove all notes for non-existing/unreachable objects.
 106
 107 OPTIONS
 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
 168 DISCUSSION
 169 ----------
 170
 171 Commit notes are blobs containing extra information about an object
 172 (usually information to supplement a commit's message).  These blobs
 173 are taken from notes refs.  A notes ref is usually a branch which
 174 contains "files" whose paths are the object names for the objects
 175 they describe, with some directory separators included for performance
 176 reasons footnote:[Permitted pathnames have the form
 177 'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
 178 names of two hexadecimal digits each followed by a filename with the
 179 rest of the object ID.].
 180
 181 Every notes change creates a new commit at the specified notes ref.
 182 You can therefore inspect the history of the notes by invoking, e.g.,
 183 `git log -p notes/commits`.  Currently the commit message only records
 184 which operation triggered the update, and the commit authorship is
 185 determined according to the usual rules (see linkgit:git-commit[1]).
 186 These details may change in the future.
 187
 188 It is also permitted for a notes ref to point directly to a tree
 189 object, in which case the history of the notes can be read with
 190 `git log -p -g <refname>`.
 191
 192
 193 NOTES MERGE STRATEGIES
 194 ----------------------
 195
 196 The default notes merge strategy is "manual", which checks out
 197 conflicting notes in a special work tree for resolving notes conflicts
 198 (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the
 199 conflicts in that work tree.
 200
 201 "ours" automatically resolves conflicting notes in favor of the local
 202 version (i.e. the current notes ref).
 203
 204 "theirs" automatically resolves notes conflicts in favor of the remote
 205 version (i.e. the given notes ref being merged into the current notes
 206 ref).
 207
 208 "union" automatically resolves notes conflicts by concatenating the
 209 local and remote versions.
 210
 211
 212 EXAMPLES
 213 --------
 214
 215 You can use notes to add annotations with information that was not
 216 available 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
 224 Notes:
 225     Tested-by: Johannes Sixt <j6t@kdbg.org>
 226 ------------
 227
 228 In principle, a note is a regular Git blob, and any kind of
 229 (non-)format is accepted.  You can binary-safely create notes from
 230 arbitrary 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
 238 Of course, it doesn't make much sense to display non-text-format notes
 239 with 'git log', so if you use such notes, you'll probably need to write
 240 some special-purpose tools to do something useful with them.
 241
 242
 243 CONFIGURATION
 244 -------------
 245
 246 core.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
 252 notes.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
 261 notes.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 +
 267 This setting can be overridden by the 'GIT_NOTES_REWRITE_REF'
 268 environment variable.
 269
 270 notes.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 +
 275 This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
 276 environment variable.
 277
 278 notes.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 +
 284 Does not have a default value; you must configure this variable to
 285 enable note rewriting.
 286 +
 287 Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.
 288
 289
 290 ENVIRONMENT
 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 +
 304 A warning will be issued for refs that do not exist, but a glob that
 305 does 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 +
 318 If not set in the environment, the list of notes to copy depends
 319 on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
 320
 321
 322 Author
 323 ------
 324 Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
 325 Johan Herland <johan@herland.net>
 326
 327 Documentation
 328 -------------
 329 Documentation by Johannes Schindelin and Johan Herland
 330
 331 GIT
 332 ---
 333 Part of the linkgit:git[7] suite