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. 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 The (fully qualified) refname from which to show notes when 200 showing commit messages. The value of this variable can be set 201 to a glob, in which case notes from all matching refs will be 202 shown. You may also specify this configuration variable 203 several times. A warning will be issued for refs that do not 204 exist, but a glob that does not match any refs is silently 205 ignored. 206+ 207This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` 208environment variable, which must be a colon separated list of refs or 209globs. 210+ 211The effective value of "core.notesRef" (possibly overridden by 212GIT_NOTES_REF) is also implicitly added to the list of refs to be 213displayed. 214 215notes.rewrite.<command>:: 216 When rewriting commits with <command> (currently `amend` or 217 `rebase`) and this variable is set to `true`, git 218 automatically copies your notes from the original to the 219 rewritten commit. Defaults to `true`, but see 220 "notes.rewriteRef" below. 221 222notes.rewriteMode:: 223 When copying notes during a rewrite (see the 224 "notes.rewrite.<command>" option), determines what to do if 225 the target commit already has a note. Must be one of 226 `overwrite`, `concatenate`, or `ignore`. Defaults to 227 `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. The ref may be a 235 glob, in which case notes in all matching refs will be copied. 236 You may also specify this configuration several times. 237+ 238Does not have a default value; you must configure this variable to 239enable note rewriting. 240+ 241This setting can be overridden with the `GIT_NOTES_REWRITE_REF` 242environment variable, which must be a colon separated list of refs or 243globs. 244 245 246ENVIRONMENT 247----------- 248 249'GIT_NOTES_REF':: 250 Which ref to manipulate notes from, instead of `refs/notes/commits`. 251 This overrides the `core.notesRef` setting. 252 253 254Author 255------ 256Written by Johannes Schindelin <johannes.schindelin@gmx.de> and 257Johan Herland <johan@herland.net> 258 259Documentation 260------------- 261Documentation by Johannes Schindelin and Johan Herland 262 263GIT 264--- 265Part of the linkgit:git[7] suite