From patchwork Sun Mar 17 11:09:07 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Denton Liu X-Patchwork-Id: 10856283 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 6317A139A for ; Sun, 17 Mar 2019 11:09:15 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 3F3C529470 for ; Sun, 17 Mar 2019 11:09:15 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 2E5D0294B9; Sun, 17 Mar 2019 11:09:15 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-8.0 required=2.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id BF43329470 for ; Sun, 17 Mar 2019 11:09:14 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726967AbfCQLJL (ORCPT ); Sun, 17 Mar 2019 07:09:11 -0400 Received: from mail-pf1-f195.google.com ([209.85.210.195]:41261 "EHLO mail-pf1-f195.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726773AbfCQLJL (ORCPT ); Sun, 17 Mar 2019 07:09:11 -0400 Received: by mail-pf1-f195.google.com with SMTP id d25so9313753pfn.8 for ; Sun, 17 Mar 2019 04:09:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:mime-version:content-disposition :user-agent; bh=bnNTFJMua0pMWlYz4Oq7Wg+MNIqi/NpCg8HT4/MQt1Q=; b=sXvNGJskp2qN63s162EHnDr378mDkOkCA1hn9wMUNoUfTsxLAsqfxriFGlzO9PzeW9 lll4LQKwhpB7qglzJ77PiDQn2oZ0Y1P2c5y6QrWCK9pH89oEbp41zjX8jV6HOB399OI/ cJFabHtQgRcDPi8eS48/qX2qoJ7jDDlrf6Sqds7oq89OoKjaWyZ+kpIXeSaDCL3MQsvX 3vF3exNVrletfxfMV9wi5TlXkACtB+HH77rCPXoxb92HI8jTUbGSc449b+DZzfjXo6JC ji6RKFLyqkHKjq1SIh5t4tZzHaQcdpx9n3uAD/j3Kagu9JRrKP5Abcjbc96848099Ou0 66lQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:user-agent; bh=bnNTFJMua0pMWlYz4Oq7Wg+MNIqi/NpCg8HT4/MQt1Q=; b=gwnOzoh7NkbXzjnFXTw/rOY5yXWwop7wlHEhZHwgPqN6xe69T9gY7c4Q85bk/pWRDh H1omYuXGVj/RLHhh6OtfxiJb/A8R5WQt7RPHv6u69NcqQN0ks4cDxmkXdcLGLNJ8FYtT /f3mcN69pHjzZuN4Rmo0rSqze7u8K7aWa0adKX1Ubg5lYDVyl1CaM9P3zzT54qWQrKkm 2FtDFl0pLqJetrwN12t449+W1Nx3vjZnXkX1B8d8EHDMAY/il3qh24z3x/DZgKLnm6w0 E0AfM0pANaTajVgebk4pskWOP83j6lzV54IyqhpNZ3eaiFkMYc2EkIxeubVqPwPid/Jf EbBQ== X-Gm-Message-State: APjAAAUZx77CpDGeF6SoAlj4bHyp2keOd/vCJgwiR97IVmYTYOtAZN1I leGFm4s7d0YqsUrqjhsUr+0ASiKeLRY= X-Google-Smtp-Source: APXvYqxkjG2C4jXHsdDVdnNC32SNUzOPQ02VEp5oWY0w8RRWjmQlqyg7X+t+la0D2vV6LptPovqsug== X-Received: by 2002:a17:902:123:: with SMTP id 32mr919418plb.187.1552820950102; Sun, 17 Mar 2019 04:09:10 -0700 (PDT) Received: from archbookpro.localdomain (c-73-222-73-77.hsd1.ca.comcast.net. [73.222.73.77]) by smtp.gmail.com with ESMTPSA id q207sm12836419pgq.88.2019.03.17.04.09.08 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 17 Mar 2019 04:09:09 -0700 (PDT) Date: Sun, 17 Mar 2019 04:09:07 -0700 From: Denton Liu To: Git Mailing List Cc: =?iso-8859-1?q?=C6var_Arnfj=F6r=F0?= Bjarmason , Andreas Schwab , Denton Liu , Duy Nguyen , Elijah Newren , Johannes Schindelin , Johannes Sixt , Junio C Hamano , Philip Oakley , vincent.guittot@linaro.org, Viresh Kumar Subject: [PATCH] git-diff.txt: prefer not using .. Message-ID: MIME-Version: 1.0 Content-Disposition: inline User-Agent: Mutt/1.11.3 (2019-02-01) Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The documentation used to consider git diff and git diff .. to be equal counterparts. However, rev-list-ish commands also use the .. 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 --- 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' [] .. [--] [...]:: - This is synonymous to the previous form. If 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 on one side is omitted, it will have the same effect as using HEAD instead.