undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation/notes: document format of notes trees

Browse Source 
Separate the specification of the notes format exposed in
git-config.1 from the description of the option; or in other
words, move the explanation for what to expect to find at
refs/notes/commits from git-config.1 to git-notes.1.

Suggested-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jonathan Nieder 2010-05-08 22:19:35 -05:00 committed by Junio C Hamano
parent d599e0484f
commit 9eb3f816de
2 changed files with 25 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
Documentation/config.txt
View File

@ -518,18 +518,12 @@ check that makes sure that existing object files will not get overwritten.
core.notesRef::
When showing commit messages, also show notes which are stored in
the given ref. This ref is expected to contain files named
after the full SHA-1 of the commit they annotate. The ref
must be fully qualified.
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.
+
If such a file exists in the given ref, the referenced blob is read, and
appended to the commit message, separated by a "Notes (<refname>):"
line (shortened to "Notes:" in the case of "refs/notes/commits"). If the
given ref itself does not exist, it is not an error, but means that no
notes should be printed.
+
This setting defaults to "refs/notes/commits", and can be overridden by
the `GIT_NOTES_REF` environment variable.
This setting defaults to "refs/notes/commits", and it can be overridden by
the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].
core.sparseCheckout::
Enable "sparse checkout" feature. See section "Sparse checkout" in

28
Documentation/git-notes.txt
View File

@ -28,7 +28,7 @@ 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
message stored in the commit object, the notes are indented like the
message, after an unindented line saying "Notes (<refname>):" (or
"Notes:" for the default setting).
"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.
@ -122,17 +122,29 @@ OPTIONS
is taken to be in `refs/notes/` if it is not qualified.
NOTES
-----
DISCUSSION
----------
Commit notes are blobs containing extra information about an object
(usually information to supplement a commit's message). These blobs
are taken from notes refs. A notes ref is usually a branch which
contains "files" whose paths are the object names for the objects
they describe, with some directory separators included for performance
reasons footnote:[Permitted pathnames have the form
'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
names of two hexadecimal digits each followed by a filename with the
rest of the object ID.].
Every notes change creates a new commit at the specified notes ref.
You can therefore inspect the history of the notes by invoking, e.g.,
`git log -p notes/commits`.
`git log -p notes/commits`. Currently the commit message only records
which operation triggered the update, and the commit authorship is
determined according to the usual rules (see linkgit:git-commit[1]).
These details may change in the future.
Currently the commit message only records which operation triggered
the update, and the commit authorship is determined according to the
usual rules (see linkgit:git-commit[1]). These details may change in
the future.
It is also permitted for a notes ref to point directly to a tree
object, in which case the history of the notes can be read with
`git log -p -g <refname>`.
Author