Re: [PATCH 3/5] git-log.txt: fix description of <since>..<until>

[Junio C Hamano <gitster@pobox.com>]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

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