Re: [PATCH 5/7] git-log.txt: generalize <since>..<until>

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 21, 2013, 18:54 UTC
Message-ID: <7va9oru32u.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1366534252-12099-6-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

Show 36 quoted lines

> '<since>..<until>' is misleading, as there are many other forms that
> 'git log' can accept as an argument.  Replace it with <revision range>,
> referring to the section "Specifying Ranges" in revisions.txt, and
> rewrite the section appropriately.
>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/git-log.txt | 16 +++++++++-------
>  1 file changed, 9 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index 64cc337..c238475 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -9,7 +9,7 @@ git-log - Show commit logs
>  SYNOPSIS
>  --------
>  [verse]
> -'git log' [<options>] [<since>..<until>] [[\--] <path>...]
> +'git log' [<options>] [<revision range>] [[\--] <path>...]
>  
>  DESCRIPTION
>  -----------
> @@ -62,12 +62,14 @@ produced by --stat etc.
>  	Note that only message is considered, if also a diff is shown
>  	its size is not included.
>  
> -<since>..<until>::
> -	Show only commits between the named two commits.  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].
> +<revision range>::
> +	Show only commits in the specified revision range.  When no
> +	<revision range> is specified, it defaults to 'HEAD' (ie. the

s/ie/i.e./; or s/ie/meaning /;

Show 5 quoted lines

> +	whole history leading to the current commit).  master..HEAD
> +	specifies all the commits reachable from 'HEAD', but not from
> +	'master'. For a complete list of ways to spell
> +	<revision range>, see the "Specifying Ranges" section of
> +	linkgit:gitrevisions[7].

If you want to have a single example (other than 'HEAD' which has to be there anyway to describe the default), I think it would be more helpful to use one that would be common for not-so-advanced users, e.g. "origin..HEAD", without many other prerequisites (e.g. "@{u}.." may be common among more advanced users but is not appropriate here, because the reader may not have learned @{upstream} or omission of a side of a range defaulting to HEAD).

	... `origin..HEAD` specifies all the commits reachable from
	the current commit (i.e. `HEAD`) but not from `origin`.

I could squash these in locally without a reroll, but I haven't read the remainder of the series yet, so we'll see.

>  [\--] <path>...::
>  	Show only commits that are enough to explain how the files