'\" t .\" Title: git-notes .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.78.1 .\" Date: 05/28/2018 .\" Manual: Git Manual .\" Source: Git 2.1.4 .\" Language: English .\" .TH "GIT\-NOTES" "1" "05/28/2018" "Git 2\&.1\&.4" "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 []] \fIgit notes\fR add [\-f] [\-F | \-m | (\-c | \-C) ] [] \fIgit notes\fR copy [\-f] ( \-\-stdin | ) \fIgit notes\fR append [\-F | \-m | (\-c | \-C) ] [] \fIgit notes\fR edit [] \fIgit notes\fR show [] \fIgit notes\fR merge [\-v | \-q] [\-s ] \fIgit notes\fR merge \-\-commit [\-v | \-q] \fIgit notes\fR merge \-\-abort [\-v | \-q] \fIgit notes\fR remove [\-\-ignore\-missing] [\-\-stdin] [\&...] \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 refs/notes/commits, 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 ():" (or "Notes:" for refs/notes/commits)\&. .sp Notes can also be added to patches prepared with git format\-patch by using the \-\-notes 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\&." 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 " ")\&. 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 \-f to overwrite existing notes)\&. However, if you\(cqre using add interactively (using an editor to supply the notes contents), then \- instead of aborting \- the existing notes will be opened in the editor (like the edit 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: git notes add [\-f] \-C $(git notes list ) .sp In \-\-stdin 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 to its corresponding \&. (The optional is ignored so that the command can read the input given to the post\-rewrite 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 \-s/\-\-strategy option) is not given, the "manual" resolver is used\&. This resolver checks out the conflicting notes in a special worktree (\&.git/NOTES_MERGE_WORKTREE), 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 edit 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 , \-\-message= .RS 4 Use the given note message (instead of prompting)\&. If multiple \-m options are given, their values are concatenated as separate paragraphs\&. Lines starting with # and empty lines other than a single line between paragraphs will be stripped out\&. .RE .PP \-F , \-\-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 # and empty lines other than a single line between paragraphs will be stripped out\&. .RE .PP \-C , \-\-reuse\-message= .RS 4 Take the given blob object (for example, another note) as the note message\&. (Use git notes copy instead to copy notes between objects\&.) .RE .PP \-c , \-\-reedit\-message= .RS 4 Like \fI\-C\fR, but with \fI\-c\fR the editor is invoked, so that the user can further edit the note message\&. .RE .PP \-\-ref .RS 4 Manipulate the notes tree in \&. This overrides \fIGIT_NOTES_REF\fR and the "core\&.notesRef" configuration\&. The ref is taken to be in refs/notes/ if it is not qualified\&. .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 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= .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"\&. 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 a 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\&., git log \-p notes/commits\&. 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 git log \-p \-g \&. .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 (\&.git/NOTES_MERGE_WORKTREE), 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 "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 \*(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 \fIgit hash\-object\fR: .sp .if n \{\ .RS 4 .\} .nf $ cc *\&.c $ blob=$(git hash\-object \-w a\&.out) $ git notes \-\-ref=built add \-C "$blob" HEAD .fi .if n \{\ .RE .\} .sp .sp (You cannot simply use git notes \-\-ref=built add \-F a\&.out HEAD 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 refs/notes/commits\&. Must be an unabbreviated ref name\&. This setting can be overridden through the environment and command line\&. .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 core\&.notesRef or \fIGIT_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 \fIGIT_NOTES_DISPLAY_REF\fR environment variable\&. See \fBgit-log\fR(1)\&. .RE .PP notes\&.rewrite\&. .RS 4 When rewriting commits with (currently amend or rebase), if this variable is false, git will not copy notes from the original to the rewritten commit\&. Defaults to true\&. See also "notes\&.rewriteRef" below\&. .sp This setting can be overridden by the \fIGIT_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 overwrite, concatenate, and ignore\&. Defaults to concatenate\&. .sp This setting can be overridden with the GIT_NOTES_REWRITE_MODE 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 \fIGIT_NOTES_REWRITE_REF\fR environment variable\&. .RE .SH "ENVIRONMENT" .PP \fIGIT_NOTES_REF\fR .RS 4 Which ref to manipulate notes from, instead of refs/notes/commits\&. This overrides the core\&.notesRef setting\&. .RE .PP \fIGIT_NOTES_DISPLAY_REF\fR .RS 4 Colon\-delimited list of refs or globs indicating which refs, in addition to the default from core\&.notesRef or \fIGIT_NOTES_REF\fR, to read notes from when showing commit messages\&. This overrides the notes\&.displayRef 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 \fIGIT_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 overwrite, concatenate, and ignore\&. This overrides the core\&.rewriteMode setting\&. .RE .PP \fIGIT_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 notes\&.rewrite\&. and notes\&.rewriteRef settings\&. .RE .SH "GIT" .sp Part of the \fBgit\fR(7) suite .SH "NOTES" .IP " 1." 4 Permitted pathnames have the form \fIab\fR/\fIcd\fR/\fIef\fR/\fI\&...\fR/\fIabcdef\&...\fR: a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID.