path: root/man1/git-notes.1

'\" t
.\"     Title: git-notes
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-10
.\"    Manual: Git Manual
.\"    Source: Git 2.44.0.568.g436d4e5b14
.\"  Language: English
.\"
.TH "GIT\-NOTES" "1" "2024\-04\-10" "Git 2\&.44\&.0\&.568\&.g436d4e" "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
\fIgit notes\fR [list [<object>]]
\fIgit notes\fR add [\-f] [\-\-allow\-empty] [\-\-[no\-]separator | \-\-separator=<paragraph\-break>] [\-\-[no\-]stripspace] [\-F <file> | \-m <msg> | (\-c | \-C) <object>] [<object>]
\fIgit notes\fR copy [\-f] ( \-\-stdin | <from\-object> [<to\-object>] )
\fIgit notes\fR append [\-\-allow\-empty] [\-\-[no\-]separator | \-\-separator=<paragraph\-break>] [\-\-[no\-]stripspace] [\-F <file> | \-m <msg> | (\-c | \-C) <object>] [<object>]
\fIgit notes\fR edit [\-\-allow\-empty] [<object>] [\-\-[no\-]stripspace]
\fIgit notes\fR show [<object>]
\fIgit notes\fR merge [\-v | \-q] [\-s <strategy> ] <notes\-ref>
\fIgit notes\fR merge \-\-commit [\-v | \-q]
\fIgit notes\fR merge \-\-abort [\-v | \-q]
\fIgit notes\fR remove [\-\-ignore\-missing] [\-\-stdin] [<object>\&...]
\fIgit notes\fR prune [\-n] [\-v]
\fIgit notes\fR get\-ref
.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 \fIgit log\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 (<refname>):" (or "Notes:" for \fBrefs/notes/commits\fR)\&.
.sp
Notes can also be added to patches prepared with \fBgit format\-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 \fIgit log\fR, see the "notes\&.displayRef" discussion in the section called \(lqCONFIGURATION\(rq\&.
.sp
See the "notes\&.rewrite\&.<command>" configuration for a way to carry notes across commands that rewrite commits\&.
.SH "SUBCOMMANDS"
.PP
list
.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 "<note\-object> <annotated\-object>")\&. This is the default subcommand if no subcommand is given\&.
.RE
.PP
add
.RS 4
Add notes for a given object (defaults to HEAD)\&. 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\&.
.RE
.PP
copy
.RS 4
Copy the notes for the first object onto the second object (defaults to HEAD)\&. Abort if the second object already has notes, or if the first object has none (use \-f to overwrite existing notes to the second object)\&. This subcommand is equivalent to:
\fBgit notes add [\-f] \-C $(git notes list <from\-object>) <to\-object>\fR
.sp
In
\fB\-\-stdin\fR
mode, take lines in the format
.sp
.if n \{\
.RS 4
.\}
.nf
<from\-object> SP <to\-object> [ SP <rest> ] LF
.fi
.if n \{\
.RE
.\}
.sp
on standard input, and copy the notes from each <from\-object> to its corresponding <to\-object>\&. (The optional
\fB<rest>\fR
is ignored so that the command can read the input given to the
\fBpost\-rewrite\fR
hook\&.)
.RE
.PP
append
.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 HEAD)\&. 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\&.
.RE
.PP
edit
.RS 4
Edit the notes for a given object (defaults to HEAD)\&.
.RE
.PP
show
.RS 4
Show the notes for a given object (defaults to HEAD)\&.
.RE
.PP
merge
.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 "manual" 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
\fIgit notes merge \-\-commit\fR, or abort the merge with
\fIgit notes merge \-\-abort\fR\&.
.RE
.PP
remove
.RS 4
Remove the notes for given objects (defaults to HEAD)\&. When giving zero or one object from the command line, this is equivalent to specifying an empty note message to the
\fBedit\fR
subcommand\&.
.RE
.PP
prune
.RS 4
Remove all notes for non\-existing/unreachable objects\&.
.RE
.PP
get\-ref
.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
\-f, \-\-force
.RS 4
When adding notes to an object that already has notes, overwrite the existing notes (instead of aborting)\&.
.RE
.PP
\-m <msg>, \-\-message=<msg>
.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\&. Lines starting with
\fB#\fR
and empty lines other than a single line between paragraphs will be stripped out\&. If you wish to keep them verbatim, use
\fB\-\-no\-stripspace\fR\&.
.RE
.PP
\-F <file>, \-\-file=<file>
.RS 4
Take the note message from the given file\&. Use
\fI\-\fR
to read the note message from the standard input\&. Lines starting with
\fB#\fR
and empty lines other than a single line between paragraphs will be stripped out\&. If you wish to keep them verbatim, use
\fB\-\-no\-stripspace\fR\&.
.RE
.PP
\-C <object>, \-\-reuse\-message=<object>
.RS 4
Take the given blob object (for example, another note) as the note message\&. (Use
\fBgit notes copy <object>\fR
instead to copy notes between objects\&.)\&. By default, message will be copied verbatim, but if you wish to strip out the lines starting with
\fB#\fR
and empty lines other than a single line between paragraphs, use with`\-\-stripspace` option\&.
.RE
.PP
\-c <object>, \-\-reedit\-message=<object>
.RS 4
Like
\fI\-C\fR, but with
\fB\-c\fR
the editor is invoked, so that the user can further edit the note message\&.
.RE
.PP
\-\-allow\-empty
.RS 4
Allow an empty note object to be stored\&. The default behavior is to automatically remove empty notes\&.
.RE
.PP
\-\-[no\-]separator, \-\-separator=<paragraph\-break>
.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
\-\-[no\-]stripspace
.RS 4
Strip leading and trailing whitespace from the note message\&. Also strip out empty lines other than a single line between paragraphs\&. Lines starting with
\fB#\fR
will be stripped out in non\-editor cases like
\fB\-m\fR,
\fB\-F\fR
and
\fB\-C\fR, but not in editor case like
\fBgit notes edit\fR,
\fB\-c\fR, etc\&.
.RE
.PP
\-\-ref <ref>
.RS 4
Manipulate the notes tree in <ref>\&. This overrides
\fBGIT_NOTES_REF\fR
and the "core\&.notesRef" 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
\-\-ignore\-missing
.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
\-\-stdin
.RS 4
Also read the object names to remove notes from the standard input (there is no reason you cannot combine this with object names from the command line)\&.
.RE
.PP
\-n, \-\-dry\-run
.RS 4
Do not remove anything; just report the object names whose notes would be removed\&.
.RE
.PP
\-s <strategy>, \-\-strategy=<strategy>
.RS 4
When merging notes, resolve notes conflicts using the given strategy\&. The following strategies are recognized: "manual" (default), "ours", "theirs", "union" and "cat_sort_uniq"\&. This option overrides the "notes\&.mergeStrategy" configuration setting\&. See the "NOTES MERGE STRATEGIES" section below for more information on each notes merge strategy\&.
.RE
.PP
\-\-commit
.RS 4
Finalize an in\-progress
\fIgit notes merge\fR\&. Use this option when you have resolved the conflicts that
\fIgit notes merge\fR
stored in \&.git/NOTES_MERGE_WORKTREE\&. This amends the partial merge commit created by
\fIgit notes merge\fR
(stored in \&.git/NOTES_MERGE_PARTIAL) by adding the notes in \&.git/NOTES_MERGE_WORKTREE\&. The notes ref stored in the \&.git/NOTES_MERGE_REF symref is updated to the resulting commit\&.
.RE
.PP
\-\-abort
.RS 4
Abort/reset an in\-progress
\fIgit notes merge\fR, i\&.e\&. a notes merge with conflicts\&. This simply removes all files related to the notes merge\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
When merging notes, operate quietly\&.
.RE
.PP
\-v, \-\-verbose
.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 log \-p notes/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 log \-p \-g <refname>\fR\&.
.SH "NOTES MERGE STRATEGIES"
.sp
The default notes merge strategy is "manual", 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 \fIgit notes merge \-\-commit\fR, or abort the merge with \fIgit notes merge \-\-abort\fR\&.
.sp
Users may select an automated merge strategy from among the following using either \-s/\-\-strategy option or configuring notes\&.mergeStrategy accordingly:
.sp
"ours" automatically resolves conflicting notes in favor of the local version (i\&.e\&. the current notes ref)\&.
.sp
"theirs" automatically resolves notes conflicts in favor of the remote version (i\&.e\&. the given notes ref being merged into the current notes ref)\&.
.sp
"union" automatically resolves notes conflicts by concatenating the local and remote versions\&.
.sp
"cat_sort_uniq" is similar to "union", 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 <j6t@kdbg\&.org>\*(Aq 72a144e2
$ git show \-s 72a144e
[\&.\&.\&.]
    Signed\-off\-by: Junio C Hamano <gitster@pobox\&.com>

Notes:
    Tested\-by: Johannes Sixt <j6t@kdbg\&.org>
.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 \fIgit hash\-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 notes \-\-ref=built add \-F a\&.out HEAD\fR because that is not binary\-safe\&.) Of course, it doesn\(cqt make much sense to display non\-text\-format notes with \fIgit log\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
core\&.notesRef
.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
notes\&.mergeStrategy
.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
notes\&.<name>\&.mergeStrategy
.RS 4
Which merge strategy to choose when doing a notes merge into refs/notes/<name>\&. This overrides the more general "notes\&.mergeStrategy"\&. See the "NOTES MERGE STRATEGIES" section in
\fBgit-notes\fR(1)
for more information on the available strategies\&.
.RE
.PP
notes\&.displayRef
.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
\fIgit log\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
\fIgit log\fR
family of commands, or by the
\fB\-\-notes=<ref>\fR
option accepted by those commands\&.
.sp
The effective value of "core\&.notesRef" (possibly overridden by GIT_NOTES_REF) is also implicitly added to the list of refs to be displayed\&.
.RE
.PP
notes\&.rewrite\&.<command>
.RS 4
When rewriting commits with <command> (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
notes\&.rewriteMode
.RS 4
When copying notes during a rewrite (see the "notes\&.rewrite\&.<command>" 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
notes\&.rewriteRef
.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\&.<command>\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\&.<command>\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.