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' merge [-v | -q] [-s <strategy> ] <notes_ref> 18'git notes' remove [<object>] 19'git notes' prune [-n | -v] 20 21 22DESCRIPTION 23----------- 24Adds, removes, or reads notes attached to objects, without touching 25the objects themselves. 26 27By default, notes are saved to and read from `refs/notes/commits`, but 28this default can be overridden. See the OPTIONS, CONFIGURATION, and 29ENVIRONMENT sections below. If this ref does not exist, it will be 30quietly created when it is first needed to store a note. 31 32A typical use of notes is to supplement a commit message without 33changing the commit itself. Notes can be shown by 'git log' along with 34the original commit message. To distinguish these notes from the 35message stored in the commit object, the notes are indented like the 36message, after an unindented line saying "Notes (<refname>):" (or 37"Notes:" for `refs/notes/commits`). 38 39To change which notes are shown by 'git log', see the 40"notes.displayRef" configuration in linkgit:git-log[1]. 41 42See the "notes.rewrite.<command>" configuration for a way to carry 43notes across commands that 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 87merge:: 88 Merge the given notes ref into the current notes ref. 89 This will try to merge the changes made by the given 90 notes ref (called "remote") since the merge-base (if 91 any) into the current notes ref (called "local"). 92+ 93If conflicts arise and a strategy for automatically resolving 94conflicting notes (see the -s/--strategy option) is not given, 95the merge fails (TODO). 96 97remove:: 98 Remove the notes for a given object (defaults to HEAD). 99 This is equivalent to specifying an empty note message to 100 the `edit` subcommand. 101 102prune:: 103 Remove all notes for non-existing/unreachable objects. 104 105OPTIONS 106------- 107-f:: 108--force:: 109 When adding notes to an object that already has notes, 110 overwrite the existing notes (instead of aborting). 111 112-m <msg>:: 113--message=<msg>:: 114 Use the given note message (instead of prompting). 115 If multiple `-m` options are given, their values 116 are concatenated as separate paragraphs. 117 Lines starting with `#` and empty lines other than a 118 single line between paragraphs will be stripped out. 119 120-F <file>:: 121--file=<file>:: 122 Take the note message from the given file. Use '-' to 123 read the note message from the standard input. 124 Lines starting with `#` and empty lines other than a 125 single line between paragraphs will be stripped out. 126 127-C <object>:: 128--reuse-message=<object>:: 129 Take the note message from the given blob object (for 130 example, another note). 131 132-c <object>:: 133--reedit-message=<object>:: 134 Like '-C', but with '-c' the editor is invoked, so that 135 the user can further edit the note message. 136 137--ref <ref>:: 138 Manipulate the notes tree in <ref>. This overrides 139 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref 140 is taken to be in `refs/notes/` if it is not qualified. 141 142-n:: 143--dry-run:: 144 Do not remove anything; just report the object names whose notes 145 would be removed. 146 147-s <strategy>:: 148--strategy=<strategy>:: 149 When merging notes, resolve notes conflicts using the given 150 strategy. The following strategies are recognized: "manual" 151 (default), "ours", "theirs" and "union". 152 See the "NOTES MERGE STRATEGIES" section below for more 153 information on each notes merge strategy. 154 155-q:: 156--quiet:: 157 When merging notes, operate quietly. 158 159-v:: 160--verbose:: 161 When merging notes, be more verbose. 162 When pruning notes, report all object names whose notes are 163 removed. 164 165 166DISCUSSION 167---------- 168 169Commit notes are blobs containing extra information about an object 170(usually information to supplement a commit's message). These blobs 171are taken from notes refs. A notes ref is usually a branch which 172contains "files" whose paths are the object names for the objects 173they describe, with some directory separators included for performance 174reasons footnote:[Permitted pathnames have the form 175'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory 176names of two hexadecimal digits each followed by a filename with the 177rest of the object ID.]. 178 179Every notes change creates a new commit at the specified notes ref. 180You can therefore inspect the history of the notes by invoking, e.g., 181`git log -p notes/commits`. Currently the commit message only records 182which operation triggered the update, and the commit authorship is 183determined according to the usual rules (see linkgit:git-commit[1]). 184These details may change in the future. 185 186It is also permitted for a notes ref to point directly to a tree 187object, in which case the history of the notes can be read with 188`git log -p -g <refname>`. 189 190 191NOTES MERGE STRATEGIES 192---------------------- 193 194The default notes merge strategy is "manual", which is not yet 195implemented (TODO). 196 197"ours" automatically resolves conflicting notes in favor of the local 198version (i.e. the current notes ref). 199 200"theirs" automatically resolves notes conflicts in favor of the remote 201version (i.e. the given notes ref being merged into the current notes 202ref). 203 204"union" automatically resolves notes conflicts by concatenating the 205local and remote versions. 206 207 208EXAMPLES 209-------- 210 211You can use notes to add annotations with information that was not 212available at the time a commit was written. 213 214------------ 215$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 216$ git show -s 72a144e 217[...] 218 Signed-off-by: Junio C Hamano <gitster@pobox.com> 219 220Notes: 221 Tested-by: Johannes Sixt <j6t@kdbg.org> 222------------ 223 224In principle, a note is a regular Git blob, and any kind of 225(non-)format is accepted. You can binary-safely create notes from 226arbitrary files using 'git hash-object': 227 228------------ 229$ cc *.c 230$ blob=$(git hash-object -w a.out) 231$ git notes --ref=built add -C "$blob" HEAD 232------------ 233 234Of course, it doesn't make much sense to display non-text-format notes 235with 'git log', so if you use such notes, you'll probably need to write 236some special-purpose tools to do something useful with them. 237 238 239CONFIGURATION 240------------- 241 242core.notesRef:: 243 Notes ref to read and manipulate instead of 244 `refs/notes/commits`. Must be an unabbreviated ref name. 245 This setting can be overridden through the environment and 246 command line. 247 248notes.displayRef:: 249 Which ref (or refs, if a glob or specified more than once), in 250 addition to the default set by `core.notesRef` or 251 'GIT_NOTES_REF', to read notes from when showing commit 252 messages with the 'git log' family of commands. 253 This setting can be overridden on the command line or by the 254 'GIT_NOTES_DISPLAY_REF' environment variable. 255 See linkgit:git-log[1]. 256 257notes.rewrite.<command>:: 258 When rewriting commits with <command> (currently `amend` or 259 `rebase`), if this variable is `false`, git will not copy 260 notes from the original to the rewritten commit. Defaults to 261 `true`. See also "`notes.rewriteRef`" below. 262+ 263This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' 264environment variable. 265 266notes.rewriteMode:: 267 When copying notes during a rewrite, what to do if the target 268 commit already has a note. Must be one of `overwrite`, 269 `concatenate`, and `ignore`. Defaults to `concatenate`. 270+ 271This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` 272environment variable. 273 274notes.rewriteRef:: 275 When copying notes during a rewrite, specifies the (fully 276 qualified) ref whose notes should be copied. May be a glob, 277 in which case notes in all matching refs will be copied. You 278 may also specify this configuration several times. 279+ 280Does not have a default value; you must configure this variable to 281enable note rewriting. 282+ 283Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. 284 285 286ENVIRONMENT 287----------- 288 289'GIT_NOTES_REF':: 290 Which ref to manipulate notes from, instead of `refs/notes/commits`. 291 This overrides the `core.notesRef` setting. 292 293'GIT_NOTES_DISPLAY_REF':: 294 Colon-delimited list of refs or globs indicating which refs, 295 in addition to the default from `core.notesRef` or 296 'GIT_NOTES_REF', to read notes from when showing commit 297 messages. 298 This overrides the `notes.displayRef` setting. 299+ 300A warning will be issued for refs that do not exist, but a glob that 301does not match any refs is silently ignored. 302 303'GIT_NOTES_REWRITE_MODE':: 304 When copying notes during a rewrite, what to do if the target 305 commit already has a note. 306 Must be one of `overwrite`, `concatenate`, and `ignore`. 307 This overrides the `core.rewriteMode` setting. 308 309'GIT_NOTES_REWRITE_REF':: 310 When rewriting commits, which notes to copy from the original 311 to the rewritten commit. Must be a colon-delimited list of 312 refs or globs. 313+ 314If not set in the environment, the list of notes to copy depends 315on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. 316 317 318Author 319------ 320Written by Johannes Schindelin <johannes.schindelin@gmx.de> and 321Johan Herland <johan@herland.net> 322 323Documentation 324------------- 325Documentation by Johannes Schindelin and Johan Herland 326 327GIT 328--- 329Part of the linkgit:git[7] suite