From patchwork Mon Jul 13 19:10:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Martin_=C3=85gren?= X-Patchwork-Id: 11660915 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id D559A618 for ; Mon, 13 Jul 2020 19:10:55 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id BBD2A20758 for ; Mon, 13 Jul 2020 19:10:55 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="s2SzrJp0" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726504AbgGMTKy (ORCPT ); Mon, 13 Jul 2020 15:10:54 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45066 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726150AbgGMTKy (ORCPT ); Mon, 13 Jul 2020 15:10:54 -0400 Received: from mail-lj1-x241.google.com (mail-lj1-x241.google.com [IPv6:2a00:1450:4864:20::241]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 27F99C061755 for ; Mon, 13 Jul 2020 12:10:54 -0700 (PDT) Received: by mail-lj1-x241.google.com with SMTP id x9so9327858ljc.5 for ; Mon, 13 Jul 2020 12:10:54 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=WCSmfOItjkS++mx21wyYFn6bcfuxCxR1SZLyHwQ0uAs=; b=s2SzrJp0hcMMuah99Vjx8CZ03Dc3HuczNo2R3Fu6i9r2kTOdqRkXjfTiKndypPOz3E jDIkOBH/sYo2IpTAT6ZBh6N7GqoCanEfhT5dqzEMg1FV3MmTIqCGfTII6nmgy79dgw/E tmpgi3deWAmvrYfOO9GfjSyA1mH1iFPQGrpdzcmYEImO5+nVc14TGqZcLj/xQwrBgwpW L3BFVkopZ+kuECk1rErrWY2CEGdhGNtMXeGL4RPc0xu+MY5gxHCeJG3Zde6TQuMqnQEC pE2Vx+cofhZ1hFVqg6zHXw3SgjZDbVgNATEzTkLcU4O0OQvorpHrsMw1qr9WUwSwv0zx huTA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=WCSmfOItjkS++mx21wyYFn6bcfuxCxR1SZLyHwQ0uAs=; b=ht+o0M9ssdDp59450Zl4bVsb9pzRqYrXBJSJNWSC3xX2TZ3BCh3plUTRfaHJseuB4B rls7Zt9c2JCBZCeFxde2qWt64nc94rXFH1Dvao6FYFlrOD1ic+abM8NtykwmYStG9NBo BEWhHSbxJYUdmwaJrCKF1KA35b0/7R/stYAVaZndVVg9MUI8Xq5KjBBO3bTI4chVRYW6 52XrMFOIBts+8wf30yfVHM+tPRZGTwc0gVvztJygF9/O1T5RxJWqx3h9dei8bXcNoAQN n/0MqrfNGwLer1fLlcWf36uoGRl0XafpI54LRuoXCRqRh5b7zqvN2DbG8ywuE4O7mDT3 o8Pw== X-Gm-Message-State: AOAM530rDpjsK7+S6zuKPzy+wjU0b0UH58j28sDPcQTa+cpk0zuLKtgo YLgSQBtxuY/sM1A1SpfNE2LYaRQO X-Google-Smtp-Source: ABdhPJx2ytLjL/iYyD/m59SEtst2OKhJaFaoq1n/39Aljb8iODmOQLgqR+2sRLROEtbWxm7k6R3Ynw== X-Received: by 2002:a2e:9cd8:: with SMTP id g24mr524485ljj.245.1594667452325; Mon, 13 Jul 2020 12:10:52 -0700 (PDT) Received: from localhost.localdomain (92-33-153-30.customers.ownit.se. [92.33.153.30]) by smtp.gmail.com with ESMTPSA id m6sm4192367ljc.134.2020.07.13.12.10.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 Jul 2020 12:10:51 -0700 (PDT) From: =?utf-8?q?Martin_=C3=85gren?= To: git@vger.kernel.org Cc: Chris Torek Subject: [PATCH 2/2] git-diff.txt: reorder possible usages Date: Mon, 13 Jul 2020 21:10:09 +0200 Message-Id: <280943ef56a2a777ab0162b8ec4ba0166cc2095c.1594666410.git.martin.agren@gmail.com> X-Mailer: git-send-email 2.28.0.rc0 In-Reply-To: References: MIME-Version: 1.0 Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org The description of `git diff` goes through several different invocations (numbering added by me): 1. git diff [] [--] [...] 2. git diff [] --no-index [--] 3. git diff [] --cached [] [--] [...] 4. git diff [] [--] [...] 5. git diff [] [--] [...] 6. git diff [] .. [--] [...] 7. git diff [] ... [--] [...] 8. git diff [] ... [--] [...] It then goes on to say that "all of the in the above description, except in the last two forms that use '..' notations, can be any ". The "last two" actually refers to 6 and 8. This got out of sync in commit b7e10b2ca2 ("Documentation: usage for diff combined commits", 2020-06-12) which added item 7 to the mix. As a further complication, after b7e10b2ca2 we also have some potential confusion around "the '..' notation". The "..[.]" in items 6 and 8 are part of the rev notation, whereas the "..." in item 7 is manpage language for "one or more". Move item 6 down, i.e., to between 7 and 8, to restore the ordering. Because 6 refers to 5 ("synonymous to the previous form") we need to tweak the language a bit. An added bonus of this commit is that we're trying to steer users away from `git diff ..` and moving it further down probably doesn't hurt. Signed-off-by: Martin Ågren --- Documentation/git-diff.txt | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index c613e71ca4..727f24d16e 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -63,12 +63,6 @@ files on disk. This is to view the changes between two arbitrary . -'git diff' [] .. [--] [...]:: - - This is synonymous to the previous form. If on - one side is omitted, it will have the same effect as - using HEAD instead. - 'git diff' [] ... [--] [...]:: This form is to view the results of a merge commit. The first @@ -78,6 +72,13 @@ files on disk. For instance, if `master` names a merge commit, `git diff master master^@` gives the same combined diff as `git show master`. +'git diff' [] .. [--] [...]:: + + This is synonymous to the earlier form (without the "..") for + viewing the changes between two arbitrary . If on + one side is omitted, it will have the same effect as + using HEAD instead. + 'git diff' [] \... [--] [...]:: This form is to view the changes on the branch containing