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 Do not remove anything; just report the object names whose notes 133 would be removed. 134 135-v:: 136 Report all object names whose notes are removed. 137 138 139DISCUSSION 140---------- 141 142Commit notes are blobs containing extra information about an object 143(usually information to supplement a commit's message). These blobs 144are taken from notes refs. A notes ref is usually a branch which 145contains "files" whose paths are the object names for the objects 146they describe, with some directory separators included for performance 147reasons footnote:[Permitted pathnames have the form 148'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory 149names of two hexadecimal digits each followed by a filename with the 150rest of the object ID.]. 151 152Every notes change creates a new commit at the specified notes ref. 153You can therefore inspect the history of the notes by invoking, e.g., 154`git log -p notes/commits`. Currently the commit message only records 155which operation triggered the update, and the commit authorship is 156determined according to the usual rules (see linkgit:git-commit[1]). 157These details may change in the future. 158 159It is also permitted for a notes ref to point directly to a tree 160object, in which case the history of the notes can be read with 161`git log -p -g <refname>`. 162 163 164EXAMPLES 165-------- 166 167You can use notes to add annotations with information that was not 168available at the time a commit was written. 169 170------------ 171$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 172$ git show -s 72a144e 173[...] 174 Signed-off-by: Junio C Hamano <gitster@pobox.com> 175 176Notes: 177 Tested-by: Johannes Sixt <j6t@kdbg.org> 178------------ 179 180In principle, a note is a regular Git blob, and any kind of 181(non-)format is accepted. You can binary-safely create notes from 182arbitrary files using 'git hash-object': 183 184------------ 185$ cc *.c 186$ blob=$(git hash-object -w a.out) 187$ git notes --ref=built add -C "$blob" HEAD 188------------ 189 190Of course, it doesn't make much sense to display non-text-format notes 191with 'git log', so if you use such notes, you'll probably need to write 192some special-purpose tools to do something useful with them. 193 194 195CONFIGURATION 196------------- 197 198core.notesRef:: 199 Notes ref to read and manipulate instead of 200 `refs/notes/commits`. Must be an unabbreviated ref name. 201 This setting can be overridden through the environment and 202 command line. 203 204notes.displayRef:: 205 Which ref (or refs, if a glob or specified more than once), in 206 addition to the default set by `core.notesRef` or 207 'GIT_NOTES_REF', to read notes from when showing commit 208 messages with the 'git log' family of commands. 209 This setting can be overridden on the command line or by the 210 'GIT_NOTES_DISPLAY_REF' environment variable. 211 See linkgit:git-log[1]. 212 213notes.rewrite.<command>:: 214 When rewriting commits with <command> (currently `amend` or 215 `rebase`), if this variable is `false`, git will not copy 216 notes from the original to the rewritten commit. Defaults to 217 `true`. See also "`notes.rewriteRef`" below. 218+ 219This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' 220environment variable. 221 222notes.rewriteMode:: 223 When copying notes during a rewrite, what to do if the target 224 commit already has a note. Must be one of `overwrite`, 225 `concatenate`, and `ignore`. Defaults to `concatenate`. 226+ 227This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` 228environment variable. 229 230notes.rewriteRef:: 231 When copying notes during a rewrite, specifies the (fully 232 qualified) ref whose notes should be copied. May be a glob, 233 in which case notes in all matching refs will be copied. You 234 may also specify this configuration several times. 235+ 236Does not have a default value; you must configure this variable to 237enable note rewriting. 238+ 239Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. 240 241 242ENVIRONMENT 243----------- 244 245'GIT_NOTES_REF':: 246 Which ref to manipulate notes from, instead of `refs/notes/commits`. 247 This overrides the `core.notesRef` setting. 248 249'GIT_NOTES_DISPLAY_REF':: 250 Colon-delimited list of refs or globs indicating which refs, 251 in addition to the default from `core.notesRef` or 252 'GIT_NOTES_REF', to read notes from when showing commit 253 messages. 254 This overrides the `notes.displayRef` setting. 255+ 256A warning will be issued for refs that do not exist, but a glob that 257does not match any refs is silently ignored. 258 259'GIT_NOTES_REWRITE_MODE':: 260 When copying notes during a rewrite, what to do if the target 261 commit already has a note. 262 Must be one of `overwrite`, `concatenate`, and `ignore`. 263 This overrides the `core.rewriteMode` setting. 264 265'GIT_NOTES_REWRITE_REF':: 266 When rewriting commits, which notes to copy from the original 267 to the rewritten commit. Must be a colon-delimited list of 268 refs or globs. 269+ 270If not set in the environment, the list of notes to copy depends 271on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. 272 273 274Author 275------ 276Written by Johannes Schindelin <johannes.schindelin@gmx.de> and 277Johan Herland <johan@herland.net> 278 279Documentation 280------------- 281Documentation by Johannes Schindelin and Johan Herland 282 283GIT 284--- 285Part of the linkgit:git[7] suite