From 9eb3f816dea9fa00e7c20204516b0cb288219057 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:19:35 -0500 Subject: 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 92f851e797..295928ea72 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 4e5113b837..af12c3c9e7 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 -- cgit v1.2.3 From 8d6888ec6aee97f8b2b395e7e075dd00d9689c25 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:21:34 -0500 Subject: Documentation/notes: describe content of notes blobs stripspace/text-based formatting kicks in when specifying the notes content with -m or -F, or when an editor is used to edit the notes. To binary-safely create notes from files, the following construct is required: git notes add -C $(git hash-object -w ) Explain this trick (thanks, Johan!) in the manual. Add an ordinary example, too, to keep this esoteric one company. Cc: Johan Herland Cc: Thomas Rast Cc: Jeff King Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 38 +++++++++++++++++++++++++++++++++++++- t/t3307-notes-man.sh | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 1 deletion(-) create mode 100755 t/t3307-notes-man.sh diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index af12c3c9e7..97b9d81e29 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -101,15 +101,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=:: 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 :: --reuse-message=:: - Reuse the note message from the given note object. + Take the note message from the given blob object (for + example, another note). -c :: --reedit-message=:: @@ -147,6 +152,37 @@ object, in which case the history of the notes can be read with `git log -p -g `. +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 ' 72a144e2 +$ git show -s 72a144e +[...] + Signed-off-by: Junio C Hamano + +Notes: + Tested-by: Johannes Sixt +------------ + +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. + + Author ------ Written by Johannes Schindelin and diff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh new file mode 100755 index 0000000000..3269f2eebd --- /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 + EOF + git notes add -m "Acked-by: A C Ker " 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 -- cgit v1.2.3 From ed9098fda2c8d178aad3a47c0c2f97474c60e82c Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:21:59 -0500 Subject: Documentation/notes: add configuration section Copy the descriptions of configuration variables from git-config.1. Once the descriptions have been ironed out, it would be nice to refactor them to share text, but for now it is simplest to experiment with separate copies. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 59 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 97b9d81e29..f5614579d6 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -183,6 +183,65 @@ 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:: + 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.displayRef:: + The (fully qualified) refname from which to show notes when + showing commit messages. The value of this variable can be set + to a glob, in which case notes from all matching refs will be + shown. You may also specify this configuration variable + several 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 overridden with the `GIT_NOTES_DISPLAY_REF` +environment variable, which must be a colon separated list of refs or +globs. ++ +The effective value of "core.notesRef" (possibly overridden by +GIT_NOTES_REF) is also implicitly added to the list of refs to be +displayed. + +notes.rewrite.:: + When rewriting commits with (currently `amend` or + `rebase`) and this variable is set to `true`, git + automatically copies your notes from the original to the + rewritten commit. Defaults to `true`, but see + "notes.rewriteRef" below. + +notes.rewriteMode:: + When copying notes during a rewrite (see the + "notes.rewrite." option), determines what to do if + the target commit already has a note. Must be one of + `overwrite`, `concatenate`, or `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. The ref 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. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_REF` +environment variable, which must be a colon separated list of refs or +globs. + Author ------ Written by Johannes Schindelin and -- cgit v1.2.3 From 0097971031e8b112a33038d47f5c864dad8e9363 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:23:58 -0500 Subject: 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 Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 31 ++++++++++++++++++++----------- 1 file 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 ():" (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 :: - Manipulate the notes tree in . This overrides both - GIT_NOTES_REF and the "core.notesRef" configuration. The ref + Manipulate the notes tree in . 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 and -- cgit v1.2.3 From 59893a88f96b3ed4223c20942fd3db5d8c43f7c0 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:30:41 -0500 Subject: Documentation/log: add a CONFIGURATION section Add a configuration section summarizing variables that affect the log family of commands. Cc: Thomas Rast Cc: Jakub Narebski Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-log.txt | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index fb184ba186..d7f6a9cc3e 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 ------ -- cgit v1.2.3 From 66c4c32d29de5d24161dc804197918453d9cd2d3 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:32:24 -0500 Subject: Documentation/notes: simplify treatment of default display refs The main description of display refs for notes should be in git-log.1, where there is a chance to give a leisurely description of all the ways they can be set, what they are used for, and so on. The description in git-notes.1 is only meant to be a quick reminder of how notes are used. So simplify it. Also add an entry for GIT_NOTES_DISPLAY_REF to the environment section. Cc: Thomas Rast Cc: Johan Herland Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 36 +++++++++++++++++++----------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 28ac8622ab..7856b286f7 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -35,8 +35,8 @@ message stored in the commit object, the notes are indented like the message, after an unindented line saying "Notes ():" (or "Notes:" for `refs/notes/commits`). -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." in linkgit:git-config[1] for a way of carrying your notes across commands @@ -196,21 +196,13 @@ core.notesRef:: command line. notes.displayRef:: - The (fully qualified) refname from which to show notes when - showing commit messages. The value of this variable can be set - to a glob, in which case notes from all matching refs will be - shown. You may also specify this configuration variable - several 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 overridden with the `GIT_NOTES_DISPLAY_REF` -environment variable, which must be a colon separated list of refs or -globs. -+ -The effective value of "core.notesRef" (possibly overridden by -GIT_NOTES_REF) is also implicitly added to the list of refs to be -displayed. + 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.:: When rewriting commits with (currently `amend` or @@ -250,6 +242,16 @@ ENVIRONMENT 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. + Author ------ -- cgit v1.2.3 From c5ce1836719dc77e3c8495206653037cb5c4e511 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:33:28 -0500 Subject: Documentation/notes: clean up description of rewriting configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify that the GIT_NOTES_REWRITE_REFS environment variable overrides both ‘[notes "rewrite"] ’ and ‘[notes] rewriteRef’. Add explanations of GIT_NOTES_REWRITE_MODE and GIT_NOTES_REWRITE_REFS to the ENVIRONMENT section. Cc: Leif Arne Storset Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 47 ++++++++++++++++++++++++++++----------------- 1 file changed, 29 insertions(+), 18 deletions(-) diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 7856b286f7..d868535ee9 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -38,9 +38,8 @@ message, after an unindented line saying "Notes ():" (or 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." in -linkgit:git-config[1] for a way of carrying your notes across commands -that rewrite commits. +See the "notes.rewrite." configuration for a way to carry +notes across commands that rewrite commits. SUBCOMMANDS @@ -206,33 +205,31 @@ notes.displayRef:: notes.rewrite.:: When rewriting commits with (currently `amend` or - `rebase`) and this variable is set to `true`, git - automatically copies your notes from the original to the - rewritten commit. Defaults to `true`, but see - "notes.rewriteRef" below. + `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 (see the - "notes.rewrite." option), determines what to do if - the target commit already has a note. Must be one of - `overwrite`, `concatenate`, or `ignore`. Defaults to - `concatenate`. + 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. The ref may be a - glob, in which case notes in all matching refs will be copied. - You may also specify this configuration several times. + 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. + -This setting can be overridden with the `GIT_NOTES_REWRITE_REF` -environment variable, which must be a colon separated list of refs or -globs. +Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. ENVIRONMENT @@ -252,6 +249,20 @@ ENVIRONMENT 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.` and `notes.rewriteRef` settings. + Author ------ -- cgit v1.2.3 From 1a3eb9a0325fc1d1d168b517210b7760d31d3022 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sat, 8 May 2010 22:37:21 -0500 Subject: Documentation/notes: nitpicks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spell out “or” in the NAME line and simplify the leading sentence in the DESCRIPTION. Some other language cleanups, too. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-notes.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index d868535ee9..de63ef0745 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,17 +20,17 @@ 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. 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 +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 ():" (or "Notes:" for `refs/notes/commits`). -- cgit v1.2.3