summaryrefslogtreecommitdiff
path: root/Documentation/git-notes.txt
diff options
context:
space:
mode:
authorJonathan Nieder <jrnieder@gmail.com>2010-05-08 22:23:58 -0500
committerJunio C Hamano <gitster@pobox.com>2010-05-08 22:30:02 -0700
commit0097971031e8b112a33038d47f5c864dad8e9363 (patch)
tree829b75a816ec31245dd58e4839d14d378ae21f14 /Documentation/git-notes.txt
parented9098fda2c8d178aad3a47c0c2f97474c60e82c (diff)
downloadgit-0097971031e8b112a33038d47f5c864dad8e9363.tar.gz
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>
Diffstat (limited to 'Documentation/git-notes.txt')
-rw-r--r--Documentation/git-notes.txt31
1 files changed, 20 insertions, 11 deletions
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index f5614579d6..28ac8622ab 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -23,6 +23,11 @@ DESCRIPTION
This command allows you to add/remove notes to/from objects, without
changing the objects themselves.
+By default, notes are saved to and read from `refs/notes/commits`, but
+this default can be overridden. See the OPTIONS, CONFIGURATION, and
+ENVIRONMENT sections below. If this ref does not exist, it will be
+quietly created when it is first needed to store a note.
+
A typical use of notes is to extend a commit message without having
to change the commit itself. Such commit notes can be shown by `git log`
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
message, after an unindented line saying "Notes (<refname>):" (or
"Notes:" for `refs/notes/commits`).
-This command always manipulates the notes specified in "core.notesRef"
-(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF.
To change which notes are shown by 'git-log', see the
"notes.displayRef" configuration.
@@ -122,8 +125,8 @@ OPTIONS
the user can further edit the note message.
--ref <ref>::
- Manipulate the notes tree in <ref>. This overrides both
- GIT_NOTES_REF and the "core.notesRef" configuration. The ref
+ Manipulate the notes tree in <ref>. This overrides
+ 'GIT_NOTES_REF' and the "core.notesRef" configuration. The ref
is taken to be in `refs/notes/` if it is not qualified.
@@ -187,13 +190,10 @@ CONFIGURATION
-------------
core.notesRef::
- When showing commit messages, also show notes which are stored in
- the given ref. The ref must be fully qualified. If the given
- ref does not exist, it is not an error but means that no
- notes should be printed.
-+
-This setting defaults to "refs/notes/commits", and it can be overridden by
-the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].
+ Notes ref to read and manipulate instead of
+ `refs/notes/commits`. Must be an unabbreviated ref name.
+ This setting can be overridden through the environment and
+ command line.
notes.displayRef::
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`
environment variable, which must be a colon separated list of refs or
globs.
+
+ENVIRONMENT
+-----------
+
+'GIT_NOTES_REF'::
+ Which ref to manipulate notes from, instead of `refs/notes/commits`.
+ This overrides the `core.notesRef` setting.
+
+
Author
------
Written by Johannes Schindelin <johannes.schindelin@gmx.de> and