diff options
Diffstat (limited to 'Documentation/git-notes.txt')
| -rw-r--r-- | Documentation/git-notes.txt | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt new file mode 100644 index 0000000000..4e5113b837 --- /dev/null +++ b/Documentation/git-notes.txt @@ -0,0 +1,149 @@ +git-notes(1) +============ + +NAME +---- +git-notes - Add/inspect object notes + +SYNOPSIS +-------- +[verse] +'git notes' [list [<object>]] +'git notes' add [-f] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' copy [-f] ( --stdin | <from-object> <to-object> ) +'git notes' append [-F <file> | -m <msg> | (-c | -C) <object>] [<object>] +'git notes' edit [<object>] +'git notes' show [<object>] +'git notes' remove [<object>] +'git notes' prune + + +DESCRIPTION +----------- +This command allows you to add/remove notes to/from objects, without +changing the objects themselves. + +A typical use of notes is to extend a commit message without having +to change the commit itself. Such commit notes can be shown by `git log` +along with the original commit message. To discern 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 the default setting). + +This command always manipulates the notes specified in "core.notesRef" +(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF. +To change which notes are shown by 'git-log', see the +"notes.displayRef" configuration. + +See the description of "notes.rewrite.<command>" in +linkgit:git-config[1] for a way of carrying your 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 an + existing note). + +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). + +remove:: + Remove the notes for a given object (defaults to HEAD). + This is equivalent to specifying an empty note message to + the `edit` subcommand. + +prune:: + Remove all notes for non-existing/unreachable objects. + +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. + +-F <file>:: +--file=<file>:: + Take the note message from the given file. Use '-' to + read the note message from the standard input. + +-C <object>:: +--reuse-message=<object>:: + Reuse the note message from the given note object. + +-c <object>:: +--reedit-message=<object>:: + Like '-C', but with '-c' the editor is invoked, so that + the user can further edit the note message. + +--ref <ref>:: + Manipulate the notes tree in <ref>. This overrides both + GIT_NOTES_REF and the "core.notesRef" configuration. The ref + is taken to be in `refs/notes/` if it is not qualified. + + +NOTES +----- + +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. + + +Author +------ +Written by Johannes Schindelin <johannes.schindelin@gmx.de> and +Johan Herland <johan@herland.net> + +Documentation +------------- +Documentation by Johannes Schindelin and Johan Herland + +GIT +--- +Part of the linkgit:git[7] suite |