[PATCH 02/15] git-note: (Documentation) Add git-note manual page

From

Johan Herland <johan@herland.net>

Date

May 27, 2007, 14:10 UTC

Message-ID

<200705271610.20927.johan@herland.net>

In-Reply-To

<200705271608.02122.johan@herland.net>

Signed-off-by: Johan Herland <johan@herland.net>
---
 Documentation/git-note.txt |   95 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 95 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/git-note.txt

diff --git a/Documentation/git-note.txt b/Documentation/git-note.txt
new file mode 100644
index 0000000..077d526
--- /dev/null
+++ b/Documentation/git-note.txt
@@ -0,0 +1,95 @@
+git-note(1)
+===========
+
+NAME
+----
+git-note - Create, list or delete git note objects
+
+
+SYNOPSIS
+--------
+[verse]
+'git-note' [-m <msg> | -F <file>] [<head>]
+'git-note' -l [<name>...]
+'git-note' -d <name>...
+
+
+DESCRIPTION
+-----------
+Adds a 'note' in `.git/refs/notes/` on an existing git object.
+
+A 'note' is an annotation associated with an existing git object.
+The note is similar in form to a commit message.
+
+Unless `-l` or `-d` is passed, the command creates a 'note' object,
+and requires the note message.  Unless `-m <msg>` or `-F <file>` is
+given, an editor is started for the user to type in the note message.
+
+`-l [<name>...]` lists notes associated with the given <name>s. If no
+<name> is given, all notes are listed. The given <name> may itself be
+a note object, in which case it is listed along with its associated
+notes (if any).
+
+`-d <name>...` deletes the notes associated with the given <name>s.
+The given <name> may itself be a note object, in which case it is
+deleted along with its associated notes (if any).
+
+
+OPTIONS
+-------
+-d <name>...::
+	Delete existing notes associated with the given name(s).
+
+-l [<name>...]::
+	List notes associated with the given name(s). List all notes id no
+	name is given.
+
+-m <msg>::
+	Use the given note message (instead of prompting)
+
+-F <file>::
+	Take the note message from the given file (instead of prompting).
+	Use '-' to read the message from the standard input.
+
+
+DISCUSSION
+----------
+A git note provides an after-the-fact text annotation associated with an
+exiting object in the git object database. The note itself is also stored
+in the database (as a special case of a tag object). Note object are therefore
+-- as all other objects in the database -- immutable, i.e. once added they
+cannot be edited, although they can be deleted.
+
+As with regular tag objects, notes are useless unless they have a
+corresponding reference stored in `.git/refs`. For notes, these references
+are stored in a hierarchy under `.git/refs/notes`. For each object that has
+one or more associated notes, there is a subdirectory under
+`.git/refs/notes` named after the object identifier (SHA1 sum). The
+object's subdirectory contains one file per note associated with that object.
+The end result is that notes are easily accessible from the name/identifier
+of the object they are associated with.
+
+Note that deleting a note with `git-note -d` only deletes the reference to
+the note. The note itself is still present in the object database, but will
+be considered unreachable by gitlink:git-fsck[1], and may be removed with
+gitlink:git-prune[1].
+
+
+USE CASE
+--------
+Notes may be used to add any kind of extra information to existing git
+objects that may not become apparent until 'after' the original object is
+created. A common use case is to add -- for example -- information on bugs
+to existing commit objects. E.g. making notes like "This commit closes
+bug #123", or "This commit opens bug #456". These messages may then be
+parsed by custom tools that interoperate with a bug tracker, etc.
+
+
+Author
+------
+Written by Johan Herland <johan@herland.net>.
+
+
+GIT
+---
+Part of the gitlink:git[7] suite

-- 
1.5.2.101.gee49f