From patchwork Mon Jul 13 19:10:08 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: 11660913 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 79E8C13B6 for ; Mon, 13 Jul 2020 19:10:51 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 5F64120738 for ; Mon, 13 Jul 2020 19:10:51 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="ot4gkN0t" Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726396AbgGMTKu (ORCPT ); Mon, 13 Jul 2020 15:10:50 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45052 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726150AbgGMTKu (ORCPT ); Mon, 13 Jul 2020 15:10:50 -0400 Received: from mail-lf1-x144.google.com (mail-lf1-x144.google.com [IPv6:2a00:1450:4864:20::144]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D96BEC061755 for ; Mon, 13 Jul 2020 12:10:49 -0700 (PDT) Received: by mail-lf1-x144.google.com with SMTP id y13so9781294lfe.9 for ; Mon, 13 Jul 2020 12:10:49 -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=YSSaaRPLQZmK08wu8Pt+S7vFcxLAP20YjycZ2hkq8fw=; b=ot4gkN0tdzdOmwyoc5xq4Hzfa3sB99FSDc8qOU5JdPkrO1qntfMH0/kKJpKBec9cTe LK6iYTXTcsUDo31J3aQhlhVHXBNTa5DtKwtn0huYkqGOjfYVRODjggOZZIqZ9Qbdzau0 hQjKQP+ezqp5LIDX0LrTrvuVdxANLxN70u5szoKL9u5gqUNCDslbp12ok9k+37cotzh8 MWhTbbBQYjL0V+69+LcQjp+VZqjVtnNPfoPrK6h9sGWh3N7H8aCkPM/jlU1CsF+2knAJ HqhV81s4mZMt+T8vllOJlayZw2aXGTUhU0gD+C8vdJbsf+PNz8PMV8+oyjWzm0oI6Tqo SLiQ== 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=YSSaaRPLQZmK08wu8Pt+S7vFcxLAP20YjycZ2hkq8fw=; b=ZHBtQGGwDCwptNYvJ5KbbL/Dc40wRtiqJPFImh8r8oiIESvNuC1rDPaaHs5jTy/Tcc 1PkTLoWQpp7/VxAwxo7m+mng5myY8dOT2N03AsFPDxvJP3bqaMcd/XLgPO4r8WYDfBTJ nXA3CZO2KGE54k0iiLZU1bBZqZe6GmHwmJWLfeBPL8n0SRGSGwiBNY/ysOBFKG6ZQDWw ny7qTV61+MZyGAlx/jUot0TQevmFTVN30cuOvvbD87Jj5YPWMnGqdh7msEzQu3pGI++r ztWVjfv6wUphLJgClXexUk6XPw2KOWMVTtkTQD1mLwxDdFPUB2uNC36imSm97BLF7xDC x0Ug== X-Gm-Message-State: AOAM532ItNVnrRzaC697LFDDcj08m7GZhjv3l7sref4tBnkRqu4UoTjO 9yjwkGSIDQ+69bNxGXgul8Xlkj3c X-Google-Smtp-Source: ABdhPJyKasll9fn5cnPsP+U5zZasWelJ+zVUUNaMJkrJZ9Wu89hgdwdrlX2s1jgnlfgnIw2iFIgvgw== X-Received: by 2002:a19:8b8a:: with SMTP id n132mr300391lfd.45.1594667448085; Mon, 13 Jul 2020 12:10:48 -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.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 13 Jul 2020 12:10:47 -0700 (PDT) From: =?utf-8?q?Martin_=C3=85gren?= To: git@vger.kernel.org Cc: Chris Torek Subject: [PATCH 1/2] git-diff.txt: don't mark required argument as optional Date: Mon, 13 Jul 2020 21:10:08 +0200 Message-Id: <77e4442ae51a968d460b2329fc39b6a5e96902b0.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 Commit b7e10b2ca2 ("Documentation: usage for diff combined commits", 2020-06-12) modified the synopsis by adding an optional "[...]" to 'git diff' [] [--] [...] to effectively add 'git diff' [] ... [--] [...] as another valid invocation. Which makes sense. Further down, in the description, it left the existing entry for 'git diff' [] [--] [...] intact and added a new entry on 'git diff' [] [...] [--] [...] where it says that "[t]his form is to view the results of a merge commit" and details how "the first listed commit must be the merge itself". But one possible instantiation of this form is `git diff ` for which the added text doesn't really apply. Remove the brackets so that we lose this overlap between the two descriptions. We can still use the more compact representation in the synopsis. Signed-off-by: Martin Ågren --- Documentation/git-diff.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 1018110ddc..c613e71ca4 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -69,7 +69,7 @@ files on disk. one side is omitted, it will have the same effect as using HEAD instead. -'git diff' [] [...] [--] [...]:: +'git diff' [] ... [--] [...]:: This form is to view the results of a merge commit. The first listed must be the merge itself; the remaining two or 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