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