Documentation: Generalize git-notes docs to 'objects' instead of 'commits'
Notes can annotate arbitrary objects (not only commits), but this is not reflected in the current documentation. This patch rewrites the git-notes documentation to talk about 'objects' instead of 'commits'. However, the discussion on commit notes and how they are displayed by 'git log' is largely preserved. Finally, I add myself to the Author/Documentation credits, since most of the lines in the git-notes code and docs are blamed on me. Cc: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Johan Herland <johan@herland.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Johan Herland committed
Feb 13, 2010 at 22:28 UTC
7d541174650fb209a00b629d113cb954c24a19de
1 file changed
+20
-15
Documentation/git-notes.txt
+20
-15
@@ -3,37 +3,41 @@ git-notes(1)
3
4
NAME
5
----
6
-git-notes - Add/inspect commit notes
6
+git-notes - Add/inspect object notes
7
8
SYNOPSIS
9
--------
10
[verse]
11
-'git notes' (edit [-F <file> | -m <msg>] | show | remove | prune) [commit]
11
+'git notes' (edit [-F <file> | -m <msg>] | show | remove | prune) [object]
12
13
DESCRIPTION
14
-----------
15
-This command allows you to add/remove notes to/from commit messages,
16
-without changing the commit. To discern these notes from the message
17
-stored in the commit object, the notes are indented like the message,
18
-after an unindented line saying "Notes:".
15
+This command allows you to add/remove notes to/from objects, without
16
+changing the objects themselves.
17
20
-To disable commit notes, you have to set the config variable
21
-core.notesRef to the empty string. Alternatively, you can set it
22
-to a different ref, something like "refs/notes/bugzilla". This setting
23
-can be overridden by the environment variable "GIT_NOTES_REF".
18
+A typical use of notes is to extend a commit message without having
19
+to change the commit itself. Such commit notes can be shown by `git log`
20
+along with the original commit message. To discern these notes from the
21
+message stored in the commit object, the notes are indented like the
22
+message, after an unindented line saying "Notes:".
23
+
24
+To disable notes, you have to set the config variable core.notesRef to
25
+the empty string. Alternatively, you can set it to a different ref,
26
+something like "refs/notes/bugzilla". This setting can be overridden
27
+by the environment variable "GIT_NOTES_REF".
28
29
30
SUBCOMMANDS
31
-----------
32
33
edit::
30
- Edit the notes for a given commit (defaults to HEAD).
34
+ Edit the notes for a given object (defaults to HEAD).
35
36
show::
33
- Show the notes for a given commit (defaults to HEAD).
37
+ Show the notes for a given object (defaults to HEAD).
38
39
remove::
36
- Remove the notes for a given commit (defaults to HEAD).
40
+ Remove the notes for a given object (defaults to HEAD).
41
This is equivalent to specifying an empty note message to
42
the `edit` subcommand.
43
@@ -54,11 +58,12 @@ OPTIONS
58
59
Author
60
------
57
-Written by Johannes Schindelin <johannes.schindelin@gmx.de>
61
+Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
62
+Johan Herland <johan@herland.net>
63
64
Documentation
65
-------------
61
-Documentation by Johannes Schindelin
66
+Documentation by Johannes Schindelin and Johan Herland
67
68
GIT
69
---