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