From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: Glen Choo <chooglen@google.com>
Cc: git@vger.kernel.org, Junio C Hamano <gitster@pobox.com>,
Atharva Raykar <raykar.ath@gmail.com>
Subject: Re: [PATCH v2 08/12] submodule--helper: report "submodule" as our name in "-h" output
Date: Wed, 15 Jun 2022 11:42:09 +0200 [thread overview]
Message-ID: <220615.86r13qxmjx.gmgdl@evledraar.gmail.com> (raw)
In-Reply-To: <kl6lczfa60d3.fsf@chooglen-macbookpro.roam.corp.google.com>
On Tue, Jun 14 2022, Glen Choo wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> diff --git a/builtin/submodule--helper.c b/builtin/submodule--helper.c
>> index 574d6e0a79b..c2f55779cb1 100644
>> --- a/builtin/submodule--helper.c
>> +++ b/builtin/submodule--helper.c
>> @@ -286,7 +286,7 @@ static int module_list(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper list [--prefix=<path>] [<path>...]"),
>> + N_("git submodule list [--prefix=<path>] [<path>...]"),
>> NULL
>> };
>> @@ -444,7 +444,7 @@ static int module_foreach(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper foreach [--quiet] [--recursive] [--] <command>"),
>> + N_("git submodule foreach [--quiet] [--recursive] [--] <command>"),
>> NULL
>> };
>>
>> @@ -582,7 +582,7 @@ static int module_init(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper init [<options>] [<path>]"),
>> + N_("git submodule init [<options>] [<path>]"),
>> NULL
>> };
>>
>> @@ -786,7 +786,7 @@ static int module_name(int argc, const char **argv, const char *prefix)
>> const struct submodule *sub;
>>
>> if (argc != 2)
>> - usage(_("git submodule--helper name <path>"));
>> + usage(_("git submodule name <path>"));
>>
>> sub = submodule_from_path(the_repository, null_oid(), argv[1]);
>>
>> @@ -1185,7 +1185,7 @@ static int module_summary(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper summary [<options>] [<commit>] [--] [<path>]"),
>> + N_("git submodule summary [<options>] [<commit>] [--] [<path>]"),
>> NULL
>> };
>>
>> @@ -1349,7 +1349,7 @@ static int module_sync(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper sync [--quiet] [--recursive] [<path>]"),
>> + N_("git submodule sync [--quiet] [--recursive] [<path>]"),
>> NULL
>> };
>>
>> @@ -1789,7 +1789,7 @@ static int module_clone(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper clone [--prefix=<path>] [--quiet] "
>> + N_("git submodule clone [--prefix=<path>] [--quiet] "
>> "[--reference <repository>] [--name <name>] [--depth <depth>] "
>> "[--single-branch] [--filter <filter-spec>] "
>> "--url <url> --path <path>"),
>> @@ -2787,7 +2787,7 @@ static int absorb_git_dirs(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper absorbgitdirs [<options>] [<path>...]"),
>> + N_("git submodule absorbgitdirs [<options>] [<path>...]"),
>> NULL
>> };
>>
>> @@ -2851,9 +2851,9 @@ static int module_config(int argc, const char **argv, const char *prefix)
>> OPT_END()
>> };
>> const char *const git_submodule_helper_usage[] = {
>> - N_("git submodule--helper config <name> [<value>]"),
>> - N_("git submodule--helper config --unset <name>"),
>> - "git submodule--helper config --check-writeable",
>> + N_("git submodule config <name> [<value>]"),
>> + N_("git submodule config --unset <name>"),
>> + "git submodule config --check-writeable",
>> NULL
>> };
>>
>> @@ -2892,7 +2892,7 @@ static int module_set_url(int argc, const char **argv, const char *prefix)
>> OPT_END()
>> };
>> const char *const usage[] = {
>> - N_("git submodule--helper set-url [--quiet] <path> <newurl>"),
>> + N_("git submodule set-url [--quiet] <path> <newurl>"),
>> NULL
>> };
>>
>> @@ -2931,8 +2931,8 @@ static int module_set_branch(int argc, const char **argv, const char *prefix)
>> OPT_END()
>> };
>> const char *const usage[] = {
>> - N_("git submodule--helper set-branch [-q|--quiet] (-d|--default) <path>"),
>> - N_("git submodule--helper set-branch [-q|--quiet] (-b|--branch) <branch> <path>"),
>> + N_("git submodule set-branch [-q|--quiet] (-d|--default) <path>"),
>> + N_("git submodule set-branch [-q|--quiet] (-b|--branch) <branch> <path>"),
>> NULL
>> };
>>
>> @@ -2973,7 +2973,7 @@ static int module_create_branch(int argc, const char **argv, const char *prefix)
>> OPT_END()
>> };
>> const char *const usage[] = {
>> - N_("git submodule--helper create-branch [-f|--force] [--create-reflog] [-q|--quiet] [-t|--track] [-n|--dry-run] <name> <start-oid> <start-name>"),
>> + N_("git submodule create-branch [-f|--force] [--create-reflog] [-q|--quiet] [-t|--track] [-n|--dry-run] <name> <start-oid> <start-name>"),
>> NULL
>> };
>>
>> @@ -3276,7 +3276,7 @@ static int module_add(int argc, const char **argv, const char *prefix)
>> };
>>
>> const char *const usage[] = {
>> - N_("git submodule--helper add [<options>] [--] <repository> [<path>]"),
>> + N_("git submodule add [<options>] [--] <repository> [<path>]"),
>> NULL
>> };
First, I think this patch is premature, so let's just drop it in a
re-roll. We don't *need* to fix this particular edge case or bug now,
and can just do it as we do the final migration.
> I don't feel positive about pretending to be "git submodule" when the
> subcommand is internal-only. Such commands are only invoked as "git
> submodule--helper foo" and we will probably never turn them into
> external-facing "git submodule foo" [1]. Even if it is internal-only,
> there is a debugging benefit to emitting a usage string with the
> correct, non-user facing command name.
I think we should really be most concerned about the end users here,
nobody except git developers are going to want to invoke
"submodule--helper" directly, so its help messages should be aimed at
helping users.
As you mention in another E-Mail it's currently not a big deal, I
*think* that "absorbgitdirs" is the only case where we'll implicitly
suggest to a user that they might invoke "git submodule--helper" as we
emit the usage info.
But I think for the patches that come after this we should definitely
change this, i.e. we don't want an in-between state where we have both
of builtin/submodule{,--helper}.c because we haven't merged the two yet,
but are now telling users about the inernal-only helper.
> I admit it might be a bit confusing to have a mix of usage strings with
> "submodule--helper" vs "submodule", but as long as we clearly label
> which commands are user-facing and which aren't, it shouldn't be too
> hard to maintain, e.g. this might just be a matter of adding comments to
> the array of commands like:
>
> static struct cmd_struct commands[] = {
> /* User facing commands - pretend to be "git submodule" */
> {"name", module_name},
> {"add", module_add},
> [...]
> /* Internal-only commands */
> {"clone", module_clone},
> {"resolve-relative-url-test", resolve_relative_url_test},
> [...]
> };
>
> Notably, even with this patch we still _kind of_ have 'pseudo usage
> strings' that reference "git submodule--helper". These are just
> internal-only commands that don't use the parse_options() API, e.g.
>
> if (argc < 3)
> die("submodule--helper push-check requires at least 2 arguments");
>
> I think it's ok to leave them as-is, provided we also leave the other
> internal-only commands as-is.
Yes let's leave them, we'll be converting these to not invoke
sub-processes sooner than later anyway.
> [1] For convenience, here is a list of all of the subcommands changed in
> this patch and whether they are user-facing/internal-only:
>
> User-facing Internal-only
>
> - foreach - list
> - init - name
> - summary - clone
> - sync - config
> - absorbgitdirs - create-branch
> - set-url
> - set-branch
> - add
But yeah, if/when we change the public-facing usage strings we should be
leaving out the "internal-only" commands, thanks. I just did a dumb
search/replace.
next prev parent reply other threads:[~2022-06-15 10:14 UTC|newest]
Thread overview: 90+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-10 0:26 [PATCH 0/8] [RFC] submodule update: parse all options in C Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 1/8] submodule update: remove intermediate parsing Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 2/8] submodule update: pass options containing "[no-]" Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 3/8] submodule update: pass options with stuck forms Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 4/8] submodule update: pass --require-init and --init Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 5/8] submodule--helper update: use one param per type Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 6/8] submodule update: remove -v, pass --quiet Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 7/8] submodule update: stop parsing options in .sh Glen Choo via GitGitGadget
2022-06-10 0:26 ` [PATCH 8/8] submodule update: remove never-used expansion Glen Choo via GitGitGadget
2022-06-10 2:01 ` [RFC PATCH 00/20] submodule: remove git-submodule.sh, create bare builtin/submodule.c Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 01/20] git-submodule.sh: remove unused sanitize_submodule_env() Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 02/20] git-submodule.sh: remove unused $prefix variable Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 03/20] git-submodule.sh: remove unused --super-prefix logic Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 04/20] git-submodule.sh: normalize parsing of "--branch" Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 05/20] git-submodule.sh: normalize parsing of --cached Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 06/20] submodule--helper: rename "absorb-git-dirs" to "absorbgitdirs" Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 07/20] git-submodule.sh: create a "case" dispatch statement Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 08/20] submodule--helper: pretend to be "git submodule" in "-h" output Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 09/20] git-submodule.sh: dispatch "sync" to helper Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 10/20] git-submodule.sh: dispatch directly " Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 11/20] git-submodule.sh: dispatch "foreach" " Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 12/20] submodule--helper: have --require-init imply --init Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 13/20] submodule--helper: understand --checkout, --merge and --rebase synonyms Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 14/20] git-submodule doc: document the -v" option to "update" Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 15/20] submodule--helper: understand -v option for "update" Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 16/20] git-submodule.sh: dispatch "update" to helper Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 17/20] git-submodule.sh: use "$quiet", not "$GIT_QUIET" Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 18/20] git-submodule.sh: simplify parsing loop Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 19/20] submodule: make it a built-in, remove git-submodule.sh Ævar Arnfjörð Bjarmason
2022-06-10 2:01 ` [RFC PATCH 20/20] submodule: add a subprocess-less submodule.useBuiltin setting Ævar Arnfjörð Bjarmason
2022-06-13 19:07 ` [RFC PATCH 00/20] submodule: remove git-submodule.sh, create bare builtin/submodule.c Glen Choo
2022-06-13 22:38 ` [PATCH v2 00/12] submodule: make "git submodule--helper" behave like "git submodule" Ævar Arnfjörð Bjarmason
2022-06-13 22:38 ` [PATCH v2 01/12] git-submodule.sh: remove unused sanitize_submodule_env() Ævar Arnfjörð Bjarmason
2022-06-13 22:38 ` [PATCH v2 02/12] git-submodule.sh: remove unused $prefix var and --super-prefix Ævar Arnfjörð Bjarmason
2022-06-13 22:38 ` [PATCH v2 03/12] git-submodule.sh: make "$cached" variable a boolean Ævar Arnfjörð Bjarmason
2022-06-13 22:38 ` [PATCH v2 04/12] git-submodule.sh: remove unused top-level "--branch" argument Ævar Arnfjörð Bjarmason
2022-06-15 0:10 ` Glen Choo
2022-06-13 22:38 ` [PATCH v2 05/12] submodule--helper: have --require-init imply --init Ævar Arnfjörð Bjarmason
2022-06-15 0:19 ` Glen Choo
2022-06-13 22:38 ` [PATCH v2 06/12] submodule update: remove "-v" option Ævar Arnfjörð Bjarmason
2022-06-15 0:29 ` Glen Choo
2022-06-13 22:38 ` [PATCH v2 07/12] submodule--helper: rename "absorb-git-dirs" to "absorbgitdirs" Ævar Arnfjörð Bjarmason
2022-06-13 22:38 ` [PATCH v2 08/12] submodule--helper: report "submodule" as our name in "-h" output Ævar Arnfjörð Bjarmason
2022-06-15 3:34 ` Glen Choo
2022-06-15 4:01 ` Glen Choo
2022-06-15 9:42 ` Ævar Arnfjörð Bjarmason [this message]
2022-06-13 22:39 ` [PATCH v2 09/12] submodule--helper: understand --checkout, --merge and --rebase synonyms Ævar Arnfjörð Bjarmason
2022-06-13 22:39 ` [PATCH v2 10/12] submodule--helper: eliminate internal "--update" option Ævar Arnfjörð Bjarmason
2022-06-15 16:52 ` Glen Choo
2022-06-13 22:39 ` [PATCH v2 11/12] git-submodule.sh: use "$quiet", not "$GIT_QUIET" Ævar Arnfjörð Bjarmason
2022-06-13 22:39 ` [PATCH v2 12/12] git-sh-setup.sh: remove "say" function, change last users Ævar Arnfjörð Bjarmason
2022-06-15 16:58 ` Glen Choo
2022-06-13 23:09 ` [PATCH v2 00/12] submodule: make "git submodule--helper" behave like "git submodule" Glen Choo
2022-06-13 23:31 ` Ævar Arnfjörð Bjarmason
2022-06-15 0:00 ` Glen Choo
2022-06-15 18:42 ` Glen Choo
2022-06-22 14:27 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
2022-06-22 14:27 ` [PATCH v3 01/12] git-submodule.sh: remove unused sanitize_submodule_env() Ævar Arnfjörð Bjarmason
2022-06-22 14:27 ` [PATCH v3 02/12] git-submodule.sh: remove unused $prefix var and --super-prefix Ævar Arnfjörð Bjarmason
2022-06-22 23:43 ` Glen Choo
2022-06-24 15:07 ` Ævar Arnfjörð Bjarmason
2022-06-24 16:48 ` Glen Choo
2022-06-22 14:27 ` [PATCH v3 03/12] git-submodule.sh: make the "$cached" variable a boolean Ævar Arnfjörð Bjarmason
2022-06-22 14:27 ` [PATCH v3 04/12] git-submodule.sh: remove unused top-level "--branch" argument Ævar Arnfjörð Bjarmason
2022-06-22 14:28 ` [PATCH v3 05/12] submodule--helper: have --require-init imply --init Ævar Arnfjörð Bjarmason
2022-06-22 14:28 ` [PATCH v3 06/12] submodule update: remove "-v" option Ævar Arnfjörð Bjarmason
2022-06-22 14:28 ` [PATCH v3 07/12] submodule--helper: rename "absorb-git-dirs" to "absorbgitdirs" Ævar Arnfjörð Bjarmason
2022-06-22 14:28 ` [PATCH v3 08/12] submodule--helper: report "submodule" as our name in some "-h" output Ævar Arnfjörð Bjarmason
2022-06-22 18:28 ` Glen Choo
2022-06-22 14:28 ` [PATCH v3 09/12] submodule--helper: understand --checkout, --merge and --rebase synonyms Ævar Arnfjörð Bjarmason
2022-06-22 18:57 ` Glen Choo
2022-06-22 19:04 ` Glen Choo
2022-06-22 14:28 ` [PATCH v3 10/12] submodule--helper: eliminate internal "--update" option Ævar Arnfjörð Bjarmason
2022-06-22 14:28 ` [PATCH v3 11/12] git-submodule.sh: use "$quiet", not "$GIT_QUIET" Ævar Arnfjörð Bjarmason
2022-06-22 14:28 ` [PATCH v3 12/12] git-sh-setup.sh: remove "say" function, change last users Ævar Arnfjörð Bjarmason
2022-06-24 3:39 ` [PATCH v3 00/12] submodule: make "git submodule--helper" behave like "git submodule" Glen Choo
2022-06-28 10:05 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 01/12] git-submodule.sh: remove unused sanitize_submodule_env() Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 02/12] git-submodule.sh: remove unused $prefix variable Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 03/12] git-submodule.sh: make the "$cached" variable a boolean Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 04/12] git-submodule.sh: remove unused top-level "--branch" argument Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 05/12] submodule--helper: have --require-init imply --init Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 06/12] submodule update: remove "-v" option Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 07/12] submodule--helper: rename "absorb-git-dirs" to "absorbgitdirs" Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 08/12] submodule--helper: report "submodule" as our name in some "-h" output Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 09/12] submodule--helper: understand --checkout, --merge and --rebase synonyms Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 10/12] submodule--helper: eliminate internal "--update" option Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 11/12] git-submodule.sh: use "$quiet", not "$GIT_QUIET" Ævar Arnfjörð Bjarmason
2022-06-28 10:05 ` [PATCH v4 12/12] git-sh-setup.sh: remove "say" function, change last users Ævar Arnfjörð Bjarmason
2022-06-28 16:52 ` [PATCH v4 00/12] submodule: make "git submodule--helper" behave like "git submodule" Glen Choo
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
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=220615.86r13qxmjx.gmgdl@evledraar.gmail.com \
--to=avarab@gmail.com \
--cc=chooglen@google.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=raykar.ath@gmail.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.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).