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