Git development
 help / color / mirror / Atom feed
From: Patrick Steinhardt <ps@pks.im>
To: Junio C Hamano <gitster@pobox.com>
Cc: git@vger.kernel.org,
	"Mark C. Chu-Carroll" <markchucarroll@fastmail.com>,
	Karthik Nayak <karthik.188@gmail.com>
Subject: Re: [PATCH v5 11/13] builtin/rerere: use `OPT_SUBCOMMAND()`
Date: Fri, 20 Nov 2026 11:16:11 +0100	[thread overview]
Message-ID: <awAd2xxwvH7HCpbH@pks.im> (raw)
In-Reply-To: <xmqqwlq8tpbm.fsf@gitster.g>

On Thu, Nov 19, 2026 at 02:43:25PM -0800, Junio C Hamano wrote:
> Patrick Steinhardt <ps@pks.im> writes:
> 
> > In git-rerere(1) we have our own custom logic to parse subcommands. In
> > preceding commits we have refactored all of those subcommands so that
> > they are ready to be used as `OPT_SUBCOMMAND()`s. Switch over to use
> > these so that we get rid of our custom subcommand parsing.
> >
> > Unfortunately this means that we have a backwards-incompatible change
> > because we no longer accept the "--[no-]rerere-autoupdate" flag for all
> > subcommands. But this was arguably broken and misleading as we ignore
> > this flag for any other subcommand aynway. So we cheat a bit and simply
> > call it a bug that those flags were accepted in the first place.
> 
> Aynway.
> 
> > +static int cmd_rerere_perform(int argc,
> > +			      const char **argv,
> > +			      const char *prefix,
> > +			      struct repository *repo)
> > +{
> > +	int autoupdate = -1;
> > +	struct option options[] = {
> > +		OPT_SET_INT(0, "rerere-autoupdate", &autoupdate,
> > +			N_("register clean resolutions in index"), 1),
> > +		OPT_END(),
> > +	};
> > +	enum rerere_flags flags = 0;
> 
> The "register clean resolutions in index" text used to be given for "-h"
> 
>     $ rungit master rerere -h
>     usage: git rerere [clear | forget <pathspec>... | diff | status | remaining | gc]
> 
>         --[no-]rerere-autoupdate
>                               register clean resolutions in index
> 
> but we moved it to this subcommand.
> 
> It was a bug that "git rerere diff --no-rerere-autoupdate" did not
> complain.  Because this option only appears here, those subcommands
> would now complain when they see the --no-rerere-autoupdate option.
> 
> Which is very good.
> 
> What is a bit sad is that it has become very hard to actually see
> this help text.
> 
>     $ rungit seen rerere -h
>     usage: git rerere [--[no-]rerere-autoupdate]
>        or: git rerere clear
>        or: git rerere diff
>        or: git rerere forget <pathspec>...
>        or: git rerere gc
>        or: git rerere remaining
>        or: git rerere status
> 
> Because the primary subcommand (i.e., record and replay after you
> got a conflict in the working tree) does not have a subcommand verb,
> "git rerere -h" would trigger the help for the top-level command,
> and the help is shown from there without using the options[] array
> in this subcommand.
> 
> I said "very hard", not impossible, because there is an awkward way
> to see this.
> 
>     $ rungit seen rerere -- -h
>     $ rungit seen rerere --rerere-autoupdate -h
> 
> Both of which would give you
> 
>     usage: git rerere [--[no-]rerere-autoupdate]
> 
>         --[no-]rerere-autoupdate
>                               register clean resolutions in index
> 
> but it probably is not what users will ever use.
> 
> I think it is OK to stop here and leave the above as-is.  The only
> people who use this option are those who already know and are used
> to it.  Everybody else I would imagine would rather use
> 
> 	git -c rerere.autoupdate=no rerere
> 
> instead.

Fair. I think all of this boils down to the pattern of having a default
subcommand. I think the pattern is okay as long as we really only accept
`git rerere` without any flags at all. But I think the moment where the
user wants to do something non-default we should refuse flags and
instead ask them to use the aliased subcommand, e.g. `git rerere perform
--rerere-autoupdate`. So essentially:

  usage: git rerere
     or: git rerere perform [--[no-]rerere-autoupdate

That ship has probably sailed for git-rerere(1) though, and I wouldn't
feel comfortable breaking that interface now. But at least it's my
personal takeaway for future commands.

Patrick

  reply	other threads:[~2026-11-20 10:16 UTC|newest]

Thread overview: 107+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-10-27 10:46 [PATCH 00/12] builtin/rerere: convert to use subcommands Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 01/12] rerere: rename `repo_rerere()` Patrick Steinhardt
2026-10-27 19:48   ` Junio C Hamano
2026-10-28  8:33     ` Patrick Steinhardt
2026-10-28 16:25       ` Junio C Hamano
2026-10-27 10:46 ` [PATCH 02/12] rerere: convert flags into an enum Patrick Steinhardt
2026-10-27 14:47   ` Mark C. Chu-Carroll
2026-10-27 19:40     ` Junio C Hamano
2026-10-28  8:33       ` Patrick Steinhardt
2026-10-28 14:11         ` Mark C. Chu-Carroll
2026-10-28 16:25         ` Junio C Hamano
2026-10-27 10:46 ` [PATCH 03/12] builtin/rerere: drop `the_repository` Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 04/12] builtin/rerere: stop passing flags to subcommands that ignore them Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 05/12] builtin/rerere: turn "forget" into a proper subcommand Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 06/12] builtin/rerere: turn "clear" " Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 07/12] builtin/rerere: turn "status" " Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 08/12] builtin/rerere: turn "remaining" " Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 09/12] builtin/rerere: turn "diff" " Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 10/12] builtin/rerere: turn "gc" " Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 11/12] builtin/rerere: use `OPT_SUBCOMMAND()` Patrick Steinhardt
2026-10-27 10:46 ` [PATCH 12/12] builtin/rerere: introduce proper usage strings for subcommands Patrick Steinhardt
2026-10-27 19:52 ` [PATCH 00/12] builtin/rerere: convert to use subcommands Junio C Hamano
2026-10-29  9:57 ` [PATCH v2 " Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 01/12] rerere: rename `repo_rerere()` Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 02/12] rerere: convert flags into an enum Patrick Steinhardt
2026-11-06 10:51     ` Karthik Nayak
2026-11-06 11:39       ` Patrick Steinhardt
2026-11-06 13:50         ` Karthik Nayak
2026-10-29  9:57   ` [PATCH v2 03/12] builtin/rerere: drop `the_repository` Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 04/12] builtin/rerere: stop passing flags to subcommands that ignore them Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 05/12] builtin/rerere: turn "forget" into a proper subcommand Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 06/12] builtin/rerere: turn "clear" " Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 07/12] builtin/rerere: turn "status" " Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 08/12] builtin/rerere: turn "remaining" " Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 09/12] builtin/rerere: turn "diff" " Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 10/12] builtin/rerere: turn "gc" " Patrick Steinhardt
2026-11-06 10:56     ` Karthik Nayak
2026-10-29  9:57   ` [PATCH v2 11/12] builtin/rerere: use `OPT_SUBCOMMAND()` Patrick Steinhardt
2026-11-06 11:44     ` Karthik Nayak
2026-11-06 14:25       ` Patrick Steinhardt
2026-10-29  9:57   ` [PATCH v2 12/12] builtin/rerere: introduce proper usage strings for subcommands Patrick Steinhardt
2026-11-06 11:45   ` [PATCH v2 00/12] builtin/rerere: convert to use subcommands Karthik Nayak
2026-11-06 15:13 ` [PATCH v3 " Patrick Steinhardt
2026-11-06 15:13   ` [PATCH v3 01/12] rerere: rename `repo_rerere()` Patrick Steinhardt
2026-11-06 15:13   ` [PATCH v3 02/12] rerere: convert flags into an enum Patrick Steinhardt
2026-11-06 16:39     ` Junio C Hamano
2026-11-09  7:06       ` Patrick Steinhardt
2026-11-09 15:40         ` Junio C Hamano
2026-11-09 19:13           ` Junio C Hamano
2026-11-11 11:02             ` Patrick Steinhardt
2026-11-06 15:13   ` [PATCH v3 03/12] builtin/rerere: drop `the_repository` Patrick Steinhardt
2026-11-06 15:13   ` [PATCH v3 04/12] builtin/rerere: stop passing flags to subcommands that ignore them Patrick Steinhardt
2026-11-06 15:13   ` [PATCH v3 05/12] builtin/rerere: turn "forget" into a proper subcommand Patrick Steinhardt
2026-11-06 15:14   ` [PATCH v3 06/12] builtin/rerere: turn "clear" " Patrick Steinhardt
2026-11-06 15:14   ` [PATCH v3 07/12] builtin/rerere: turn "status" " Patrick Steinhardt
2026-11-06 15:14   ` [PATCH v3 08/12] builtin/rerere: turn "remaining" " Patrick Steinhardt
2026-11-06 15:14   ` [PATCH v3 09/12] builtin/rerere: turn "diff" " Patrick Steinhardt
2026-11-06 15:14   ` [PATCH v3 10/12] builtin/rerere: turn "gc" " Patrick Steinhardt
2026-11-06 15:14   ` [PATCH v3 11/12] builtin/rerere: use `OPT_SUBCOMMAND()` Patrick Steinhardt
2026-11-06 15:14   ` [PATCH v3 12/12] builtin/rerere: introduce proper usage strings for subcommands Patrick Steinhardt
2026-11-11 12:18 ` [PATCH v4 00/12] builtin/rerere: convert to use subcommands Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 01/12] rerere: rename `repo_rerere()` Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 02/12] rerere: convert flags into an enum Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 03/12] builtin/rerere: drop `the_repository` Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 04/12] builtin/rerere: stop passing flags to subcommands that ignore them Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 05/12] builtin/rerere: turn "forget" into a proper subcommand Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 06/12] builtin/rerere: turn "clear" " Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 07/12] builtin/rerere: turn "status" " Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 08/12] builtin/rerere: turn "remaining" " Patrick Steinhardt
2026-11-11 12:18   ` [PATCH v4 09/12] builtin/rerere: turn "diff" " Patrick Steinhardt
2026-11-17  1:37     ` Junio C Hamano
2026-11-11 12:18   ` [PATCH v4 10/12] builtin/rerere: turn "gc" " Patrick Steinhardt
2026-11-17  1:21     ` Junio C Hamano
2026-11-11 12:18   ` [PATCH v4 11/12] builtin/rerere: use `OPT_SUBCOMMAND()` Patrick Steinhardt
2026-11-17  1:28     ` Junio C Hamano
2026-11-18 14:09       ` Patrick Steinhardt
2026-11-18 17:02         ` Junio C Hamano
2026-11-11 12:18   ` [PATCH v4 12/12] builtin/rerere: introduce proper usage strings for subcommands Patrick Steinhardt
2026-11-17  1:37     ` Junio C Hamano
2026-11-18 14:09       ` Patrick Steinhardt
2026-11-12 13:41   ` [PATCH v4 00/12] builtin/rerere: convert to use subcommands Karthik Nayak
2026-11-13  7:20     ` Patrick Steinhardt
2026-11-13 18:09       ` Junio C Hamano
2026-11-13 19:38         ` Tuomas Ahola
2026-11-13 19:44         ` Phillip Wood
2026-11-13 21:44           ` Junio C Hamano
2026-11-14  7:22             ` Tuomas Ahola
2026-11-16  7:46               ` Patrick Steinhardt
2026-11-14 12:45   ` Junio C Hamano
2026-11-16  7:57     ` Patrick Steinhardt
2026-11-16 15:43       ` Junio C Hamano
2026-11-17  1:16         ` Junio C Hamano
2026-11-18 14:09           ` Patrick Steinhardt
2026-11-19 11:47 ` [PATCH v5 00/13] " Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 01/13] rerere: rename `repo_rerere()` Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 02/13] rerere: convert flags into an enum Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 03/13] builtin/rerere: drop `the_repository` Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 04/13] builtin/rerere: stop passing flags to subcommands that ignore them Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 05/13] builtin/rerere: turn "forget" into a proper subcommand Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 06/13] builtin/rerere: turn "clear" " Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 07/13] builtin/rerere: turn "status" " Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 11/13] builtin/rerere: use `OPT_SUBCOMMAND()` Patrick Steinhardt
2026-11-19 22:43     ` Junio C Hamano
2026-11-20 10:16       ` Patrick Steinhardt [this message]
2026-11-20 16:54         ` Junio C Hamano
2026-11-19 11:47   ` [PATCH v5 12/13] builtin/rerere: introduce proper usage strings for subcommands Patrick Steinhardt
2026-11-19 11:47   ` [PATCH v5 13/13] Documentation/git-rerere: drop claim that we pass args to diff(1) Patrick Steinhardt

Reply instructions:

You may reply publicly 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

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

  git send-email \
    --in-reply-to=awAd2xxwvH7HCpbH@pks.im \
    --to=ps@pks.im \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=karthik.188@gmail.com \
    --cc=markchucarroll@fastmail.com \
    /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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox