git-notes
Add or inspect object notes
TLDR
List all notes and the objects they are attached to
List all notes attached to a given object (defaults to HEAD)
Show the notes attached to a given object (defaults to HEAD)
Append a note to a specified object (opens the default text editor)
Append a note to a specified object, specifying the message
Edit an existing note (defaults to HEAD)
Copy a note from one object to another
Remove all the notes added to a specified object
SYNOPSIS
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
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>
<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
NOTES MERGE STRATEGIES
EXAMPLES
$ 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 .
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 .
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
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.