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 given blob object (for example, another note) as the
 146         note message. (Use `git notes copy <object>` instead to
 147         copy notes between objects.)
 148
 149 -c <object>::
 150 --reedit-message=<object>::
 151         Like '-C', but with '-c' the editor is invoked, so that
 152         the user can further edit the note message.
 153
 154 --ref <ref>::
 155         Manipulate the notes tree in <ref>.  This overrides
 156         'GIT_NOTES_REF' and the "core.notesRef" configuration.  The ref
 157         is taken to be in `refs/notes/` if it is not qualified.
 158
 159 --ignore-missing::
 160         Do not consider it an error to request removing notes from an
 161         object that does not have notes attached to it.
 162
 163 --stdin::
 164         Also read the object names to remove notes from from the standard
 165         input (there is no reason you cannot combine this with object
 166         names from the command line).
 167
 168 -n::
 169 --dry-run::
 170         Do not remove anything; just report the object names whose notes
 171         would be removed.
 172
 173 -s <strategy>::
 174 --strategy=<strategy>::
 175         When merging notes, resolve notes conflicts using the given
 176         strategy. The following strategies are recognized: "manual"
 177         (default), "ours", "theirs", "union" and "cat_sort_uniq".
 178         See the "NOTES MERGE STRATEGIES" section below for more
 179         information on each notes merge strategy.
 180
 181 --commit::
 182         Finalize an in-progress 'git notes merge'. Use this option
 183         when you have resolved the conflicts that 'git notes merge'
 184         stored in .git/NOTES_MERGE_WORKTREE. This amends the partial
 185         merge commit created by 'git notes merge' (stored in
 186         .git/NOTES_MERGE_PARTIAL) by adding the notes in
 187         .git/NOTES_MERGE_WORKTREE. The notes ref stored in the
 188         .git/NOTES_MERGE_REF symref is updated to the resulting commit.
 189
 190 --abort::
 191         Abort/reset a in-progress 'git notes merge', i.e. a notes merge
 192         with conflicts. This simply removes all files related to the
 193         notes merge.
 194
 195 -q::
 196 --quiet::
 197         When merging notes, operate quietly.
 198
 199 -v::
 200 --verbose::
 201         When merging notes, be more verbose.
 202         When pruning notes, report all object names whose notes are
 203         removed.
 204
 205
 206 DISCUSSION
 207 ----------
 208
 209 Commit notes are blobs containing extra information about an object
 210 (usually information to supplement a commit's message).  These blobs
 211 are taken from notes refs.  A notes ref is usually a branch which
 212 contains "files" whose paths are the object names for the objects
 213 they describe, with some directory separators included for performance
 214 reasons footnote:[Permitted pathnames have the form
 215 'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
 216 names of two hexadecimal digits each followed by a filename with the
 217 rest of the object ID.].
 218
 219 Every notes change creates a new commit at the specified notes ref.
 220 You can therefore inspect the history of the notes by invoking, e.g.,
 221 `git log -p notes/commits`.  Currently the commit message only records
 222 which operation triggered the update, and the commit authorship is
 223 determined according to the usual rules (see linkgit:git-commit[1]).
 224 These details may change in the future.
 225
 226 It is also permitted for a notes ref to point directly to a tree
 227 object, in which case the history of the notes can be read with
 228 `git log -p -g <refname>`.
 229
 230
 231 NOTES MERGE STRATEGIES
 232 ----------------------
 233
 234 The default notes merge strategy is "manual", which checks out
 235 conflicting notes in a special work tree for resolving notes conflicts
 236 (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the
 237 conflicts in that work tree.
 238 When done, the user can either finalize the merge with
 239 'git notes merge --commit', or abort the merge with
 240 'git notes merge --abort'.
 241
 242 "ours" automatically resolves conflicting notes in favor of the local
 243 version (i.e. the current notes ref).
 244
 245 "theirs" automatically resolves notes conflicts in favor of the remote
 246 version (i.e. the given notes ref being merged into the current notes
 247 ref).
 248
 249 "union" automatically resolves notes conflicts by concatenating the
 250 local and remote versions.
 251
 252 "cat_sort_uniq" is similar to "union", but in addition to concatenating
 253 the local and remote versions, this strategy also sorts the resulting
 254 lines, and removes duplicate lines from the result. This is equivalent
 255 to applying the "cat | sort | uniq" shell pipeline to the local and
 256 remote versions. This strategy is useful if the notes follow a line-based
 257 format where one wants to avoid duplicated lines in the merge result.
 258 Note that if either the local or remote version contain duplicate lines
 259 prior to the merge, these will also be removed by this notes merge
 260 strategy.
 261
 262
 263 EXAMPLES
 264 --------
 265
 266 You can use notes to add annotations with information that was not
 267 available at the time a commit was written.
 268
 269 ------------
 270 $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
 271 $ git show -s 72a144e
 272 [...]
 273     Signed-off-by: Junio C Hamano <gitster@pobox.com>
 274
 275 Notes:
 276     Tested-by: Johannes Sixt <j6t@kdbg.org>
 277 ------------
 278
 279 In principle, a note is a regular Git blob, and any kind of
 280 (non-)format is accepted.  You can binary-safely create notes from
 281 arbitrary files using 'git hash-object':
 282
 283 ------------
 284 $ cc *.c
 285 $ blob=$(git hash-object -w a.out)
 286 $ git notes --ref=built add -C "$blob" HEAD
 287 ------------
 288
 289 (You cannot simply use `git notes --ref=built add -F a.out HEAD`
 290 because that is not binary-safe.)
 291 Of course, it doesn't make much sense to display non-text-format notes
 292 with 'git log', so if you use such notes, you'll probably need to write
 293 some special-purpose tools to do something useful with them.
 294
 295
 296 CONFIGURATION
 297 -------------
 298
 299 core.notesRef::
 300         Notes ref to read and manipulate instead of
 301         `refs/notes/commits`.  Must be an unabbreviated ref name.
 302         This setting can be overridden through the environment and
 303         command line.
 304
 305 notes.displayRef::
 306         Which ref (or refs, if a glob or specified more than once), in
 307         addition to the default set by `core.notesRef` or
 308         'GIT_NOTES_REF', to read notes from when showing commit
 309         messages with the 'git log' family of commands.
 310         This setting can be overridden on the command line or by the
 311         'GIT_NOTES_DISPLAY_REF' environment variable.
 312         See linkgit:git-log[1].
 313
 314 notes.rewrite.<command>::
 315         When rewriting commits with <command> (currently `amend` or
 316         `rebase`), if this variable is `false`, git will not copy
 317         notes from the original to the rewritten commit.  Defaults to
 318         `true`.  See also "`notes.rewriteRef`" below.
 319 +
 320 This setting can be overridden by the 'GIT_NOTES_REWRITE_REF'
 321 environment variable.
 322
 323 notes.rewriteMode::
 324         When copying notes during a rewrite, what to do if the target
 325         commit already has a note.  Must be one of `overwrite`,
 326         `concatenate`, and `ignore`.  Defaults to `concatenate`.
 327 +
 328 This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
 329 environment variable.
 330
 331 notes.rewriteRef::
 332         When copying notes during a rewrite, specifies the (fully
 333         qualified) ref whose notes should be copied.  May be a glob,
 334         in which case notes in all matching refs will be copied.  You
 335         may also specify this configuration several times.
 336 +
 337 Does not have a default value; you must configure this variable to
 338 enable note rewriting.
 339 +
 340 Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.
 341
 342
 343 ENVIRONMENT
 344 -----------
 345
 346 'GIT_NOTES_REF'::
 347         Which ref to manipulate notes from, instead of `refs/notes/commits`.
 348         This overrides the `core.notesRef` setting.
 349
 350 'GIT_NOTES_DISPLAY_REF'::
 351         Colon-delimited list of refs or globs indicating which refs,
 352         in addition to the default from `core.notesRef` or
 353         'GIT_NOTES_REF', to read notes from when showing commit
 354         messages.
 355         This overrides the `notes.displayRef` setting.
 356 +
 357 A warning will be issued for refs that do not exist, but a glob that
 358 does not match any refs is silently ignored.
 359
 360 'GIT_NOTES_REWRITE_MODE'::
 361         When copying notes during a rewrite, what to do if the target
 362         commit already has a note.
 363         Must be one of `overwrite`, `concatenate`, and `ignore`.
 364         This overrides the `core.rewriteMode` setting.
 365
 366 'GIT_NOTES_REWRITE_REF'::
 367         When rewriting commits, which notes to copy from the original
 368         to the rewritten commit.  Must be a colon-delimited list of
 369         refs or globs.
 370 +
 371 If not set in the environment, the list of notes to copy depends
 372 on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
 373
 374
 375 Author
 376 ------
 377 Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
 378 Johan Herland <johan@herland.net>
 379
 380 Documentation
 381 -------------
 382 Documentation by Johannes Schindelin and Johan Herland
 383
 384 GIT
 385 ---
 386 Part of the linkgit:git[7] suite