From: Johan Herland Date: Sun, 27 May 2007 14:10:20 GMT Subject: [PATCH 02/15] git-note: (Documentation) Add git-note manual page Message-ID: <200705271610.20927.johan@herland.net> In-Reply-To: <200705271608.02122.johan@herland.net> The manual page describes the operation of the git-note command, as well as some discussion around the design and usage of git notes. Signed-off-by: Johan Herland --- 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 | -F ] [] +'git-note' -l [...] +'git-note' -d ... + + +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 ` or `-F ` is +given, an editor is started for the user to type in the note message. + +`-l [...]` lists notes associated with the given s. If no + is given, all notes are listed. The given may itself be +a note object, in which case it is listed along with its associated +notes (if any). + +`-d ...` deletes the notes associated with the given s. +The given may itself be a note object, in which case it is +deleted along with its associated notes (if any). + + +OPTIONS +------- +-d ...:: + Delete existing notes associated with the given name(s). + +-l [...]:: + List notes associated with the given name(s). List all notes id no + name is given. + +-m :: + Use the given note message (instead of prompting) + +-F :: + 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 . + + +GIT +--- +Part of the gitlink:git[7] suite -- 1.5.2.101.gee49f