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", "union" and "cat_sort_uniq". 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"cat_sort_uniq" is similar to "union", but in addition to concatenating 234the local and remote versions, this strategy also sorts the resulting 235lines, and removes duplicate lines from the result. This is equivalent 236to applying the "cat | sort | uniq" shell pipeline to the local and 237remote versions. This strategy is useful if the notes follow a line-based 238format where one wants to avoid duplicated lines in the merge result. 239Note that if either the local or remote version contain duplicate lines 240prior to the merge, these will also be removed by this notes merge 241strategy. 242 243 244EXAMPLES 245-------- 246 247You can use notes to add annotations with information that was not 248available at the time a commit was written. 249 250------------ 251$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 252$ git show -s 72a144e 253[...] 254 Signed-off-by: Junio C Hamano <gitster@pobox.com> 255 256Notes: 257 Tested-by: Johannes Sixt <j6t@kdbg.org> 258------------ 259 260In principle, a note is a regular Git blob, and any kind of 261(non-)format is accepted. You can binary-safely create notes from 262arbitrary files using 'git hash-object': 263 264------------ 265$ cc *.c 266$ blob=$(git hash-object -w a.out) 267$ git notes --ref=built add -C "$blob" HEAD 268------------ 269 270Of course, it doesn't make much sense to display non-text-format notes 271with 'git log', so if you use such notes, you'll probably need to write 272some special-purpose tools to do something useful with them. 273 274 275CONFIGURATION 276------------- 277 278core.notesRef:: 279 Notes ref to read and manipulate instead of 280 `refs/notes/commits`. Must be an unabbreviated ref name. 281 This setting can be overridden through the environment and 282 command line. 283 284notes.displayRef:: 285 Which ref (or refs, if a glob or specified more than once), in 286 addition to the default set by `core.notesRef` or 287 'GIT_NOTES_REF', to read notes from when showing commit 288 messages with the 'git log' family of commands. 289 This setting can be overridden on the command line or by the 290 'GIT_NOTES_DISPLAY_REF' environment variable. 291 See linkgit:git-log[1]. 292 293notes.rewrite.<command>:: 294 When rewriting commits with <command> (currently `amend` or 295 `rebase`), if this variable is `false`, git will not copy 296 notes from the original to the rewritten commit. Defaults to 297 `true`. See also "`notes.rewriteRef`" below. 298+ 299This setting can be overridden by the 'GIT_NOTES_REWRITE_REF' 300environment variable. 301 302notes.rewriteMode:: 303 When copying notes during a rewrite, what to do if the target 304 commit already has a note. Must be one of `overwrite`, 305 `concatenate`, and `ignore`. Defaults to `concatenate`. 306+ 307This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` 308environment variable. 309 310notes.rewriteRef:: 311 When copying notes during a rewrite, specifies the (fully 312 qualified) ref whose notes should be copied. May be a glob, 313 in which case notes in all matching refs will be copied. You 314 may also specify this configuration several times. 315+ 316Does not have a default value; you must configure this variable to 317enable note rewriting. 318+ 319Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. 320 321 322ENVIRONMENT 323----------- 324 325'GIT_NOTES_REF':: 326 Which ref to manipulate notes from, instead of `refs/notes/commits`. 327 This overrides the `core.notesRef` setting. 328 329'GIT_NOTES_DISPLAY_REF':: 330 Colon-delimited list of refs or globs indicating which refs, 331 in addition to the default from `core.notesRef` or 332 'GIT_NOTES_REF', to read notes from when showing commit 333 messages. 334 This overrides the `notes.displayRef` setting. 335+ 336A warning will be issued for refs that do not exist, but a glob that 337does not match any refs is silently ignored. 338 339'GIT_NOTES_REWRITE_MODE':: 340 When copying notes during a rewrite, what to do if the target 341 commit already has a note. 342 Must be one of `overwrite`, `concatenate`, and `ignore`. 343 This overrides the `core.rewriteMode` setting. 344 345'GIT_NOTES_REWRITE_REF':: 346 When rewriting commits, which notes to copy from the original 347 to the rewritten commit. Must be a colon-delimited list of 348 refs or globs. 349+ 350If not set in the environment, the list of notes to copy depends 351on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. 352 353 354Author 355------ 356Written by Johannes Schindelin <johannes.schindelin@gmx.de> and 357Johan Herland <johan@herland.net> 358 359Documentation 360------------- 361Documentation by Johannes Schindelin and Johan Herland 362 363GIT 364--- 365Part of the linkgit:git[7] suite