Documentation/notes: simplify treatment of default notes ref
Separate the documentation of the semantics, command-line option, configuration item, and environment variable for the default notes ref. The documentation is easier to digest in bite-sized pieces. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
May 8, 2010 at 22:23 UTC
0097971031e8b112a33038d47f5c864dad8e9363
1 file changed
+20
-11
Documentation/git-notes.txt
+20
-11
@@ -23,6 +23,11 @@ DESCRIPTION
23
This command allows you to add/remove notes to/from objects, without
24
changing the objects themselves.
25
26
+By default, notes are saved to and read from `refs/notes/commits`, but
27
+this default can be overridden. See the OPTIONS, CONFIGURATION, and
28
+ENVIRONMENT sections below. If this ref does not exist, it will be
29
+quietly created when it is first needed to store a note.
30
+
31
A typical use of notes is to extend a commit message without having
32
to change the commit itself. Such commit notes can be shown by `git log`
33
along with the original commit message. To discern these notes from the
@@ -30,8 +35,6 @@ message stored in the commit object, the notes are indented like the
35
message, after an unindented line saying "Notes (<refname>):" (or
36
"Notes:" for `refs/notes/commits`).
37
33
-This command always manipulates the notes specified in "core.notesRef"
34
-(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF.
38
To change which notes are shown by 'git-log', see the
39
"notes.displayRef" configuration.
40
@@ -122,8 +125,8 @@ OPTIONS
125
the user can further edit the note message.
126
127
--ref <ref>::
125
- Manipulate the notes tree in <ref>. This overrides both
126
- GIT_NOTES_REF and the "core.notesRef" configuration. The ref
128
+ Manipulate the notes tree in <ref>. This overrides
129
+ 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref
130
is taken to be in `refs/notes/` if it is not qualified.
131
132
@@ -187,13 +190,10 @@ CONFIGURATION
190
-------------
191
192
core.notesRef::
190
- When showing commit messages, also show notes which are stored in
191
- the given ref. The ref must be fully qualified. If the given
192
- ref does not exist, it is not an error but means that no
193
- notes should be printed.
194
-+
195
-This setting defaults to "refs/notes/commits", and it can be overridden by
196
-the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].
193
+ Notes ref to read and manipulate instead of
194
+ `refs/notes/commits`. Must be an unabbreviated ref name.
195
+ This setting can be overridden through the environment and
196
+ command line.
197
198
notes.displayRef::
199
The (fully qualified) refname from which to show notes when
@@ -242,6 +242,15 @@ This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
242
environment variable, which must be a colon separated list of refs or
243
globs.
244
245
+
246
+ENVIRONMENT
247
+-----------
248
+
249
+'GIT_NOTES_REF'::
250
+ Which ref to manipulate notes from, instead of `refs/notes/commits`.
251
+ This overrides the `core.notesRef` setting.
252
+
253
+
254
Author
255
------
256
Written by Johannes Schindelin <johannes.schindelin@gmx.de> and