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 26A typical use of notes is to extend a commit message without having 27to change the commit itself. Such commit notes can be shown by `git log` 28along with the original commit message. To discern these notes from the 29message stored in the commit object, the notes are indented like the 30message, after an unindented line saying "Notes (<refname>):" (or 31"Notes:" for `refs/notes/commits`). 32 33This command always manipulates the notes specified in "core.notesRef" 34(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF. 35To change which notes are shown by 'git-log', see the 36"notes.displayRef" configuration. 37 38See the description of "notes.rewrite.<command>" in 39linkgit:git-config[1] for a way of carrying your notes across commands 40that rewrite commits. 41 42 43SUBCOMMANDS 44----------- 45 46list:: 47 List the notes object for a given object. If no object is 48 given, show a list of all note objects and the objects they 49 annotate (in the format "<note object> <annotated object>"). 50 This is the default subcommand if no subcommand is given. 51 52add:: 53 Add notes for a given object (defaults to HEAD). Abort if the 54 object already has notes (use `-f` to overwrite an 55 existing note). 56 57copy:: 58 Copy the notes for the first object onto the second object. 59 Abort if the second object already has notes, or if the first 60 object has none (use -f to overwrite existing notes to the 61 second object). This subcommand is equivalent to: 62 `git notes add [-f] -C $(git notes list <from-object>) <to-object>` 63+ 64In `\--stdin` mode, take lines in the format 65+ 66---------- 67<from-object> SP <to-object> [ SP <rest> ] LF 68---------- 69+ 70on standard input, and copy the notes from each <from-object> to its 71corresponding <to-object>. (The optional `<rest>` is ignored so that 72the command can read the input given to the `post-rewrite` hook.) 73 74append:: 75 Append to the notes of an existing object (defaults to HEAD). 76 Creates a new notes object if needed. 77 78edit:: 79 Edit the notes for a given object (defaults to HEAD). 80 81show:: 82 Show the notes for a given object (defaults to HEAD). 83 84remove:: 85 Remove the notes for a given object (defaults to HEAD). 86 This is equivalent to specifying an empty note message to 87 the `edit` subcommand. 88 89prune:: 90 Remove all notes for non-existing/unreachable objects. 91 92OPTIONS 93------- 94-f:: 95--force:: 96 When adding notes to an object that already has notes, 97 overwrite the existing notes (instead of aborting). 98 99-m <msg>:: 100--message=<msg>:: 101 Use the given note message (instead of prompting). 102 If multiple `-m` options are given, their values 103 are concatenated as separate paragraphs. 104 Lines starting with `#` and empty lines other than a 105 single line between paragraphs will be stripped out. 106 107-F <file>:: 108--file=<file>:: 109 Take the note message from the given file. Use '-' to 110 read the note message from the standard input. 111 Lines starting with `#` and empty lines other than a 112 single line between paragraphs will be stripped out. 113 114-C <object>:: 115--reuse-message=<object>:: 116 Take the note message from the given blob object (for 117 example, another note). 118 119-c <object>:: 120--reedit-message=<object>:: 121 Like '-C', but with '-c' the editor is invoked, so that 122 the user can further edit the note message. 123 124--ref <ref>:: 125 Manipulate the notes tree in <ref>. This overrides both 126 GIT_NOTES_REF and the "core.notesRef" configuration. The ref 127 is taken to be in `refs/notes/` if it is not qualified. 128 129 130DISCUSSION 131---------- 132 133Commit notes are blobs containing extra information about an object 134(usually information to supplement a commit's message). These blobs 135are taken from notes refs. A notes ref is usually a branch which 136contains "files" whose paths are the object names for the objects 137they describe, with some directory separators included for performance 138reasons footnote:[Permitted pathnames have the form 139'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory 140names of two hexadecimal digits each followed by a filename with the 141rest of the object ID.]. 142 143Every notes change creates a new commit at the specified notes ref. 144You can therefore inspect the history of the notes by invoking, e.g., 145`git log -p notes/commits`. Currently the commit message only records 146which operation triggered the update, and the commit authorship is 147determined according to the usual rules (see linkgit:git-commit[1]). 148These details may change in the future. 149 150It is also permitted for a notes ref to point directly to a tree 151object, in which case the history of the notes can be read with 152`git log -p -g <refname>`. 153 154 155EXAMPLES 156-------- 157 158You can use notes to add annotations with information that was not 159available at the time a commit was written. 160 161------------ 162$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 163$ git show -s 72a144e 164[...] 165 Signed-off-by: Junio C Hamano <gitster@pobox.com> 166 167Notes: 168 Tested-by: Johannes Sixt <j6t@kdbg.org> 169------------ 170 171In principle, a note is a regular Git blob, and any kind of 172(non-)format is accepted. You can binary-safely create notes from 173arbitrary files using 'git hash-object': 174 175------------ 176$ cc *.c 177$ blob=$(git hash-object -w a.out) 178$ git notes --ref=built add -C "$blob" HEAD 179------------ 180 181Of course, it doesn't make much sense to display non-text-format notes 182with 'git log', so if you use such notes, you'll probably need to write 183some special-purpose tools to do something useful with them. 184 185 186CONFIGURATION 187------------- 188 189core.notesRef:: 190 When showing commit messages, also show notes which are stored in 191 the given ref. The ref must be fully qualified. If the given 192 ref does not exist, it is not an error but means that no 193 notes should be printed. 194+ 195This setting defaults to "refs/notes/commits", and it can be overridden by 196the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1]. 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 245Author 246------ 247Written by Johannes Schindelin <johannes.schindelin@gmx.de> and 248Johan Herland <johan@herland.net> 249 250Documentation 251------------- 252Documentation by Johannes Schindelin and Johan Herland 253 254GIT 255--- 256Part of the linkgit:git[7] suite