Skip to content

Commit

Permalink
Merge branch 'jn/notes-doc' into maint
Browse files Browse the repository at this point in the history 
* jn/notes-doc:
  Documentation/notes: nitpicks
  Documentation/notes: clean up description of rewriting configuration
  Documentation/notes: simplify treatment of default display refs
  Documentation/log: add a CONFIGURATION section
  Documentation/notes: simplify treatment of default notes ref
  Documentation/notes: add configuration section
  Documentation/notes: describe content of notes blobs
  Documentation/notes: document format of notes trees
  • Loading branch information
Junio C Hamano committed Jun 21, 2010
2 parents 6f79d66 + 1a3eb9a commit 1b9fa0e
Show file tree
Hide file tree
Showing 4 changed files with 238 additions and 35 deletions.
16 changes: 5 additions & 11 deletions Documentation/config.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
42 changes: 42 additions & 0 deletions Documentation/git-log.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
------
Expand Down
177 changes: 153 additions & 24 deletions Documentation/git-notes.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ git-notes(1)

NAME
----
git-notes - Add/inspect object notes
git-notes - Add or inspect object notes

SYNOPSIS
--------
Expand All @@ -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
Expand Down Expand Up @@ -101,38 +103,165 @@ 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>::
Like '-C', but with '-c' the editor is invoked, so that
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.

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>`.


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@kdbg.org>' 72a144e2
$ git show -s 72a144e
[...]
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Notes:
Tested-by: Johannes Sixt <j6t@kdbg.org>
------------

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 through the environment and
command line.

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.
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
Expand Down
38 changes: 38 additions & 0 deletions t/t3307-notes-man.sh
View file
Original file line number Diff line number Diff line change
@@ -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@example.com>
EOF
git notes add -m "Acked-by: A C Ker <acker@example.com>" 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

0 comments on commit 1b9fa0e

Please sign in to comment.