diff options
Diffstat (limited to 'Documentation/git-notes.txt')
| -rw-r--r-- | Documentation/git-notes.txt | 386 |
1 files changed, 0 insertions, 386 deletions
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt deleted file mode 100644 index 84022f99d7..0000000000 --- a/Documentation/git-notes.txt +++ /dev/null @@ -1,386 +0,0 @@ -git-notes(1) -============ - -NAME ----- -git-notes - Add or inspect object notes - -SYNOPSIS --------- -[verse] -'git notes' [list [<object>]] -'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>] -'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] ) -'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>] -'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace] -'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" discussion in <<CONFIGURATION>>. - -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). If you specify multiple `-m` and `-F`, a blank - line will be inserted between the messages. Use the `--separator` - option to insert other delimiters. You can use `-e` to edit and - fine-tune the message(s) supplied from `-m` and `-F` options - interactively (using an editor) before adding the note. - -copy:: - Copy the notes for the first object onto the second object (defaults to - HEAD). 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 new message(s) given by `-m` or `-F` options to an - existing note, or add them as a new note if one does not - exist, for the object (defaults to HEAD). When appending to - an existing note, a blank line is added before each new - message as an inter-paragraph separator. The separator can - be customized with the `--separator` option. - Edit the notes to be appended given by `-m` and `-F` options with - `-e` interactively (using an editor) before appending the note. - -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. - If you wish to keep them verbatim, use `--no-stripspace`. - --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. - If you wish to keep them verbatim, use `--no-stripspace`. - --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.). By default, message will be - copied verbatim, but if you wish to strip out the lines - starting with `#` and empty lines other than a single line - between paragraphs, use with`--stripspace` option. - --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. - ---[no-]separator, --separator=<paragraph-break>:: - Specify a string used as a custom inter-paragraph separator - (a newline is added at the end as needed). If `--no-separator`, no - separators will be added between paragraphs. Defaults to a blank - line. - ---[no-]stripspace:: - Strip leading and trailing whitespace from the note message. - Also strip out empty lines other than a single line between - paragraphs. Lines starting with `#` will be stripped out - in non-editor cases like `-m`, `-F` and `-C`, but not in - editor case like `git notes edit`, `-c`, etc. - ---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 an 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 -'bf'`/`'fe'`/`'30'`/`'...'`/`'680d5a...': 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]] -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. - -include::includes/cmd-config-section-rest.txt[] - -include::config/notes.txt[] - - -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 |