From 9eb3f816dea9fa00e7c20204516b0cb288219057 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:19:35 -0500 Subject: [PATCH] Documentation/notes: document format of notes trees 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 Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/config.txt | 16 +++++----------- Documentation/git-notes.txt | 30 +++++++++++++++++++++--------- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 92f851e79..295928ea7 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -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 ():" -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 diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 4e5113b83..af12c3c9e 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -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 ():" (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`. - -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. +`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. + +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 `. Author -- 2.26.2