From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 24 Apr 2013 18:29:15 GMT
Subject: Re: [PATCH 6/5] git-diff.txt: banish the <commit>..<commit> form
Message-ID: <7vip3bdbpg.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1366822980-21926-1-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> The '<commit>..<commit>' and '<commit>...<commit>' forms are confusing
> as they are reminiscent of the corresponding forms in the "SPECIFYING
> RANGES" section of revisions.txt.  We can remove the
> '<commit>..<commit>' form now (hence discouraging its use), since it
> is exactly equivalent to the clearer '<commit> <commit>' form.
> However, we must keep the '<commit>...<commit>' form around until we
> can find a different way to express the same thing.
>
> Suggested-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Documentation/git-diff.txt | 21 ++++++---------------
>  1 file changed, 6 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index 1f2f681..118b448 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -14,7 +14,6 @@ SYNOPSIS
>  'git diff' [options] --cached [<commit>] [[--] [<path>...]]
>  'git diff' [options] <blob> <blob>
>  'git diff' [options] <commit> <commit> [[--] [<path>...]]
> -'git diff' [options] <commit>..<commit> [[--] [<path>...]]

I agree with the end result not to list .. form in the SYNOPSIS, but
you shouldn't have added it in the first place in the earlier patch.

>  'git diff' [options] <commit>\...<commit> [[--] [<path>...]]
>  
>  DESCRIPTION
> @@ -63,12 +62,6 @@ directories. This behavior can be forced by --no-index.
>  	This is to view the changes between two arbitrary
>  	<commit>.
>  
> -'git diff' [options] <commit>..<commit> [[--] [<path>...]]::
> -
> -	This is synonymous to the previous form.  If <commit> on
> -	one side is omitted, it will have the same effect as
> -	using HEAD instead.

I do not think it is a bad idea to drop this enumerated item, but I
would have expected a sidenote to be added for the description for
"git diff A B" form, so that people who saw "git diff A..B" somewhere
on the web and wonder what it means can look it up.