From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-4.0 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,NICE_REPLY_A, SPF_HELO_PASS,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by dcvr.yhbt.net (Postfix) with ESMTP id 4901D1F4B4 for ; Tue, 22 Sep 2020 13:27:28 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726648AbgIVN10 (ORCPT ); Tue, 22 Sep 2020 09:27:26 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56392 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726605AbgIVN10 (ORCPT ); Tue, 22 Sep 2020 09:27:26 -0400 Received: from mail-wm1-x342.google.com (mail-wm1-x342.google.com [IPv6:2a00:1450:4864:20::342]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id EF920C061755 for ; Tue, 22 Sep 2020 06:27:25 -0700 (PDT) Received: by mail-wm1-x342.google.com with SMTP id b79so3346710wmb.4 for ; Tue, 22 Sep 2020 06:27:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=reply-to:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=3l7VUwShaNgKeFUfIdiMEyrhAVfan8RfQPuC42YD0bw=; b=ZKe84qflHo7pJ9Xf4vljZMMlpREUwThlgd8RsXQcfGz6F9cw3SzGUMnTP2R/sc+oY4 zOSqc+bsEV6vrdjA0x1QZgXCb50mkfHIpR9POffeeSzF5/or+YyD4MSdUyUhRT9gdX2B dMv4kt1k+OMr617LVlg6XxHctAcGoleUabfUo0TQXMCTQpRb2RCVTZ8323UL4iPqswxV 1RUNScurOOb4ByqvuwgDyxDY3eiG0DkB4v9WrIETIa7NZ3nyO1wJ5yFIxDaJdad3LQkX 9IZbOY4JA4omgBus4vvS6UH502VdsNzSKlbuz3uxhjdmemlTZI1VLzlp+JTblpxTxZQa +B4w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:reply-to:subject:to:cc:references:from :message-id:date:user-agent:mime-version:in-reply-to :content-language:content-transfer-encoding; bh=3l7VUwShaNgKeFUfIdiMEyrhAVfan8RfQPuC42YD0bw=; b=qtTDZW+Yt4IsgYhhqWDgWKkOQDtUZJFu9MqUsjKXzZANRqyp1cFLK+Sb+MYh6DGcX+ 3AwhxHFi7Th8/jeQz2uJkaEoE+QRT3f/4No3+6C8fSqWatPgFSsgfvG/6QoAOJhWHzyt iAxDb8yyhVG3jjrvnAdietZBmGK6OLq22OEnRo4UArIrURrzabuq/wYGAU6V8AzpGBRz ZiDrzlHy2XLNsafFx+DIf2lhBV7tG3rQXF3t4s1lM6cmgXd+RvLRGOIufcku6XLp1sbD HQe3yJRsisVeDa8IEwK/osTBZ/IJgbK1ioWB+Z9d+LP6ojF/eH3hvBc9srPUC7wsKaFj htIQ== X-Gm-Message-State: AOAM532yKf9cPpqfamm6HlZrE8DuiojzFY5Ij5Bm6muwnIlHgH1TdTNE L7g33DkfFst7c4IGqBgCkBxaeXRPYL0= X-Google-Smtp-Source: ABdhPJyth4gGqVPaf1LwRDpc3QZstlUrMatGgJXwh1k8Ok4+H5k9+cuWLzDikTYaNPM6A2i7DIJDfA== X-Received: by 2002:a1c:4c06:: with SMTP id z6mr1056301wmf.40.1600781244489; Tue, 22 Sep 2020 06:27:24 -0700 (PDT) Received: from [192.168.1.240] (79.35.7.51.dyn.plus.net. [51.7.35.79]) by smtp.gmail.com with ESMTPSA id h76sm5325855wme.10.2020.09.22.06.27.23 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Tue, 22 Sep 2020 06:27:23 -0700 (PDT) Reply-To: phillip.wood@dunelm.org.uk Subject: Re: [PATCH 2/3] commit: reorder synopsis To: Junio C Hamano , Phillip Wood via GitGitGadget Cc: git@vger.kernel.org, Phillip Wood References: <80a69318b57348c59e45c0f8df1c342ef84388d4.1600695050.git.gitgitgadget@gmail.com> From: Phillip Wood Message-ID: <2a14d3d2-743c-215e-aa69-de75a576f685@gmail.com> Date: Tue, 22 Sep 2020 14:27:22 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.12.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8 Content-Language: en-GB-large Content-Transfer-Encoding: 7bit Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org On 22/09/2020 06:27, Junio C Hamano wrote: > "Phillip Wood via GitGitGadget" writes: > >> From: Phillip Wood >> >> Rearrange the synopsis for `git commit` to try and put options that >> are used more often nearer the beginning. > > Which option is used "more often" depends heavily on the workflow, > and it is a bit unfriendly to those who are affected by this change > not to list the ones you are demoting, with rationale for each, > something like: I agree the changes are a bit subjective, I thought --dry-run -u and -v were probably not as important enough to justify their position on the first line and it sounds like you basically agree with that. > - "--dry-run" may or may not be used often, but it is orthogonal to > the regular options that affect how the command behaves, and it > is much less important and interesting than the other options. > > Among the ones you are demoting without explanation > > - "-s" is no longer even mentioned, which I do not think is a well > thought out change. That's a mistake I did not intend to remove it, thanks for spotting that > - "-v" is to make the command do the same thing as it does without > it, but just more loudly, so it is less interesting than the > other options. > > - "-u" affects what is shown in the editor to prepare the log > message, which is of less importance than other options that > affect the outcome of the command. When --no-status is in > effect, -u would not even have any effect, so it probably > makes sense to move this next to "--[no-]status". > > - "--reset-author" can be used not just to take ownership of the > commit from somebody else, but also be used to update the author > date of your own change. It probably belongs to the same group > as -c/-C/-F/-m that affects the metadata of the resulting commit > and should stay at the original location in the list. If you > want to change anything around this area, I'd suggest moving > --date= close to this "options that affect commit's > metadata" group. I was trying to group the author/date related option together - they all affect the metadata of the resulting commit What do you think to -'git commit' [-a | --interactive | --patch] [-s] [-v] [-u] [--amend] - [--dry-run] [(-c | -C | --fixup | --squash) ] - [-F | -m ] [--reset-author] [--allow-empty] - [--allow-empty-message] [--no-verify] [-e] [--author=] - [--date=] [--cleanup=] [--[no-]status] [-i | -o] [--pathspec-from-file= [--pathspec-file-nul]] [-S[]] [--] [...] +'git commit' [-a | --interactive | --patch] [--amend] + [(-c | -C | --fixup | --squash) ] [-F | -m ] + [--reset-author] [--author=] [--date=] [-s] [-e] + [--allow-empty] [--allow-empty-message] [--no-verify] + [--cleanup=] [-u] [--[no-]status] [-v] [--dry-run] [-i | -o | -p] [--pathspec-from-file= [--pathspec-file-nul]] [-S[]] [--] [...] --dry-run and -v are demoted. -u is moved next to --[no-]status as they are related. -s is restored but moved and the author/date related options are moved up to join the other options that affect the commit metadata. The downside is that --allow-empty and friends end up being moved down a line as a consequence of keeping all the commit metadata related options together. If you are happy I'll redo the commit message based on your suggestions above Thanks Phillip > > >> Signed-off-by: Phillip Wood >> --- >> Documentation/git-commit.txt | 10 +++++----- >> 1 file changed, 5 insertions(+), 5 deletions(-) >> >> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt >> index a1d1d1246f..9de4dc5d66 100644 >> --- a/Documentation/git-commit.txt >> +++ b/Documentation/git-commit.txt >> @@ -8,11 +8,11 @@ git-commit - Record changes to the repository >> SYNOPSIS >> -------- >> [verse] >> -'git commit' [-a | --interactive | --patch] [-s] [-v] [-u] [--amend] >> - [--dry-run] [(-c | -C | --fixup | --squash) ] >> - [-F | -m ] [--reset-author] [--allow-empty] >> - [--allow-empty-message] [--no-verify] [-e] [--author=] >> - [--date=] [--cleanup=] [--[no-]status] >> +'git commit' [-a | --interactive | --patch] [--amend] >> + [(-c | -C | --fixup | --squash) ] [-F | -m ] >> + [--allow-empty] [--allow-empty-message] [--no-verify] [-e] >> + [--reset-author] [--author=] [--date=] >> + [--cleanup=] [-v] [-u] [--dry-run] [--[no-]status] >> [-i | -o] [--pathspec-from-file= [--pathspec-file-nul]] >> [-S[]] [--] [...]