'\" t .\" Title: git-notes .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 2025-06-15 .\" Manual: Git Manual .\" Source: Git 2.50.0 .\" Language: English .\" .TH "GIT\-NOTES" "1" "2025\-06\-15" "Git 2\&.50\&.0" "Git Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" git-notes \- Add or inspect object notes .SH "SYNOPSIS" .sp .nf \fBgit\fR \fBnotes\fR [\fBlist\fR [\fI\fR]] \fBgit\fR \fBnotes\fR \fBadd\fR [\fB\-f\fR] [\fB\-\-allow\-empty\fR] [\fB\-\-\fR[\fBno\-\fR]\fBseparator\fR | \fB\-\-separator=\fR\fI\fR] [\fB\-\-\fR[\fBno\-\fR]\fBstripspace\fR] [\fB\-F\fR \fI\fR | \fB\-m\fR \fI\fR | (\fB\-c\fR | \fB\-C\fR) \fI\fR] [\fB\-e\fR] [\fI\fR] \fBgit\fR \fBnotes\fR \fBcopy\fR [\fB\-f\fR] ( \fB\-\-stdin\fR | \fI\fR [\fI\fR] ) \fBgit\fR \fBnotes\fR \fBappend\fR [\fB\-\-allow\-empty\fR] [\fB\-\-\fR[\fBno\-\fR]\fBseparator\fR | \fB\-\-separator=\fR\fI\fR] [\fB\-\-\fR[\fBno\-\fR]\fBstripspace\fR] [\fB\-F\fR \fI\fR | \fB\-m\fR \fI\fR | (\fB\-c\fR | \fB\-C\fR) \fI\fR] [\fB\-e\fR] [\fI\fR] \fBgit\fR \fBnotes\fR \fBedit\fR [\fB\-\-allow\-empty\fR] [\fI\fR] [\fB\-\-\fR[\fBno\-\fR]\fBstripspace\fR] \fBgit\fR \fBnotes\fR \fBshow\fR [\fI\fR] \fBgit\fR \fBnotes\fR \fBmerge\fR [\fB\-v\fR | \fB\-q\fR] [\fB\-s\fR \fI\fR ] \fI\fR \fBgit\fR \fBnotes\fR \fBmerge\fR \fB\-\-commit\fR [\fB\-v\fR | \fB\-q\fR] \fBgit\fR \fBnotes\fR \fBmerge\fR \fB\-\-abort\fR [\fB\-v\fR | \fB\-q\fR] \fBgit\fR \fBnotes\fR \fBremove\fR [\fB\-\-ignore\-missing\fR] [\fB\-\-stdin\fR] [\fI\fR\&...] \fBgit\fR \fBnotes\fR \fBprune\fR [\fB\-n\fR] [\fB\-v\fR] \fBgit\fR \fBnotes\fR \fBget\-ref\fR .fi .sp .SH "DESCRIPTION" .sp Adds, removes, or reads notes attached to objects, without touching the objects themselves\&. .sp By default, notes are saved to and read from \fBrefs/notes/commits\fR, but this default can be overridden\&. See the OPTIONS, CONFIGURATION, and ENVIRONMENT sections below\&. If this ref does not exist, it will be quietly created when it is first needed to store a note\&. .sp A typical use of notes is to supplement a commit message without changing the commit itself\&. Notes can be shown by \fBgit\fR \fBlog\fR along with the original commit message\&. To distinguish these notes from the message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes (\fI\fR):" (or "Notes:" for \fBrefs/notes/commits\fR)\&. .sp Notes can also be added to patches prepared with \fBgit\fR \fBformat\-patch\fR by using the \fB\-\-notes\fR option\&. Such notes are added as a patch commentary after a three dash separator line\&. .sp To change which notes are shown by \fBgit\fR \fBlog\fR, see the \fBnotes\&.displayRef\fR discussion in CONFIGURATION\&. .sp See the \fBnotes\&.rewrite\&.\fR\fI\fR configuration for a way to carry notes across commands that rewrite commits\&. .SH "SUBCOMMANDS" .PP \fBlist\fR .RS 4 List the notes object for a given object\&. If no object is given, show a list of all note objects and the objects they annotate (in the format "\fI\fR \fI\fR")\&. This is the default subcommand if no subcommand is given\&. .RE .PP \fBadd\fR .RS 4 Add notes for a given object (defaults to \fBHEAD\fR)\&. Abort if the object already has notes (use \fB\-f\fR to overwrite existing notes)\&. However, if you\(cqre using \fBadd\fR interactively (using an editor to supply the notes contents), then \- instead of aborting \- the existing notes will be opened in the editor (like the \fBedit\fR subcommand)\&. If you specify multiple \fB\-m\fR and \fB\-F\fR, a blank line will be inserted between the messages\&. Use the \fB\-\-separator\fR option to insert other delimiters\&. You can use \fB\-e\fR to edit and fine\-tune the message(s) supplied from \fB\-m\fR and \fB\-F\fR options interactively (using an editor) before adding the note\&. .RE .PP \fBcopy\fR .RS 4 Copy the notes for the first object onto the second object (defaults to \fBHEAD\fR)\&. Abort if the second object already has notes, or if the first object has none (use \fB\-f\fR to overwrite existing notes to the second object)\&. This subcommand is equivalent to: \fBgit\fR \fBnotes\fR \fBadd\fR [\fB\-f\fR] \fB\-C\fR \fB$\fR(\fBgit\fR \fBnotes\fR \fBlist\fR \fI\fR) \fI\fR .sp In \fB\-\-stdin\fR mode, take lines in the format .sp .if n \{\ .RS 4 .\} .nf SP [ SP ] LF .fi .if n \{\ .RE .\} .sp on standard input, and copy the notes from each \fI\fR to its corresponding \fI\fR\&. (The optional \fI\fR is ignored so that the command can read the input given to the \fBpost\-rewrite\fR hook\&.) .sp \fB\-\-stdin\fR cannot be combined with object names given on the command line\&. .RE .PP \fBappend\fR .RS 4 Append new message(s) given by \fB\-m\fR or \fB\-F\fR options to an existing note, or add them as a new note if one does not exist, for the object (defaults to \fBHEAD\fR)\&. When appending to an existing note, a blank line is added before each new message as an inter\-paragraph separator\&. The separator can be customized with the \fB\-\-separator\fR option\&. Edit the notes to be appended given by \fB\-m\fR and \fB\-F\fR options with \fB\-e\fR interactively (using an editor) before appending the note\&. .RE .PP \fBedit\fR .RS 4 Edit the notes for a given object (defaults to \fBHEAD\fR)\&. .RE .PP \fBshow\fR .RS 4 Show the notes for a given object (defaults to \fBHEAD\fR)\&. .RE .PP \fBmerge\fR .RS 4 Merge the given notes ref into the current notes ref\&. This will try to merge the changes made by the given notes ref (called "remote") since the merge\-base (if any) into the current notes ref (called "local")\&. .sp If conflicts arise and a strategy for automatically resolving conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given, the \fBmanual\fR resolver is used\&. This resolver checks out the conflicting notes in a special worktree (\fB\&.git/NOTES_MERGE_WORKTREE\fR), and instructs the user to manually resolve the conflicts there\&. When done, the user can either finalize the merge with \fBgit\fR \fBnotes\fR \fBmerge\fR \fB\-\-commit\fR, or abort the merge with \fBgit\fR \fBnotes\fR \fBmerge\fR \fB\-\-abort\fR\&. .RE .PP \fBremove\fR .RS 4 Remove the notes for given objects (defaults to \fBHEAD\fR)\&. When giving zero or one object from the command line, this is equivalent to specifying an empty note message to the \fBedit\fR subcommand\&. .sp In \fB\-\-stdin\fR mode, also remove the object names given on standard input\&. In other words, \fB\-\-stdin\fR can be combined with object names from the command line\&. .RE .PP \fBprune\fR .RS 4 Remove all notes for non\-existing/unreachable objects\&. .RE .PP \fBget\-ref\fR .RS 4 Print the current notes ref\&. This provides an easy way to retrieve the current notes ref (e\&.g\&. from scripts)\&. .RE .SH "OPTIONS" .PP \fB\-f\fR, \fB\-\-force\fR .RS 4 When adding notes to an object that already has notes, overwrite the existing notes (instead of aborting)\&. .RE .PP \fB\-m\fR \fI\fR, \fB\-\-message=\fR\fI\fR .RS 4 Use the given note message (instead of prompting)\&. If multiple \fB\-m\fR options are given, their values are concatenated as separate paragraphs\&. .RE .PP \fB\-F\fR \fI\fR, \fB\-\-file=\fR\fI\fR .RS 4 Take the note message from the given file\&. Use \fB\-\fR to read the note message from the standard input\&. .RE .PP \fB\-C\fR \fI\fR, \fB\-\-reuse\-message=\fR\fI\fR .RS 4 Take the given blob object (for example, another note) as the note message\&. (Use \fBgit\fR \fBnotes\fR \fBcopy\fR \fI\fR instead to copy notes between objects\&.) Implies \fB\-\-no\-stripspace\fR since the default behavior is to copy the message verbatim\&. .RE .PP \fB\-c\fR \fI\fR, \fB\-\-reedit\-message=\fR\fI\fR .RS 4 Like \fB\-C\fR, but with \fB\-c\fR the editor is invoked, so that the user can further edit the note message\&. .RE .PP \fB\-\-allow\-empty\fR .RS 4 Allow an empty note object to be stored\&. The default behavior is to automatically remove empty notes\&. .RE .PP \fB\-\-separator=\fR\fI\fR, \fB\-\-separator\fR, \fB\-\-no\-separator\fR .RS 4 Specify a string used as a custom inter\-paragraph separator (a newline is added at the end as needed)\&. If \fB\-\-no\-separator\fR, no separators will be added between paragraphs\&. Defaults to a blank line\&. .RE .PP \fB\-\-stripspace\fR, \fB\-\-no\-stripspace\fR .RS 4 Clean up whitespace\&. Specifically (see \fBgit-stripspace\fR(1)): .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} remove trailing whitespace from all lines .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} collapse multiple consecutive empty lines into one empty line .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} remove empty lines from the beginning and end of the input .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} add a missing \fB\en\fR to the last line if necessary\&. .RE .sp \fB\-\-stripspace\fR is the default except for \fB\-C\fR/\fB\-\-reuse\-message\fR\&. However, keep in mind that this depends on the order of similar options\&. For example, for \fB\-C\fR \fI\fR \fB\-m\fR\fI\fR, \fB\-\-stripspace\fR will be used because the default for \fB\-m\fR overrides the previous \fB\-C\fR\&. This is a known limitation that may be fixed in the future\&. .RE .PP \fB\-\-ref=\fR\fI\fR .RS 4 Manipulate the notes tree in \fI\fR\&. This overrides \fBGIT_NOTES_REF\fR and the \fBcore\&.notesRef\fR configuration\&. The ref specifies the full refname when it begins with \fBrefs/notes/\fR; when it begins with \fBnotes/\fR, \fBrefs/\fR and otherwise \fBrefs/notes/\fR is prefixed to form a full name of the ref\&. .RE .PP \fB\-\-ignore\-missing\fR .RS 4 Do not consider it an error to request removing notes from an object that does not have notes attached to it\&. .RE .PP \fB\-\-stdin\fR .RS 4 Only valid for \fBremove\fR and \fBcopy\fR\&. See the respective subcommands\&. .RE .PP \fB\-n\fR, \fB\-\-dry\-run\fR .RS 4 Do not remove anything; just report the object names whose notes would be removed\&. .RE .PP \fB\-s\fR \fI\fR, \fB\-\-strategy=\fR\fI\fR .RS 4 When merging notes, resolve notes conflicts using the given strategy\&. The following strategies are recognized: \fBmanual\fR (default), \fBours\fR, \fBtheirs\fR, \fBunion\fR and \fBcat_sort_uniq\fR\&. This option overrides the \fBnotes\&.mergeStrategy\fR configuration setting\&. See the "NOTES MERGE STRATEGIES" section below for more information on each notes merge strategy\&. .RE .PP \fB\-\-commit\fR .RS 4 Finalize an in\-progress \fBgit\fR \fBnotes\fR \fBmerge\fR\&. Use this option when you have resolved the conflicts that \fBgit\fR \fBnotes\fR \fBmerge\fR stored in \fB\&.git/NOTES_MERGE_WORKTREE\fR\&. This amends the partial merge commit created by \fBgit\fR \fBnotes\fR \fBmerge\fR (stored in \fB\&.git/NOTES_MERGE_PARTIAL\fR) by adding the notes in \fB\&.git/NOTES_MERGE_WORKTREE\fR\&. The notes ref stored in the \fB\&.git/NOTES_MERGE_REF\fR symref is updated to the resulting commit\&. .RE .PP \fB\-\-abort\fR .RS 4 Abort/reset an in\-progress \fBgit\fR \fBnotes\fR \fBmerge\fR, i\&.e\&. a notes merge with conflicts\&. This simply removes all files related to the notes merge\&. .RE .PP \fB\-q\fR, \fB\-\-quiet\fR .RS 4 When merging notes, operate quietly\&. .RE .PP \fB\-v\fR, \fB\-\-verbose\fR .RS 4 When merging notes, be more verbose\&. When pruning notes, report all object names whose notes are removed\&. .RE .SH "DISCUSSION" .sp Commit notes are blobs containing extra information about an object (usually information to supplement a commit\(cqs message)\&. These blobs are taken from notes refs\&. A notes ref is usually a branch which contains "files" whose paths are the object names for the objects they describe, with some directory separators included for performance reasons \&\s-2\u[1]\d\s+2\&. .sp Every notes change creates a new commit at the specified notes ref\&. You can therefore inspect the history of the notes by invoking, e\&.g\&., \fBgit\fR \fBlog\fR \fB\-p\fR \fBnotes/commits\fR\&. Currently the commit message only records which operation triggered the update, and the commit authorship is determined according to the usual rules (see \fBgit-commit\fR(1))\&. These details may change in the future\&. .sp It is also permitted for a notes ref to point directly to a tree object, in which case the history of the notes can be read with \fBgit\fR \fBlog\fR \fB\-p\fR \fB\-g\fR \fI\fR\&. .SH "NOTES MERGE STRATEGIES" .sp The default notes merge strategy is \fBmanual\fR, which checks out conflicting notes in a special work tree for resolving notes conflicts (\fB\&.git/NOTES_MERGE_WORKTREE\fR), and instructs the user to resolve the conflicts in that work tree\&. When done, the user can either finalize the merge with \fBgit\fR \fBnotes\fR \fBmerge\fR \fB\-\-commit\fR, or abort the merge with \fBgit\fR \fBnotes\fR \fBmerge\fR \fB\-\-abort\fR\&. .sp Users may select an automated merge strategy from among the following using either \fB\-s\fR/\fB\-\-strategy\fR option or configuring \fBnotes\&.mergeStrategy\fR accordingly: .sp \fBours\fR automatically resolves conflicting notes in favor of the local version (i\&.e\&. the current notes ref)\&. .sp \fBtheirs\fR automatically resolves notes conflicts in favor of the remote version (i\&.e\&. the given notes ref being merged into the current notes ref)\&. .sp \fBunion\fR automatically resolves notes conflicts by concatenating the local and remote versions\&. .sp \fBcat_sort_uniq\fR is similar to \fBunion\fR, but in addition to concatenating the local and remote versions, this strategy also sorts the resulting lines, and removes duplicate lines from the result\&. This is equivalent to applying the "cat | sort | uniq" shell pipeline to the local and remote versions\&. This strategy is useful if the notes follow a line\-based format where one wants to avoid duplicated lines in the merge result\&. Note that if either the local or remote version contain duplicate lines prior to the merge, these will also be removed by this notes merge strategy\&. .SH "EXAMPLES" .sp You can use notes to add annotations with information that was not available at the time a commit was written\&. .sp .if n \{\ .RS 4 .\} .nf $ git notes add \-m \*(AqTested\-by: Johannes Sixt \*(Aq 72a144e2 $ git show \-s 72a144e [\&.\&.\&.] Signed\-off\-by: Junio C Hamano Notes: Tested\-by: Johannes Sixt .fi .if n \{\ .RE .\} .sp .sp In principle, a note is a regular Git blob, and any kind of (non\-)format is accepted\&. You can binary\-safely create notes from arbitrary files using \fBgit\fR \fBhash\-object\fR: .sp .if n \{\ .RS 4 .\} .nf $ cc *\&.c $ blob=$(git hash\-object \-w a\&.out) $ git notes \-\-ref=built add \-\-allow\-empty \-C "$blob" HEAD .fi .if n \{\ .RE .\} .sp .sp (You cannot simply use \fBgit\fR \fBnotes\fR \fB\-\-ref=built\fR \fBadd\fR \fB\-F\fR \fBa\&.out\fR \fBHEAD\fR because that is not binary\-safe\&.) Of course, it doesn\(cqt make much sense to display non\-text\-format notes with \fBgit\fR \fBlog\fR, so if you use such notes, you\(cqll probably need to write some special\-purpose tools to do something useful with them\&. .SH "CONFIGURATION" .PP \fBcore\&.notesRef\fR .RS 4 Notes ref to read and manipulate instead of \fBrefs/notes/commits\fR\&. Must be an unabbreviated ref name\&. This setting can be overridden through the environment and command line\&. .RE .sp Everything above this line in this section isn\(cqt included from the \fBgit-config\fR(1) documentation\&. The content that follows is the same as what\(cqs found there: .PP \fBnotes\&.mergeStrategy\fR .RS 4 Which merge strategy to choose by default when resolving notes conflicts\&. Must be one of \fBmanual\fR, \fBours\fR, \fBtheirs\fR, \fBunion\fR, or \fBcat_sort_uniq\fR\&. Defaults to \fBmanual\fR\&. See the "NOTES MERGE STRATEGIES" section of \fBgit-notes\fR(1) for more information on each strategy\&. .sp This setting can be overridden by passing the \fB\-\-strategy\fR option to \fBgit-notes\fR(1)\&. .RE .PP \fBnotes\&.\fR\fI\fR\fB\&.mergeStrategy\fR .RS 4 Which merge strategy to choose when doing a notes merge into \fBrefs/notes/\fR\fI\fR\&. This overrides the more general \fBnotes\&.mergeStrategy\fR\&. See the "NOTES MERGE STRATEGIES" section in \fBgit-notes\fR(1) for more information on the available strategies\&. .RE .PP \fBnotes\&.displayRef\fR .RS 4 Which ref (or refs, if a glob or specified more than once), in addition to the default set by \fBcore\&.notesRef\fR or \fBGIT_NOTES_REF\fR, to read notes from when showing commit messages with the \fBgit\fR \fBlog\fR family of commands\&. .sp This setting can be overridden with the \fBGIT_NOTES_DISPLAY_REF\fR environment variable, which must be a colon separated list of refs or globs\&. .sp A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored\&. .sp This setting can be disabled by the \fB\-\-no\-notes\fR option to the \fBgit-log\fR(1) family of commands, or by the \fB\-\-notes=\fR\fI\fR option accepted by those commands\&. .sp The effective value of \fBcore\&.notesRef\fR (possibly overridden by \fBGIT_NOTES_REF\fR) is also implicitly added to the list of refs to be displayed\&. .RE .PP \fBnotes\&.rewrite\&.\fR\fI\fR .RS 4 When rewriting commits with \fI\fR (currently \fBamend\fR or \fBrebase\fR), if this variable is \fBfalse\fR, git will not copy notes from the original to the rewritten commit\&. Defaults to \fBtrue\fR\&. See also \fBnotes\&.rewriteRef\fR below\&. .sp This setting can be overridden with the \fBGIT_NOTES_REWRITE_REF\fR environment variable, which must be a colon separated list of refs or globs\&. .RE .PP \fBnotes\&.rewriteMode\fR .RS 4 When copying notes during a rewrite (see the \fBnotes\&.rewrite\&.\fR\fI\fR option), determines what to do if the target commit already has a note\&. Must be one of \fBoverwrite\fR, \fBconcatenate\fR, \fBcat_sort_uniq\fR, or \fBignore\fR\&. Defaults to \fBconcatenate\fR\&. .sp This setting can be overridden with the \fBGIT_NOTES_REWRITE_MODE\fR environment variable\&. .RE .PP \fBnotes\&.rewriteRef\fR .RS 4 When copying notes during a rewrite, specifies the (fully qualified) ref whose notes should be copied\&. May be a glob, in which case notes in all matching refs will be copied\&. You may also specify this configuration several times\&. .sp Does not have a default value; you must configure this variable to enable note rewriting\&. Set it to \fBrefs/notes/commits\fR to enable rewriting for the default commit notes\&. .sp Can be overridden with the \fBGIT_NOTES_REWRITE_REF\fR environment variable\&. See \fBnotes\&.rewrite\&.\fR\fI\fR above for a further description of its format\&. .RE .SH "ENVIRONMENT" .PP \fBGIT_NOTES_REF\fR .RS 4 Which ref to manipulate notes from, instead of \fBrefs/notes/commits\fR\&. This overrides the \fBcore\&.notesRef\fR setting\&. .RE .PP \fBGIT_NOTES_DISPLAY_REF\fR .RS 4 Colon\-delimited list of refs or globs indicating which refs, in addition to the default from \fBcore\&.notesRef\fR or \fBGIT_NOTES_REF\fR, to read notes from when showing commit messages\&. This overrides the \fBnotes\&.displayRef\fR setting\&. .sp A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored\&. .RE .PP \fBGIT_NOTES_REWRITE_MODE\fR .RS 4 When copying notes during a rewrite, what to do if the target commit already has a note\&. Must be one of \fBoverwrite\fR, \fBconcatenate\fR, \fBcat_sort_uniq\fR, or \fBignore\fR\&. This overrides the \fBcore\&.rewriteMode\fR setting\&. .RE .PP \fBGIT_NOTES_REWRITE_REF\fR .RS 4 When rewriting commits, which notes to copy from the original to the rewritten commit\&. Must be a colon\-delimited list of refs or globs\&. .sp If not set in the environment, the list of notes to copy depends on the \fBnotes\&.rewrite\&.\fR\fI\fR and \fBnotes\&.rewriteRef\fR settings\&. .RE .SH "GIT" .sp Part of the \fBgit\fR(1) suite .SH "NOTES" .IP " 1." 4 Permitted pathnames have the form \fIbf\fR\fB/\fR\fIfe\fR\fB/\fR\fI30\fR\fB/\fR\fI\&...\fR\fB/\fR\fI680d5a\&...\fR: a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID.