Add some basic information to the ‘git notes’ page, mostly by moving
over information from git-config.1. In particular, clarify that the
GIT_NOTES_REWRITE_REFS environment variable overrides both
‘[notes "rewrite"] <command>’ and ‘[notes] rewriteRef’.
Also add a Configuration section to git-log.1 for the ‘git notes’
page to refer to.
Later it would be nice to merge some changes back to git-config.1,
but one thing at a time.
Based on advice from Johan, Thomas, and Jeff.
Acked-by: Johan Herland <johan@xxxxxxxxxxx>
Acked-by: Thomas Rast <trast@xxxxxxxxxxxxxxx>
Cc: Jeff King <peff@xxxxxxxx>
Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx>
---
This patch is meant to replace the jn/notes-doc branch in pu.
Interdiff from last round:
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index de63ef0..1d8eef1 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -149,9 +149,12 @@ 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>`.
+Some notes refs may be "history-less", either because they point
+directly to a tree instead of a commit, or because their commits are
+truncated; the notes generated by textconv caching
+(see linkgit:gitattributes[5]) are an example of the latter.
+To see the local history of these refs, view the reflog with
+`git log -g <refname>`.
EXAMPLES
@@ -191,8 +194,8 @@ CONFIGURATION
core.notesRef::
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.
+ This setting can be overridden by the 'GIT_NOTES_REF'
+ environment variable or the `--ref` option.
notes.displayRef::
Which ref (or refs, if a glob or specified more than once), in
Thomas Rast wrote:
> I admit I read the end result instead of
> the series to save myself some confusion.
There’s a good reason to combine patches if I’ve ever heard one.
Thanks for noticing.
Jonathan
Documentation/config.txt | 16 +---
Documentation/git-log.txt | 42 ++++++++++
Documentation/git-notes.txt | 180 +++++++++++++++++++++++++++++++++++++------
t/t3307-notes-man.sh | 38 +++++++++
4 files changed, 241 insertions(+), 35 deletions(-)
create mode 100755 t/t3307-notes-man.sh
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8f86050..cc4bc20 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 (<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
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index fb184ba..d7f6a9c 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -132,6 +132,48 @@ Discussion
include::i18n.txt[]
+Configuration
+-------------
+
+See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
+for settings related to diff generation.
+
+format.pretty::
+ Default for the `--format` option. (See "PRETTY FORMATS" above.)
+ Defaults to "medium".
+
+i18n.logOutputEncoding::
+ Encoding to use when displaying logs. (See "Discussion", above.)
+ Defaults to the value of `i18n.commitEncoding` if set, UTF-8
+ otherwise.
+
+log.date::
+ Default format for human-readable dates. (Compare the
+ `--date` option.) Defaults to "default", which means to write
+ dates like `Sat May 8 19:35:34 2010 -0500`.
+
+log.showroot::
+ If `false`, 'git log' and related commands will not treat the
+ initial commit as a big creation event. Any root commits in
+ `git log -p` output would be shown without a diff attached.
+ The default is `true`.
+
+mailmap.file::
+ See linkgit:git-shortlog[1].
+
+notes.displayRef::
+ Which refs, in addition to the default set by `core.notesRef`
+ or 'GIT_NOTES_REF', to read notes from when showing commit
+ messages with the 'log' family of commands. See
+ linkgit:git-notes[1].
++
+May be an unabbreviated ref name or a glob and may be specified
+multiple times. A warning will be issued for refs that do not exist,
+but a glob that does not match any refs is silently ignored.
++
+This setting can be disabled by the `--no-standard-notes` option,
+overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable,
+and supplemented by the `--show-notes` option.
Author
------
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 4e5113b..1d8eef1 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -3,7 +3,7 @@ git-notes(1)
NAME
----
-git-notes - Add/inspect object notes
+git-notes - Add or inspect object notes
SYNOPSIS
--------
@@ -20,24 +20,26 @@ SYNOPSIS
DESCRIPTION
-----------
-This command allows you to add/remove notes to/from objects, without
-changing the objects themselves.
+Adds, removes, or reads notes attached to objects, without touching
+the objects themselves.
-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
+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 supplement a commit message without
+changing the commit itself. Notes can be shown by 'git log' along with
+the original commit message. To distinguish 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.
-To change which notes are shown by 'git-log', see the
-"notes.displayRef" configuration.
+To change which notes are shown by 'git log', see the
+"notes.displayRef" configuration in linkgit:git-log[1].
-See the description of "notes.rewrite.<command>" in
-linkgit:git-config[1] for a way of carrying your notes across commands
-that rewrite commits.
+See the "notes.rewrite.<command>" configuration for a way to carry
+notes across commands that rewrite commits.
SUBCOMMANDS
@@ -101,15 +103,20 @@ OPTIONS
Use the given note message (instead of prompting).
If multiple `-m` options are given, their values
are concatenated as separate paragraphs.
+ Lines starting with `#` and empty lines other than a
+ single line between paragraphs will be stripped out.
-F <file>::
--file=<file>::
Take the note message from the given file. Use '-' to
read the note message from the standard input.
+ Lines starting with `#` and empty lines other than a
+ single line between paragraphs will be stripped out.
-C <object>::
--reuse-message=<object>::
- Reuse the note message from the given note object.
+ Take the note message from the given blob object (for
+ example, another note).
-c <object>::
--reedit-message=<object>::
@@ -117,22 +124,147 @@ 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.
-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.
+Some notes refs may be "history-less", either because they point
+directly to a tree instead of a commit, or because their commits are
+truncated; the notes generated by textconv caching
+(see linkgit:gitattributes[5]) are an example of the latter.
+To see the local history of these refs, view the reflog with
+`git log -g <refname>`.
+
+
+EXAMPLES
+--------
+
+You can use notes to add annotations with information that was not
+available at the time a commit was written.
+
+------------
+$ git notes add -m 'Tested-by: Johannes Sixt <j6t@xxxxxxxx>' 72a144e2
+$ git show -s 72a144e
+[...]
+ Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
+
+Notes:
+ Tested-by: Johannes Sixt <j6t@xxxxxxxx>
+------------
+
+In principle, a note is a regular Git blob, and any kind of
+(non-)format is accepted. You can binary-safely create notes from
+arbitrary files using 'git hash-object':
+
+------------
+$ cc *.c
+$ blob=$(git hash-object -w a.out)
+$ git notes --ref=built add -C "$blob" HEAD
+------------
+
+Of course, it doesn't make much sense to display non-text-format notes
+with 'git log', so if you use such notes, you'll probably need to write
+some special-purpose tools to do something useful with them.
+
+
+CONFIGURATION
+-------------
+
+core.notesRef::
+ Notes ref to read and manipulate instead of
+ `refs/notes/commits`. Must be an unabbreviated ref name.
+ This setting can be overridden by the 'GIT_NOTES_REF'
+ environment variable or the `--ref` option.
+
+notes.displayRef::
+ Which ref (or refs, if a glob or specified more than once), in
+ addition to the default set by `core.notesRef` or
+ 'GIT_NOTES_REF', to read notes from when showing commit
+ messages with the 'git log' family of commands.
+ This setting can be overridden on the command line or by the
+ 'GIT_NOTES_DISPLAY_REF' environment variable.
+ See linkgit:git-log[1].
+
+notes.rewrite.<command>::
+ When rewriting commits with <command> (currently `amend` or
+ `rebase`), if this variable is `false`, git will not copy
+ notes from the original to the rewritten commit. Defaults to
+ `true`. See also "`notes.rewriteRef`" below.
++
+This setting can be overridden by the 'GIT_NOTES_REWRITE_REF'
+environment variable.
+
+notes.rewriteMode::
+ When copying notes during a rewrite, what to do if the target
+ commit already has a note. Must be one of `overwrite`,
+ `concatenate`, and `ignore`. Defaults to `concatenate`.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
+environment variable.
+
+notes.rewriteRef::
+ When copying notes during a rewrite, specifies the (fully
+ qualified) ref whose notes should be copied. May be a glob,
+ in which case notes in all matching refs will be copied. You
+ may also specify this configuration several times.
++
+Does not have a default value; you must configure this variable to
+enable note rewriting.
++
+Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.
+
+
+ENVIRONMENT
+-----------
+
+'GIT_NOTES_REF'::
+ Which ref to manipulate notes from, instead of `refs/notes/commits`.
+ This overrides the `core.notesRef` setting.
+
+'GIT_NOTES_DISPLAY_REF'::
+ Colon-delimited list of refs or globs indicating which refs,
+ in addition to the default from `core.notesRef` or
+ 'GIT_NOTES_REF', to read notes from when showing commit
+ messages.
+ This overrides the `notes.displayRef` setting.
++
+A warning will be issued for refs that do not exist, but a glob that
+does not match any refs is silently ignored.
+
+'GIT_NOTES_REWRITE_MODE'::
+ When copying notes during a rewrite, what to do if the target
+ commit already has a note.
+ Must be one of `overwrite`, `concatenate`, and `ignore`.
+ This overrides the `core.rewriteMode` setting.
+
+'GIT_NOTES_REWRITE_REF'::
+ When rewriting commits, which notes to copy from the original
+ to the rewritten commit. Must be a colon-delimited list of
+ refs or globs.
++
+If not set in the environment, the list of notes to copy depends
+on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
Author
diff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh
new file mode 100755
index 0000000..3269f2e
--- /dev/null
+++ b/t/t3307-notes-man.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+
+test_description='Examples from the git-notes man page
+
+Make sure the manual is not full of lies.'
+
+. ./test-lib.sh
+
+test_expect_success 'setup' '
+ test_commit A &&
+ test_commit B &&
+ test_commit C
+'
+
+test_expect_success 'example 1: notes to add an Acked-by line' '
+ cat <<-\EOF >expect &&
+ B
+
+ Notes:
+ Acked-by: A C Ker <acker@xxxxxxxxxxx>
+ EOF
+ git notes add -m "Acked-by: A C Ker <acker@xxxxxxxxxxx>" B &&
+ git show -s B^{commit} >log &&
+ tail -n 4 log >actual &&
+ test_cmp expect actual
+'
+
+test_expect_success 'example 2: binary notes' '
+ cp "$TEST_DIRECTORY"/test4012.png .
+ git checkout B &&
+ blob=$(git hash-object -w test4012.png) &&
+ git notes --ref=logo add -C "$blob" &&
+ git notes --ref=logo copy B C &&
+ git notes --ref=logo show C >actual &&
+ test_cmp test4012.png actual
+'
+
+test_done
--
1.7.1
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html