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