Re: [PATCH 3/5] git-log.txt: fix description of <since>..<until>
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Apr 21, 2013, 06:40 UTC
- Message-ID
- <7vy5ccwflw.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <1366458313-7186-4-git-send-email-artagnon@gmail.com>
Ramkumar Ramachandra <artagnon@gmail.com> writes:
Show 29 quoted lines
> First, <since> and <until> are ways to specify "revisions", not > "commits", as gitrevisions.txt would indicate. Second, > '<since>..<until>' is simply indicative of how users would normally > want to specify the rev spec: it need not conform to this form, and > can take any form that gitrevisions.txt lists. A 'git log :/quuxery' > is perfectly valid, for instance. Make these two corrections to the > description of '<since>..<until>' under OPTIONS. > > Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com> > --- > Documentation/git-log.txt | 6 +++--- > 1 file changed, 3 insertions(+), 3 deletions(-) > > diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt > index 69db578..f03ae74 100644 > --- a/Documentation/git-log.txt > +++ b/Documentation/git-log.txt > @@ -25,11 +25,11 @@ OPTIONS > ------- > > <since>..<until>:: > - Show only commits between the named two commits. When > + Show only commits between the named two revisions. When > either <since> or <until> is omitted, it defaults to > `HEAD`, i.e. the tip of the current branch. > - For a more complete list of ways to spell <since> > - and <until>, see linkgit:gitrevisions[7]. > + For a more complete list of ways to spell <since>..<until>, > + see linkgit:gitrevisions[7].
A bigger issue is if it is a good idea to single out A..B like this in the enumeration of options and parameters. We are listing this among the optoins and pathspec, so this is where we _ought_ to be saying that you can specify a revision range on the command line. We use A..B only because it is the most commonly used form, asking e.g. "show me the commit since v1.7.12 up to v1.8.0", but this existing headline makes it as if it is the _only_ form, which is somewhat misleading.
It might be better _not_ to say <since>..<until> here and on the synopsis part, replace it with <revision range>, and update the text to mention <since>..<until> as a more concrete "v1.0..v2.0" example. Perhaps like
<revision range>::
Show only commits in the specified revision range. When no <revision range> is specified, defaults to "HEAD" (i.e. the whole history leading to the current commit). v1.0..v2.0 asks for commits since the commit tagged as version 1.0 up to the commit tagged as version 2.0. For a more complete list of ways to spell this parameter, see "Specifying Ranges" section of linkgit:gitrevisions[7].
or something.
Documentation/gitrevisions.txt lists <rev1>..<rev2>, but does not mention that missing <rev1> (or <rev2>) defaults to HEAD, which is worth adding there with or without the above suggested update.