git-notes

gitnotes [list [<object>]] gitnotes add [ -f] [ --allow -empty] [ -F <file> | -m <msg> | ( -c | -C) <object>] [<object>] gitnotes copy [ -f] ( --stdin | <from -object> <to -object> ) gitnotes append [ --allow -empty] [ -F <file> | -m <msg> | ( -c | -C) <object>] [<object>] gitnotes edit [ --allow -empty] [<object>] gitnotes show [<object>] gitnotes merge [ -v | -q] [ -s <strategy> ] <notes -ref> gitnotes merge --commit [ -v | -q] gitnotes merge --abort [ -v | -q] gitnotes remove [ --ignore -missing] [ --stdin] [<object> ...] gitnotes prune [ -n] [ -v] gitnotes get -ref

DESCRIPTION

Adds, removes, or reads notes attached to objects, without touching the objects themselves .

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 .

A typical use of notes is to supplement a commit message without changing the commit itself . Notes can be shown by gitlog 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 refs/notes/commits ).

Notes can also be added to patches prepared with gitformat -patch by using the --notes option . Such notes are added as a patch commentary after a three dash separator line .

To change which notes are shown by gitlog ,see the "notes .displayRef" configuration in git-log (1).

See the "notes .rewrite .<command>" configuration for a way to carry notes across commands that rewrite commits .

SUBCOMMANDS

list 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 .

add 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 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) .

copy 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: gitnotes add [ -f] -C $(git notes list <from -object>) <to -object>

In --stdin mode, take lines in the format

.RS 4
<from -object> SP <to -object> [ SP <rest> ] LF .RE

on standard input, and copy the notes from each <from -object> to its corresponding <to -object> . (The optional <rest> is ignored so that the command can read the input given to the post-rewrite hook .)

append Append to the notes of an existing object (defaults to HEAD) . Creates a new notes object if needed .

edit Edit the notes for a given object (defaults to HEAD) .

show Show the notes for a given object (defaults to HEAD) .

merge 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") .

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 ( .git/NOTES_MERGE_WORKTREE ),and instructs the user to manually resolve the conflicts there . When done, the user can either finalize the merge with gitnotes merge --commit ,or abort the merge with gitnotes merge --abort .

remove 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 .

prune Remove all notes for non -existing/unreachable objects .

get -ref Print the current notes ref . This provides an easy way to retrieve the current notes ref (e .g . from scripts) .

OPTIONS

-f, --force When adding notes to an object that already has notes, overwrite the existing notes (instead of aborting) .

-m <msg>, --message=<msg> 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 .

-F <file>, --file=<file> Take the note message from the given file . Use - 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 .

-C <object>, --reuse -message=<object> Take the given blob object (for example, another note) as the note message . (Use gitnotes copy <object> instead to copy notes between objects .)

-c <object>, --reedit -message=<object> Like -C ,but with -c the editor is invoked, so that the user can further edit the note message .

--allow -empty Allow an empty note object to be stored . The default behavior is to automatically remove empty notes .

--ref <ref> Manipulate the notes tree in <ref> . This overrides GIT_NOTES_REF and the "core .notesRef" configuration . The ref specifies the full refname when it begins with refs/notes/ ;when it begins with notes/ , refs/ and otherwise refs/notes/ is prefixed to form a full name of the ref .

--ignore -missing Do not consider it an error to request removing notes from an object that does not have notes attached to it .

--stdin 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) .

-n, --dry -run Do not remove anything; just report the object names whose notes would be removed .

-s <strategy>, --strategy=<strategy> 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 .

--commit Finalize an in -progress gitnotes merge . Use this option when you have resolved the conflicts that gitnotes merge stored in .git/NOTES_MERGE_WORKTREE . This amends the partial merge commit created by gitnotes merge (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 .

--abort Abort/reset an in -progress gitnotes merge ,i .e . a notes merge with conflicts . This simply removes all files related to the notes merge .

-q, --quiet When merging notes, operate quietly .

-v, --verbose When merging notes, be more verbose . When pruning notes, report all object names whose notes are removed .

DISCUSSION

Commit notes are blobs containing extra information about an object (usually information to supplement a commit 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 [1] .

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 ., gitlog -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 git-commit (1)). These details may change in the future .

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 gitlog -p -g <refname> .

NOTES MERGE STRATEGIES

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 gitnotes merge --commit ,or abort the merge with gitnotes merge --abort .

Users may select an automated merge strategy from among the following using either -s/ --strategy option or configuring notes .mergeStrategy accordingly:

"ours" automatically resolves conflicting notes in favor of the local version (i .e . the current notes ref) .

"theirs" automatically resolves notes conflicts in favor of the remote version (i .e . the given notes ref being merged into the current notes ref) .

"union" automatically resolves notes conflicts by concatenating the local and remote versions .

"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 .

EXAMPLES

You can use notes to add annotations with information that was not available at the time a commit was written .

.RS 4
$ 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> .RE

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 githash -object :

.RS 4
$ cc * .c $ blob=$(git hash -object -w a .out) $ git notes --ref=built add --allow -empty -C "$blob" HEAD .RE

(You cannot simply use gitnotes --ref=built add -F a .out HEAD because that is not binary -safe .) Of course, it doesn make much sense to display non -text -format notes with gitlog ,so if you use such notes, you probably need to write some special -purpose tools to do something useful with them .

CONFIGURATION

core .notesRef 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 .

notes .mergeStrategy Which merge strategy to choose by default when resolving notes conflicts . Must be one of manual , ours , theirs , union ,or cat_sort_uniq . Defaults to manual . See "NOTES MERGE STRATEGIES" section above for more information on each strategy .

This setting can be overridden by passing the --strategy option .

notes .<name> .mergeStrategy 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 .

notes .displayRef Which ref (or refs, if a glob or specified more than once), in addition to the default set by core.notesRef or GIT_NOTES_REF ,to read notes from when showing commit messages with the gitlog family of commands . This setting can be overridden on the command line or by the GIT_NOTES_DISPLAY_REF environment variable . See git-log (1).

notes .rewrite .<command> When rewriting commits with <command> (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 .

This setting can be overridden by the GIT_NOTES_REWRITE_REF environment variable .

notes .rewriteMode When copying notes during a rewrite, what to do if the target commit already has a note . Must be one of overwrite , concatenate , cat_sort_uniq ,or ignore . Defaults to concatenate .

This setting can be overridden with the GIT_NOTES_REWRITE_MODE environment variable .

notes .rewriteRef 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 .

Does not have a default value; you must configure this variable to enable note rewriting .

Can be overridden with the GIT_NOTES_REWRITE_REF environment variable .

ENVIRONMENT

GIT_NOTES_REF Which ref to manipulate notes from, instead of refs/notes/commits . This overrides the core.notesRef setting .

GIT_NOTES_DISPLAY_REF Colon -delimited list of refs or globs indicating which refs, in addition to the default from core.notesRef or GIT_NOTES_REF ,to read notes from when showing commit messages . This overrides the notes.displayRef setting .

A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored .

GIT_NOTES_REWRITE_MODE When copying notes during a rewrite, what to do if the target commit already has a note . Must be one of overwrite , concatenate , cat_sort_uniq ,or ignore . This overrides the core.rewriteMode setting .

GIT_NOTES_REWRITE_REF When rewriting commits, which notes to copy from the original to the rewritten commit . Must be a colon -delimited list of refs or globs .

If not set in the environment, the list of notes to copy depends on the notes.rewrite .<command> and notes.rewriteRef settings .

GIT

Part of the git (1)suite

NOTES

" 1." 4 Permitted pathnames have the form ab / cd / ef / ... / abcdef... :a sequence of directory names of two hexadecimal digits each followed by a filename with the rest of the object ID.