Merge branch 'rc/maint-curl-helper' into maint
[gitweb.git] / Documentation / git-notes.txt
index d4487cab5284670644f88d95680581ffd29ae952..4e5113b837230c8f050cf4bbe10e8de4b3271bd0 100644 (file)
@@ -3,57 +3,146 @@ git-notes(1)
 
 NAME
 ----
-git-notes - Add/inspect commit notes
+git-notes - Add/inspect object notes
 
 SYNOPSIS
 --------
 [verse]
-'git notes' (edit [-F <file> | -m <msg>] | show) [commit]
+'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 notes to commit messages, without
-changing the commit.  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:".
+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).
 
-To disable commit notes, you have to set the config variable
-core.notesRef to the empty string.  Alternatively, you can set it
-to a different ref, something like "refs/notes/bugzilla".  This setting
-can be overridden by the environment variable "GIT_NOTES_REF".
+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 commit (defaults to HEAD).
+       Edit the notes for a given object (defaults to HEAD).
 
 show::
-       Show the notes for a given commit (defaults to HEAD).
+       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` (or `-F`) options are given, their
-       values are concatenated as separate paragraphs.
+       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.
-       If multiple `-F` (or `-m`) options are given, their
-       values are concatenated as separate paragraphs.
+
+-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>
+Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
+Johan Herland <johan@herland.net>
 
 Documentation
 -------------
-Documentation by Johannes Schindelin
+Documentation by Johannes Schindelin and Johan Herland
 
 GIT
 ---