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 186Author 187------ 188Written by Johannes Schindelin <johannes.schindelin@gmx.de> and 189Johan Herland <johan@herland.net> 190 191Documentation 192------------- 193Documentation by Johannes Schindelin and Johan Herland 194 195GIT 196--- 197Part of the linkgit:git[7] suite