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