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