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