| 1 | git-notes(1) |
| 2 | ============ |
| 3 | |
| 4 | NAME |
| 5 | ---- |
| 6 | git-notes - Add or inspect object notes |
| 7 | |
| 8 | SYNOPSIS |
| 9 | -------- |
| 10 | [synopsis] |
| 11 | git notes [list [<object>]] |
| 12 | git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>] |
| 13 | git notes copy [-f] ( --stdin | <from-object> [<to-object>] ) |
| 14 | git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>] |
| 15 | git notes edit [--allow-empty] [<object>] [--[no-]stripspace] |
| 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 [--ignore-missing] [--stdin] [<object>...] |
| 21 | git notes prune [-n] [-v] |
| 22 | git notes get-ref |
| 23 | |
| 24 | |
| 25 | DESCRIPTION |
| 26 | ----------- |
| 27 | Adds, removes, or reads notes attached to objects, without touching |
| 28 | the objects themselves. |
| 29 | |
| 30 | By default, notes are saved to and read from `refs/notes/commits`, but |
| 31 | this default can be overridden. See the OPTIONS, CONFIGURATION, and |
| 32 | ENVIRONMENT sections below. If this ref does not exist, it will be |
| 33 | quietly created when it is first needed to store a note. |
| 34 | |
| 35 | A typical use of notes is to supplement a commit message without |
| 36 | changing the commit itself. Notes can be shown by `git log` along with |
| 37 | the original commit message. To distinguish these notes from the |
| 38 | message stored in the commit object, the notes are indented like the |
| 39 | message, after an unindented line saying "Notes (_<refname>_):" (or |
| 40 | "Notes:" for `refs/notes/commits`). |
| 41 | |
| 42 | Notes can also be added to patches prepared with `git format-patch` by |
| 43 | using the `--notes` option. Such notes are added as a patch commentary |
| 44 | after a three dash separator line. |
| 45 | |
| 46 | To change which notes are shown by `git log`, see the |
| 47 | `notes.displayRef` discussion in <<CONFIGURATION,CONFIGURATION>>. |
| 48 | |
| 49 | See the `notes.rewrite.<command>` configuration for a way to carry |
| 50 | notes across commands that rewrite commits. |
| 51 | |
| 52 | |
| 53 | SUBCOMMANDS |
| 54 | ----------- |
| 55 | |
| 56 | `list`:: |
| 57 | List the notes object for a given object. If no object is |
| 58 | given, show a list of all note objects and the objects they |
| 59 | annotate (in the format "`<note-object> <annotated-object>`"). |
| 60 | This is the default subcommand if no subcommand is given. |
| 61 | |
| 62 | `add`:: |
| 63 | Add notes for a given object (defaults to `HEAD`). Abort if the |
| 64 | object already has notes (use `-f` to overwrite existing notes). |
| 65 | However, if you're using `add` interactively (using an editor |
| 66 | to supply the notes contents), then - instead of aborting - |
| 67 | the existing notes will be opened in the editor (like the `edit` |
| 68 | subcommand). If you specify multiple `-m` and `-F`, a blank |
| 69 | line will be inserted between the messages. Use the `--separator` |
| 70 | option to insert other delimiters. You can use `-e` to edit and |
| 71 | fine-tune the message(s) supplied from `-m` and `-F` options |
| 72 | interactively (using an editor) before adding the note. |
| 73 | |
| 74 | `copy`:: |
| 75 | Copy the notes for the first object onto the second object (defaults to |
| 76 | `HEAD`). Abort if the second object already has notes, or if the first |
| 77 | object has none (use `-f` to overwrite existing notes to the |
| 78 | second object). This subcommand is equivalent to: |
| 79 | `git notes add [-f] -C $(git notes list <from-object>) <to-object>` |
| 80 | + |
| 81 | In `--stdin` mode, take lines in the format |
| 82 | + |
| 83 | ---------- |
| 84 | <from-object> SP <to-object> [ SP <rest> ] LF |
| 85 | ---------- |
| 86 | + |
| 87 | on standard input, and copy the notes from each _<from-object>_ to its |
| 88 | corresponding _<to-object>_. (The optional _<rest>_ is ignored so that |
| 89 | the command can read the input given to the `post-rewrite` hook.) |
| 90 | + |
| 91 | `--stdin` cannot be combined with object names given on the command |
| 92 | line. |
| 93 | |
| 94 | `append`:: |
| 95 | Append new message(s) given by `-m` or `-F` options to an |
| 96 | existing note, or add them as a new note if one does not |
| 97 | exist, for the object (defaults to `HEAD`). When appending to |
| 98 | an existing note, a blank line is added before each new |
| 99 | message as an inter-paragraph separator. The separator can |
| 100 | be customized with the `--separator` option. |
| 101 | Edit the notes to be appended given by `-m` and `-F` options with |
| 102 | `-e` interactively (using an editor) before appending the note. |
| 103 | |
| 104 | `edit`:: |
| 105 | Edit the notes for a given object (defaults to `HEAD`). |
| 106 | |
| 107 | `show`:: |
| 108 | Show the notes for a given object (defaults to `HEAD`). |
| 109 | |
| 110 | `merge`:: |
| 111 | Merge the given notes ref into the current notes ref. |
| 112 | This will try to merge the changes made by the given |
| 113 | notes ref (called "remote") since the merge-base (if |
| 114 | any) into the current notes ref (called "local"). |
| 115 | + |
| 116 | If conflicts arise and a strategy for automatically resolving |
| 117 | conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given, |
| 118 | the `manual` resolver is used. This resolver checks out the |
| 119 | conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`), |
| 120 | and instructs the user to manually resolve the conflicts there. |
| 121 | When done, the user can either finalize the merge with |
| 122 | `git notes merge --commit`, or abort the merge with |
| 123 | `git notes merge --abort`. |
| 124 | |
| 125 | `remove`:: |
| 126 | Remove the notes for given objects (defaults to `HEAD`). When |
| 127 | giving zero or one object from the command line, this is |
| 128 | equivalent to specifying an empty note message to |
| 129 | the `edit` subcommand. |
| 130 | + |
| 131 | In `--stdin` mode, also remove the object names given on standard |
| 132 | input. In other words, `--stdin` can be combined with object names from |
| 133 | the command line. |
| 134 | |
| 135 | `prune`:: |
| 136 | Remove all notes for non-existing/unreachable objects. |
| 137 | |
| 138 | `get-ref`:: |
| 139 | Print the current notes ref. This provides an easy way to |
| 140 | retrieve the current notes ref (e.g. from scripts). |
| 141 | |
| 142 | OPTIONS |
| 143 | ------- |
| 144 | `-f`:: |
| 145 | `--force`:: |
| 146 | When adding notes to an object that already has notes, |
| 147 | overwrite the existing notes (instead of aborting). |
| 148 | |
| 149 | `-m <msg>`:: |
| 150 | `--message=<msg>`:: |
| 151 | Use the given note message (instead of prompting). |
| 152 | If multiple `-m` options are given, their values |
| 153 | are concatenated as separate paragraphs. |
| 154 | |
| 155 | `-F <file>`:: |
| 156 | `--file=<file>`:: |
| 157 | Take the note message from the given file. Use `-` to |
| 158 | read the note message from the standard input. |
| 159 | |
| 160 | `-C <object>`:: |
| 161 | `--reuse-message=<object>`:: |
| 162 | Take the given blob object (for example, another note) as the |
| 163 | note message. (Use `git notes copy <object>` instead to |
| 164 | copy notes between objects.) Implies `--no-stripspace` since |
| 165 | the default behavior is to copy the message verbatim. |
| 166 | |
| 167 | `-c <object>`:: |
| 168 | `--reedit-message=<object>`:: |
| 169 | Like `-C`, but with `-c` the editor is invoked, so that |
| 170 | the user can further edit the note message. |
| 171 | |
| 172 | `--allow-empty`:: |
| 173 | Allow an empty note object to be stored. The default behavior is |
| 174 | to automatically remove empty notes. |
| 175 | |
| 176 | `--separator=<paragraph-break>`:: |
| 177 | `--separator`:: |
| 178 | `--no-separator`:: |
| 179 | Specify a string used as a custom inter-paragraph separator |
| 180 | (a newline is added at the end as needed). If `--no-separator`, no |
| 181 | separators will be added between paragraphs. Defaults to a blank |
| 182 | line. |
| 183 | |
| 184 | `--stripspace`:: |
| 185 | `--no-stripspace`:: |
| 186 | Clean up whitespace. Specifically (see |
| 187 | linkgit:git-stripspace[1]): |
| 188 | + |
| 189 | -- |
| 190 | - remove trailing whitespace from all lines |
| 191 | - collapse multiple consecutive empty lines into one empty line |
| 192 | - remove empty lines from the beginning and end of the input |
| 193 | - add a missing `\n` to the last line if necessary. |
| 194 | -- |
| 195 | + |
| 196 | `--stripspace` is the default except for |
| 197 | `-C`/`--reuse-message`. However, keep in mind that this depends on the |
| 198 | order of similar options. For example, for `-C <object> -m<message>`, |
| 199 | `--stripspace` will be used because the default for `-m` overrides the |
| 200 | previous `-C`. This is a known limitation that may be fixed in the |
| 201 | future. |
| 202 | |
| 203 | `--ref=<ref>`:: |
| 204 | Manipulate the notes tree in _<ref>_. This overrides |
| 205 | `GIT_NOTES_REF` and the `core.notesRef` configuration. The ref |
| 206 | specifies the full refname when it begins with `refs/notes/`; when it |
| 207 | begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed |
| 208 | to form a full name of the ref. |
| 209 | |
| 210 | `--ignore-missing`:: |
| 211 | Do not consider it an error to request removing notes from an |
| 212 | object that does not have notes attached to it. |
| 213 | |
| 214 | `--stdin`:: |
| 215 | Only valid for `remove` and `copy`. See the respective subcommands. |
| 216 | |
| 217 | `-n`:: |
| 218 | `--dry-run`:: |
| 219 | Do not remove anything; just report the object names whose notes |
| 220 | would be removed. |
| 221 | |
| 222 | `-s <strategy>`:: |
| 223 | `--strategy=<strategy>`:: |
| 224 | When merging notes, resolve notes conflicts using the given |
| 225 | strategy. The following strategies are recognized: `manual` |
| 226 | (default), `ours`, `theirs`, `union` and `cat_sort_uniq`. |
| 227 | This option overrides the `notes.mergeStrategy` configuration setting. |
| 228 | See the "NOTES MERGE STRATEGIES" section below for more |
| 229 | information on each notes merge strategy. |
| 230 | |
| 231 | `--commit`:: |
| 232 | Finalize an in-progress `git notes merge`. Use this option |
| 233 | when you have resolved the conflicts that `git notes merge` |
| 234 | stored in `.git/NOTES_MERGE_WORKTREE`. This amends the partial |
| 235 | merge commit created by `git notes merge` (stored in |
| 236 | `.git/NOTES_MERGE_PARTIAL`) by adding the notes in |
| 237 | `.git/NOTES_MERGE_WORKTREE`. The notes ref stored in the |
| 238 | `.git/NOTES_MERGE_REF` symref is updated to the resulting commit. |
| 239 | |
| 240 | `--abort`:: |
| 241 | Abort/reset an in-progress `git notes merge`, i.e. a notes merge |
| 242 | with conflicts. This simply removes all files related to the |
| 243 | notes merge. |
| 244 | |
| 245 | `-q`:: |
| 246 | `--quiet`:: |
| 247 | When merging notes, operate quietly. |
| 248 | |
| 249 | `-v`:: |
| 250 | `--verbose`:: |
| 251 | When merging notes, be more verbose. |
| 252 | When pruning notes, report all object names whose notes are |
| 253 | removed. |
| 254 | |
| 255 | |
| 256 | DISCUSSION |
| 257 | ---------- |
| 258 | |
| 259 | Commit notes are blobs containing extra information about an object |
| 260 | (usually information to supplement a commit's message). These blobs |
| 261 | are taken from notes refs. A notes ref is usually a branch which |
| 262 | contains "files" whose paths are the object names for the objects |
| 263 | they describe, with some directory separators included for performance |
| 264 | reasons footnote:[Permitted pathnames have the form |
| 265 | 'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': a sequence of directory |
| 266 | names of two hexadecimal digits each followed by a filename with the |
| 267 | rest of the object ID.]. |
| 268 | |
| 269 | Every notes change creates a new commit at the specified notes ref. |
| 270 | You can therefore inspect the history of the notes by invoking, e.g., |
| 271 | `git log -p notes/commits`. Currently the commit message only records |
| 272 | which operation triggered the update, and the commit authorship is |
| 273 | determined according to the usual rules (see linkgit:git-commit[1]). |
| 274 | These details may change in the future. |
| 275 | |
| 276 | It is also permitted for a notes ref to point directly to a tree |
| 277 | object, in which case the history of the notes can be read with |
| 278 | `git log -p -g <refname>`. |
| 279 | |
| 280 | |
| 281 | NOTES MERGE STRATEGIES |
| 282 | ---------------------- |
| 283 | |
| 284 | The default notes merge strategy is `manual`, which checks out |
| 285 | conflicting notes in a special work tree for resolving notes conflicts |
| 286 | (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the |
| 287 | conflicts in that work tree. |
| 288 | When done, the user can either finalize the merge with |
| 289 | `git notes merge --commit`, or abort the merge with |
| 290 | `git notes merge --abort`. |
| 291 | |
| 292 | Users may select an automated merge strategy from among the following using |
| 293 | either `-s`/`--strategy` option or configuring `notes.mergeStrategy` accordingly: |
| 294 | |
| 295 | `ours` automatically resolves conflicting notes in favor of the local |
| 296 | version (i.e. the current notes ref). |
| 297 | |
| 298 | `theirs` automatically resolves notes conflicts in favor of the remote |
| 299 | version (i.e. the given notes ref being merged into the current notes |
| 300 | ref). |
| 301 | |
| 302 | `union` automatically resolves notes conflicts by concatenating the |
| 303 | local and remote versions. |
| 304 | |
| 305 | `cat_sort_uniq` is similar to `union`, but in addition to concatenating |
| 306 | the local and remote versions, this strategy also sorts the resulting |
| 307 | lines, and removes duplicate lines from the result. This is equivalent |
| 308 | to applying the "cat | sort | uniq" shell pipeline to the local and |
| 309 | remote versions. This strategy is useful if the notes follow a line-based |
| 310 | format where one wants to avoid duplicated lines in the merge result. |
| 311 | Note that if either the local or remote version contain duplicate lines |
| 312 | prior to the merge, these will also be removed by this notes merge |
| 313 | strategy. |
| 314 | |
| 315 | |
| 316 | EXAMPLES |
| 317 | -------- |
| 318 | |
| 319 | You can use notes to add annotations with information that was not |
| 320 | available at the time a commit was written. |
| 321 | |
| 322 | ------------ |
| 323 | $ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 |
| 324 | $ git show -s 72a144e |
| 325 | [...] |
| 326 | Signed-off-by: Junio C Hamano <gitster@pobox.com> |
| 327 | |
| 328 | Notes: |
| 329 | Tested-by: Johannes Sixt <j6t@kdbg.org> |
| 330 | ------------ |
| 331 | |
| 332 | In principle, a note is a regular Git blob, and any kind of |
| 333 | (non-)format is accepted. You can binary-safely create notes from |
| 334 | arbitrary files using `git hash-object`: |
| 335 | |
| 336 | ------------ |
| 337 | $ cc *.c |
| 338 | $ blob=$(git hash-object -w a.out) |
| 339 | $ git notes --ref=built add --allow-empty -C "$blob" HEAD |
| 340 | ------------ |
| 341 | |
| 342 | (You cannot simply use `git notes --ref=built add -F a.out HEAD` |
| 343 | because that is not binary-safe.) |
| 344 | Of course, it doesn't make much sense to display non-text-format notes |
| 345 | with `git log`, so if you use such notes, you'll probably need to write |
| 346 | some special-purpose tools to do something useful with them. |
| 347 | |
| 348 | |
| 349 | [[CONFIGURATION]] |
| 350 | CONFIGURATION |
| 351 | ------------- |
| 352 | |
| 353 | `core.notesRef`:: |
| 354 | Notes ref to read and manipulate instead of |
| 355 | `refs/notes/commits`. Must be an unabbreviated ref name. |
| 356 | This setting can be overridden through the environment and |
| 357 | command line. |
| 358 | |
| 359 | include::includes/cmd-config-section-rest.adoc[] |
| 360 | |
| 361 | include::config/notes.adoc[] |
| 362 | |
| 363 | |
| 364 | ENVIRONMENT |
| 365 | ----------- |
| 366 | |
| 367 | `GIT_NOTES_REF`:: |
| 368 | Which ref to manipulate notes from, instead of `refs/notes/commits`. |
| 369 | This overrides the `core.notesRef` setting. |
| 370 | |
| 371 | `GIT_NOTES_DISPLAY_REF`:: |
| 372 | Colon-delimited list of refs or globs indicating which refs, |
| 373 | in addition to the default from `core.notesRef` or |
| 374 | `GIT_NOTES_REF`, to read notes from when showing commit |
| 375 | messages. |
| 376 | This overrides the `notes.displayRef` setting. |
| 377 | + |
| 378 | A warning will be issued for refs that do not exist, but a glob that |
| 379 | does not match any refs is silently ignored. |
| 380 | |
| 381 | `GIT_NOTES_REWRITE_MODE`:: |
| 382 | When copying notes during a rewrite, what to do if the target |
| 383 | commit already has a note. |
| 384 | Must be one of `overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`. |
| 385 | This overrides the `core.rewriteMode` setting. |
| 386 | |
| 387 | `GIT_NOTES_REWRITE_REF`:: |
| 388 | When rewriting commits, which notes to copy from the original |
| 389 | to the rewritten commit. Must be a colon-delimited list of |
| 390 | refs or globs. |
| 391 | + |
| 392 | If not set in the environment, the list of notes to copy depends |
| 393 | on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. |
| 394 | |
| 395 | GIT |
| 396 | --- |
| 397 | Part of the linkgit:git[1] suite |