git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Johan Herland <johan@herland.net>
To: git@vger.kernel.org
Cc: Linus Torvalds <torvalds@linux-foundation.org>,
	Junio C Hamano <junkio@cox.net>
Subject: [PATCH 02/15] git-note: (Documentation) Add git-note manual page
Date: Sun, 27 May 2007 16:10:20 +0200	[thread overview]
Message-ID: <200705271610.20927.johan@herland.net> (raw)
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 <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

  parent reply	other threads:[~2007-05-27 14:10 UTC|newest]

Thread overview: 53+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2007-05-09 19:20 [RFC] Second parent for reverts Daniel Barkalow
2007-05-09 20:07 ` Johannes Schindelin
2007-05-09 20:22   ` Shawn O. Pearce
2007-05-09 22:26     ` Johan Herland
2007-05-09 21:54 ` Junio C Hamano
2007-05-09 22:16   ` Linus Torvalds
2007-05-10 16:35     ` Linus Torvalds
2007-05-10 18:06       ` Johan Herland
2007-05-10 18:22         ` Linus Torvalds
2007-05-27 14:08           ` [PATCH 00/15] git-note: A mechanisim for providing free-form after-the-fact annotations on commits Johan Herland
2007-05-27 14:09             ` [PATCH 01/15] git-note: Add git-note command for adding/listing/deleting git notes Johan Herland
2007-05-27 14:10             ` Johan Herland [this message]
2007-05-27 14:11             ` [PATCH 03/15] git-note: (Administrivia) Add git-note to Makefile, .gitignore, etc Johan Herland
2007-05-27 14:11             ` [PATCH 04/15] git-note: (Plumbing) Add plumbing-level support for git notes Johan Herland
2007-05-27 14:12             ` [PATCH 05/15] git-note: (Plumbing) Add support for git notes to git-rev-parse and git-show-ref Johan Herland
2007-05-27 14:13             ` [PATCH 06/15] git-note: (Documentation) Explain the new '--notes' option " Johan Herland
2007-05-27 14:13             ` [PATCH 07/15] git-note: (Almost plumbing) Add support for git notes to git-pack-refs and git-fsck Johan Herland
2007-05-27 14:14             ` [PATCH 08/15] git-note: (Decorations) Add note decorations to "git-{log,show,whatchanged} --decorate" Johan Herland
2007-05-27 14:14             ` [PATCH 09/15] git-note: (Documentation) Explain new behaviour of --decorate in git-{log,show,whatchanged} Johan Herland
2007-05-27 14:15             ` [PATCH 10/15] git-note: (Transfer) Teach git-clone how to clone notes Johan Herland
2007-05-27 14:15             ` [PATCH 11/15] git-note: (Transfer) Teach git-fetch to auto-follow notes Johan Herland
2007-05-27 14:15             ` [PATCH 12/15] git-note: (Transfer) Teach git-push to push notes when --all or --notes is given Johan Herland
2007-05-27 14:16             ` [PATCH 13/15] git-note: (Documentation) Explain the new --notes option to git-push Johan Herland
2007-05-27 14:16             ` [PATCH 14/15] git-note: (Tests) Add tests for git-note and associated functionality Johan Herland
2007-05-27 14:17             ` [PATCH 15/15] git-note: Add display of notes to gitk Johan Herland
2007-05-27 20:09             ` [PATCH 00/15] git-note: A mechanisim for providing free-form after-the-fact annotations on commits Junio C Hamano
2007-05-28  0:29               ` Johan Herland
2007-05-28  0:59               ` Jakub Narebski
2007-05-28  4:37             ` Linus Torvalds
2007-05-28 10:54               ` Johan Herland
2007-05-28 16:28                 ` Linus Torvalds
2007-05-28 16:40                   ` Johan Herland
2007-05-28 16:58                     ` Linus Torvalds
2007-05-28 17:48                       ` Johan Herland
2007-05-28 20:45                         ` Junio C Hamano
2007-05-28 21:35                           ` Shawn O. Pearce
2007-05-28 23:37                             ` Johannes Schindelin
2007-05-29  3:12                             ` Linus Torvalds
2007-05-29  3:22                               ` Shawn O. Pearce
2007-05-29  7:04                                 ` Jakub Narebski
2007-05-29 11:04                               ` Andy Parkins
2007-05-29 11:12                                 ` Johannes Schindelin
2007-05-29  7:06                           ` Johan Herland
2007-05-29  8:22                             ` Jeff King
2007-05-29  9:23                               ` Johan Herland
2007-05-28 20:45                 ` Junio C Hamano
2007-05-28 21:19                   ` Shawn O. Pearce
2007-05-28 23:46                   ` [PATCH] Add fsck_verify_ref_to_tag_object() to verify that refname matches name stored in tag object Johan Herland
2007-05-28 17:29               ` [PATCH 00/15] git-note: A mechanisim for providing free-form after-the-fact annotations on commits Michael S. Tsirkin
2007-05-28 17:42                 ` Michael S. Tsirkin
2007-05-28 17:58                   ` Johan Herland
2007-05-10 22:33       ` [RFC] Second parent for reverts Martin Langhoff
2007-05-10  1:43   ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=200705271610.20927.johan@herland.net \
    --to=johan@herland.net \
    --cc=git@vger.kernel.org \
    --cc=junkio@cox.net \
    --cc=torvalds@linux-foundation.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).