diff options
Diffstat (limited to 'Documentation/git-notes.txt')
| -rw-r--r-- | Documentation/git-notes.txt | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt new file mode 100644 index 0000000000..43677297f3 --- /dev/null +++ b/Documentation/git-notes.txt @@ -0,0 +1,405 @@ +git-notes(1) +============ + +NAME +---- +git-notes - Add or inspect object notes + +SYNOPSIS +-------- +[verse] +'git notes' [list [<object>]] +'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' copy [-f] ( --stdin | <from-object> <to-object> ) +'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [--allow-empty] [<object>] +'git notes' show [<object>] +'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref> +'git notes' merge --commit [-v | -q] +'git notes' merge --abort [-v | -q] +'git notes' remove [--ignore-missing] [--stdin] [<object>...] +'git notes' prune [-n | -v] +'git notes' 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 'git log' 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 `git format-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 'git log', see the +"notes.displayRef" configuration in linkgit: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're 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: + `git notes add [-f] -C $(git notes list <from-object>) <to-object>` ++ +In `--stdin` mode, take lines in the format ++ +---------- +<from-object> SP <to-object> [ SP <rest> ] LF +---------- ++ +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 +'git notes merge --commit', or abort the merge with +'git notes 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 `git notes 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 'git notes merge'. Use this option + when you have resolved the conflicts that 'git notes merge' + stored in .git/NOTES_MERGE_WORKTREE. This amends the partial + merge commit created by 'git notes 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 a in-progress 'git notes 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's 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 footnote:[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.]. + +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 linkgit: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 +`git log -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 +'git notes merge --commit', or abort the merge with +'git notes 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. + +------------ +$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano <gitster@pobox.com> + +Notes: + Tested-by: Johannes Sixt <j6t@kdbg.org> +------------ + +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 'git hash-object': + +------------ +$ cc *.c +$ blob=$(git hash-object -w a.out) +$ git notes --ref=built add --allow-empty -C "$blob" HEAD +------------ + +(You cannot simply use `git notes --ref=built add -F a.out HEAD` +because that is not binary-safe.) +Of course, it doesn't make much sense to display non-text-format notes +with 'git log', so if you use such notes, you'll 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 'git log' family of commands. + This setting can be overridden on the command line or by the + `GIT_NOTES_DISPLAY_REF` environment variable. + See linkgit: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 linkgit:git[1] suite |