| '\" t |
| .\" Title: git-notes |
| .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
| .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/> |
| .\" Date: 12/01/2018 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.20.0.rc2 |
| .\" Language: English |
| .\" |
| .TH "GIT\-NOTES" "1" "12/01/2018" "Git 2\&.20\&.0\&.rc2" "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] [\-F <file> | \-m <msg> | (\-c | \-C) <object>] [<object>] |
| \fIgit notes\fR copy [\-f] ( \-\-stdin | <from\-object> <to\-object> ) |
| \fIgit notes\fR append [\-\-allow\-empty] [\-F <file> | \-m <msg> | (\-c | \-C) <object>] [<object>] |
| \fIgit notes\fR edit [\-\-allow\-empty] [<object>] |
| \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" configuration in \fBgit-log\fR(1)\&. |
| .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)\&. |
| .RE |
| .PP |
| copy |
| .RS 4 |
| Copy the notes for the first object onto the second object\&. 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 to the notes of an existing object (defaults to HEAD)\&. Creates a new notes object if needed\&. |
| .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\&. |
| .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\&. |
| .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\&.) |
| .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 |
| \-\-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 |
| .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 "NOTES MERGE STRATEGIES" section above for more information on each strategy\&. |
| .sp |
| This setting can be overridden by passing the |
| \fB\-\-strategy\fR |
| option\&. |
| .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 above for more information on each available strategy\&. |
| .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\&. This setting can be overridden on the command line or by the |
| \fBGIT_NOTES_DISPLAY_REF\fR |
| environment variable\&. See |
| \fBgit-log\fR(1)\&. |
| .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 by the |
| \fBGIT_NOTES_REWRITE_REF\fR |
| environment variable\&. |
| .RE |
| .PP |
| notes\&.rewriteMode |
| .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\&. 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\&. |
| .sp |
| Can be overridden with the |
| \fBGIT_NOTES_REWRITE_REF\fR |
| environment variable\&. |
| .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 \fIab\fR\fB/\fR\fIcd\fR\fB/\fR\fIef\fR\fB/\fR\fI\&...\fR\fB/\fR\fIabcdef\&...\fR: a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID. |
| |