git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / Atom feed
From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
To: Denton Liu <liu.denton@gmail.com>
Cc: Git Mailing List <git@vger.kernel.org>,
	Andreas Schwab <schwab@linux-m68k.org>,
	Duy Nguyen <pclouds@gmail.com>, Elijah Newren <newren@gmail.com>,
	Johannes Schindelin <Johannes.Schindelin@gmx.de>,
	Johannes Sixt <j6t@kdbg.org>, Junio C Hamano <gitster@pobox.com>,
	Philip Oakley <philipoakley@iee.org>,
	vincent.guittot@linaro.org,
	Viresh Kumar <viresh.kumar@linaro.org>
Subject: Re: [PATCH] git-diff.txt: prefer not using <commit>..<commit>
Date: Sun, 17 Mar 2019 14:40:59 +0100
Message-ID: <87multaaac.fsf@evledraar.gmail.com> (raw)
In-Reply-To: <bc7c3f9d769b2d5a108ff4cdc3c7277e112fdb56.1552820745.git.liu.denton@gmail.com>


On Sun, Mar 17 2019, Denton Liu wrote:

> The documentation used to consider
>
> 	git diff <commit> <commit>
>
> and
>
> 	git diff <commit>..<commit>
>
> to be equal counterparts. However, rev-list-ish commands also use the
> <commit>..<commit> notation, but in a logically conflicting manner which
> was confusing for some users (including me!).
>
> Deprecating the notation entirely is not really an option because it
> would be an arduous process without much end-value. In addition, there
> are some valid use-cases that we don't want to break.
>
> Document the preference of the first form so that future confusion can
> be minimised.
>
> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>
> Thanks all on your feedback on the discussion thread[1]! I opted for
> just the documentation-only route so we don't break any valid use-cases.
>
> [1]: https://public-inbox.org/git/20190311093751.GA31092@archbookpro.localdomain/
>
>  Documentation/git-diff.txt | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index 72179d993c..10c7a2220c 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -63,7 +63,11 @@ two blob objects, or changes between two files on disk.
>
>  'git diff' [<options>] <commit>..<commit> [--] [<path>...]::
>
> -	This is synonymous to the previous form.  If <commit> on
> +	This is synonymous to the previous form.  However,
> +	users should prefer the previous form over this form
> +	as this form may be more confusing due to the same
> +	notation having a logically conflicting meaning in
> +	linkgit:git-rev-list[1]-ish commands.  If <commit> on
>  	one side is omitted, it will have the same effect as
>  	using HEAD instead.

I think we're better off just consistently recommending "A..B" instead
of "A B" and "fixing" any occurrence of the latter to the
former. I.e. not taking this patch & going in the other direction.

As noted in the thread you linked we'll always need ".." when one side
is "HEAD" implicitly, and that's a really common case.

So as confusing as the whole ".." v.s. "..." is in diff v.s. log I think
we're worse off with "A B", since we'll *still* need to document the
likes of "A.." and how that differs from log "A.." or "A...".

So sometimes using the whitespace form for two revs and then the ".."
when we just have one side makes things more confusing, not less. The
reader will be left having to juggle more complexity in their head, not
less.

  parent reply index

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-03-17 11:09 Denton Liu
2019-03-17 13:24 ` Duy Nguyen
2019-03-18  6:45   ` Junio C Hamano
2019-03-19  1:12     ` Denton Liu
2019-03-17 13:40 ` Ævar Arnfjörð Bjarmason [this message]
2019-03-17 14:01   ` Duy Nguyen
2019-03-17 14:12     ` Ævar Arnfjörð Bjarmason
2019-03-18  6:47       ` Junio C Hamano
2019-03-18 17:46   ` Elijah Newren
2019-03-18 19:07     ` Ævar Arnfjörð Bjarmason
2019-03-19  0:56       ` Junio C Hamano
2019-03-18 17:59 ` Elijah Newren

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87multaaac.fsf@evledraar.gmail.com \
    --to=avarab@gmail.com \
    --cc=Johannes.Schindelin@gmx.de \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=j6t@kdbg.org \
    --cc=liu.denton@gmail.com \
    --cc=newren@gmail.com \
    --cc=pclouds@gmail.com \
    --cc=philipoakley@iee.org \
    --cc=schwab@linux-m68k.org \
    --cc=vincent.guittot@linaro.org \
    --cc=viresh.kumar@linaro.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org list mirror (unofficial, one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox