threads / patch / 23689
Subject: [PATCH 0/4] Documentation/notes: fill out the man page a little
Jonathan NiederI decided it’s time I learn to use notes. Here’s a by-product.
Thoughts? Jonathan Nieder (4): Documentation/notes: describe effect of environment and configuration Documentation/notes: adjust description to use configuration section Documentation/notes: describe content of notes Documentation/notes: nitpicks
Documentation/git-notes.txt | 114 +++++++++++++++++++++++++++++++++++++------ 1 files changed, 99 insertions(+), 15 deletions(-)
Jonathan Nieder[PATCH 1/4] Documentation/notes: describe effect of environment and configuration
Based on the description from Documentation/config.txt.
For now, this does not share text with Documentation/config.txt because that makes it easier to think about how to describe the environment variables.
Cc: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> --- Documentation/git-notes.txt | 82 +++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 82 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 4e5113b..b26598e 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -135,6 +135,88 @@ usual rules (see linkgit:git-commit[1]). These details may change in the future. +CONFIGURATION +------------- + +core.notesRef:: + By default, 'git notes' and other commands read and manipulate + the notes referred to by `refs/notes/commits`. This + configuration item allows one to specify an alternative + default ref (to be overridden by environment variables or + command-line options). + +notes.displayRef:: + Which refs, in addition to the default set by `core.notesRef` + or 'GIT_NOTES_REF', for 'git log' to read notes from when + showing commit messages. Can be a (fully qualified) ref name + or glob. You may also specify this configuration variable + several times. ++ +This setting can be overridden with the 'GIT_NOTES_DISPLAY_REF' +environment variable. + +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`, 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. 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. Configure this variable to enable note +rewriting. ++ +Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable. + +See linkgit:git-config[1] for details. + +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':: + Which refs, in addition to the default from `core.notesRef` or + 'GIT_NOTES_REF', to read notes from when showing commit + messages. + Must be a colon-delimited list of refs or globs. + 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`, or `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 will depend +on the `notes.rewrite.<command>` and `notes.rewriteRef` settings. + + Author ------ Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
-- 1.7.1
Thomas RastRe: [PATCH 1/4] Documentation/notes: describe effect of environment and configuration
Jonathan Nieder wrote:
> +core.notesRef:: > + By default, 'git notes' and other commands read and manipulate > + the notes referred to by `refs/notes/commits`. This > + configuration item allows one to specify an alternative > + default ref (to be overridden by environment variables or > + command-line options). > + > +notes.displayRef:: > + Which refs, in addition to the default set by `core.notesRef` > + or 'GIT_NOTES_REF', for 'git log' to read notes from when > + showing commit messages. Can be a (fully qualified) ref name > + or glob. You may also specify this configuration variable > + several times. > ++ > +This setting can be overridden with the 'GIT_NOTES_DISPLAY_REF' > +environment variable.
I noticed you copied the rest of the description, but not these, verbatim. If the intention was to separate the specification of the notes format exposed in git-config(1),
[...] This ref is expected to contain files named after the full
SHA-1 of the commit they annotate. The ref must be fully
qualified. 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.from the description of the option. I agree to the idea, but maybe we should also do the same in git-config(1). For example, it could be added to the NOTES section of git-notes(1) that already describes some implementation details.
You also describe the warning semantics only for GIT_NOTES_DISPLAY_REF, not for notes.displayRef. I see the config options as the main feature, and the variable as a mere convenience (but others may disagree) so I would put the full semantics into the config descriptions.
Otherwise, ack.
--
Thomas Rast
trast@{inf,student}.ethz.chJonathan Nieder[PATCH 2/4] Documentation/notes: adjust description to use configuration section
Introduce the default notes ref early on to give the reader a frame of reference for understanding the rest of the description.
Cc: Johan Herland <johan@herland.net> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> --- Documentation/git-notes.txt | 14 ++++++-------- 1 files changed, 6 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index b26598e..0594776 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -23,6 +23,10 @@ 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 CONFIGURATION and ENVIRONMENT +sections below. + 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,14 +34,8 @@ 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). -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. - -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 of carrying +notes across commands that rewrite commits. SUBCOMMANDS
-- 1.7.1
Jonathan Nieder[PATCH 3/4] Documentation/notes: describe content of notes
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> --- Documentation/git-notes.txt | 4 ++++ 1 files changed, 4 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 0594776..273264b 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -27,6 +27,10 @@ By default, notes are saved to and read from `refs/notes/commits`, but this default can be overridden. See the CONFIGURATION and ENVIRONMENT sections below. +Notes can contain any sequence of non-null bytes. Since they are +sanitized with linkgit:git-stripspace[1], empty lines other than a +single line separating paragraphs are not significant. + 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
-- 1.7.1
Thomas RastRe: [PATCH 3/4] Documentation/notes: describe content of notes
Jonathan Nieder wrote:
> +Notes can contain any sequence of non-null bytes. Since they are > +sanitized with linkgit:git-stripspace[1], empty lines other than a > +single line separating paragraphs are not significant.
It even goes slightly further: create_note() calls stripspace() with the skip_comments option enabled, so comment lines are also removed. ('git notes add' actually puts `git show --stat` in a big comment block...)
--
Thomas Rast
trast@{inf,student}.ethz.ch
Johan HerlandRe: [PATCH 3/4] Documentation/notes: describe content of notes
On Tuesday 04 May 2010, Jonathan Nieder wrote:
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> > --- > Documentation/git-notes.txt | 4 ++++ > 1 files changed, 4 insertions(+), 0 deletions(-) > > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt > index 0594776..273264b 100644 > --- a/Documentation/git-notes.txt > +++ b/Documentation/git-notes.txt > @@ -27,6 +27,10 @@ By default, notes are saved to and read from > `refs/notes/commits`, but this default can be overridden. See the > CONFIGURATION and ENVIRONMENT sections below. > > +Notes can contain any sequence of non-null bytes. Since they are > +sanitized with linkgit:git-stripspace[1], empty lines other than a > +single line separating paragraphs are not significant.
In principle, a note is a regular Git (blob) object, and can contain NUL bytes - indeed any kind of (non-)format is accepted.
However, the 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.
So as long as you stick to the following subcommands, notes should be completely binary-safe:
- git notes [list [<object>]] - git notes add [-f] -C <note-object> <object> - git notes copy [-f] <from-object> <to-object> - git notes show [<object>] - git notes remove [<object>] - git notes prune
In other words, you can (binary-safely) create notes from files with the following construct:
git notes add -C $(git hash-object -w <file>) <object>
Of course, it doesn't make much sense displaying non-text-format notes with 'git log', so if you use such notes you'll probably need to write some special-purpose tools for doing anything useful with them.
Otherwise, your other 3 patches seem fine to me (modulo Thomas Rast's comments) and you can consider them Acked-by: Johan Herland <johan@herland.net>
Have fun! :)
...Johan
-- Johan Herland, <johan@herland.net> www.herland.net
Jeff KingRe: [PATCH 3/4] Documentation/notes: describe content of notes
On Tue, May 04, 2010 at 11:55:01AM +0200, Johan Herland wrote:
> On Tuesday 04 May 2010, Jonathan Nieder wrote: > > Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> > > --- > > Documentation/git-notes.txt | 4 ++++ > > 1 files changed, 4 insertions(+), 0 deletions(-) > > > > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt > > index 0594776..273264b 100644 > > --- a/Documentation/git-notes.txt > > +++ b/Documentation/git-notes.txt > > @@ -27,6 +27,10 @@ By default, notes are saved to and read from > > `refs/notes/commits`, but this default can be overridden. See the > > CONFIGURATION and ENVIRONMENT sections below. > > > > +Notes can contain any sequence of non-null bytes. Since they are > > +sanitized with linkgit:git-stripspace[1], empty lines other than a > > +single line separating paragraphs are not significant. > > In principle, a note is a regular Git (blob) object, and can contain NUL > bytes - indeed any kind of (non-)format is accepted. > > However, the 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.
The textconv-cache notes contain whatever the textconv filter produces, so they are a likely way of getting non-standard characters. In practice, though, you will probably not see NULL, because the point was to generate a _text_ version.
-Peff
Jonathan Nieder[PATCH 4/4] Documentation/notes: nitpicks
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 <jrnieder@gmail.com> --- That’s the end of the series. Nothing dramatic, but I thought this basic information could help. Thanks for looking it over.
While I have your attention: the original man page said
To disable commit notes, you have to set the config variable core.notesRef to the empty string. Alternatively, you can set it to a different ref, something like "refs/notes/bugzilla". This setting can be overridden by the environment variable "GIT_NOTES_REF".
which sounds helpful to me, both as an example and as a way to help people who do not want to use the feature. Any idea where we could add it back?
Documentation/git-notes.txt | 16 ++++++++-------- 1 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 273264b..b953575 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,8 +20,8 @@ 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 CONFIGURATION and ENVIRONMENT @@ -31,14 +31,14 @@ Notes can contain any sequence of non-null bytes. Since they are sanitized with linkgit:git-stripspace[1], empty lines other than a single line separating paragraphs are not significant. -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 (<refname>):" (or -"Notes:" for the default setting). +"Notes:" for the main notes ref). -See the "notes.rewrite.<command>" configuration for a way of carrying +See the "notes.rewrite.<command>" configuration for a way to carry notes across commands that rewrite commits.
-- 1.7.1
Thomas RastRe: [PATCH 4/4] Documentation/notes: nitpicks
Jonathan Nieder wrote:
> -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 (<refname>):" (or > -"Notes:" for the default setting). > +"Notes:" for the main notes ref).
Nitpick on your nitpick: we do not call refs/notes/commits the "main" notes ref anywhere, and you don't seem to introduce this terminology.
The user might infer that "main" means core.notesRef, but the omission of (<refname>) is actually hardcoded to only happen for refs/notes/commits, so that's not correct.
[I'll review the other patches after the lecture.]
--
Thomas Rast
trast@{inf,student}.ethz.chJonathan NiederRe: [PATCH 4/4] Documentation/notes: nitpicks
Thomas Rast wrote:
> Jonathan Nieder wrote:
>> -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 (<refname>):" (or >> -"Notes:" for the default setting). >> +"Notes:" for the main notes ref).
[...]
> The user might infer that "main" means core.notesRef, but the omission > of (<refname>) is actually hardcoded to only happen for > refs/notes/commits, so that's not correct.
Oh! I had no inkling.
I guess the simplest way to document this is to just say it:
... unindented line saying "Notes (<refname>):' (or "Notes:" for refs/notes/commits).
Thanks for the explanation.
Cheers, Jonathan