worktree add: improve message for ambiguous remote branch name #2197
+134
−44
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -1343,13 +1343,51 @@ enum checkout_command { | |
| CHECKOUT_RESTORE = 3, | ||
|
There was a problem hiding this comment. "D. Ben Knoble" wrote on the Git mailing list (how to reply to this email): On Wed, Aug 19, 2026 at 8:51 AM Yoichi NAKAYAMA via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> When the user runs 'git checkout bar-topic' command that does not
> exactly say which remote they want to work with, and there is no local
> branch named bar-topic, we try to guess which remote by passing
> bar-topic then create a new branch named bar-topic which tracks the
> remote branch.
>
> If multiple remotes have a branch named bar-topic, we cannot determine
> a single specific remote. Therefore, we provide information that the
> user can utilize to resolve the issue.
>
> To make the advice more feasible, we will provide matched remote names
> for the specified branch name.
>
> To achive that, we add an optional feature to the
> `unique_tracking_name()` function that allows the matched remote name
> to be exposed to the caller.
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> ---
> builtin/checkout.c | 75 +++++++++++++++++++++++++++-------------------
> builtin/worktree.c | 4 +--
> checkout.c | 14 +++++++--
> checkout.h | 5 +++-
> 4 files changed, 63 insertions(+), 35 deletions(-)
>
> diff --git a/builtin/checkout.c b/builtin/checkout.c
> index 55e3a89a85..a2749352e6 100644
> --- a/builtin/checkout.c
> +++ b/builtin/checkout.c
> @@ -1343,13 +1343,51 @@ enum checkout_command {
> CHECKOUT_RESTORE = 3,
> };
>
> +static void be_explicit(const char *branch,
Be explicit about what? Reading below, a better name might be
"advise_ambiguous_remote_branch_name" or something, idk.
> + enum checkout_command which_command,
> + const struct string_list *matched_remote_names)
> +{
> + const char *cmdname;
> + struct string_list_item *item;
> +
> + switch (which_command) {
> + case CHECKOUT_CHECKOUT:
> + cmdname = "checkout";
> + break;
> + case CHECKOUT_SWITCH:
> + cmdname = "switch";
> + break;
> + default:
> + BUG("command <%d> should not reach parse_remote_branch",
> + which_command);
> + break;
> + }
> +
> + advise(_("Branches with the same name appears in multiple remotes:"));
> + for_each_string_list_item(item, matched_remote_names) {
> + advise(_(" %s"), item->string);
> + }
> + advise(_("If you meant to check out a remote tracking branch on <remote>,\n"
> + "you can do so by fully qualifying the name with the --track option:\n"
> + "\n"
> + " git %s --track <remote>/%s\n"
> + "\n"
> + "If you'd like to always have checkouts of an ambiguous name prefer\n"
> + "one remote, e.g. the 'origin' remote, consider setting\n"
> + "checkout.defaultRemote=origin in your config."),
> + cmdname, branch);
> +}
> +
I think it's possible this refactor is a bit distracting from the
overall goal of the patch, though I don't think extracting the
function is a bad thing. Maybe split the steps up into
- mechanical refactoring (no behavior change)
- changes to improve the message (easier to see the diff)
? Just my 2 cents.
> static char *parse_remote_branch(const char *arg,
> struct object_id *rev,
> int could_be_checkout_paths,
> enum checkout_command which_command)
> {
> int num_matches = 0;
> - char *remote = unique_tracking_name(arg, rev, &num_matches);
> + struct string_list matched_remote_names = STRING_LIST_INIT_DUP;
> +
> + char *remote = unique_tracking_name(arg, rev, &num_matches,
> + &matched_remote_names);
>
> if (remote && could_be_checkout_paths) {
> die(_("'%s' could be both a local file and a tracking branch.\n"
> @@ -1358,37 +1396,14 @@ static char *parse_remote_branch(const char *arg,
> }
>
> if (!remote && num_matches > 1) {
> - if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME)) {
> - const char *cmdname;
> -
> - switch (which_command) {
> - case CHECKOUT_CHECKOUT:
> - cmdname = "checkout";
> - break;
> - case CHECKOUT_SWITCH:
> - cmdname = "switch";
> - break;
> - default:
> - BUG("command <%d> should not reach parse_remote_branch",
> - which_command);
> - break;
> - }
> -
> - advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
> - "you can do so by fully qualifying the name with the --track option:\n"
> - "\n"
> - " git %s --track origin/<name>\n"
> - "\n"
> - "If you'd like to always have checkouts of an ambiguous <name> prefer\n"
> - "one remote, e.g. the 'origin' remote, consider setting\n"
> - "checkout.defaultRemote=origin in your config."),
> - cmdname);
> - }
> -
> - die(_("'%s' matched multiple (%d) remote tracking branches"),
> - arg, num_matches);
> + if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> + be_explicit(arg, which_command, &matched_remote_names);
> + die(_("'%s' matched multiple (%d) remote tracking branches"),
> + arg, num_matches);
> }
>
> + string_list_clear(&matched_remote_names, 0);
> +
> return remote;
> }
[rest of diff snipped]There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>> +static void be_explicit(const char *branch,
>
> Be explicit about what? Reading below, a better name might be
> "advise_ambiguous_remote_branch_name" or something, idk.
It stands for "tell the user to be more explicit". I agree with you
that the refactoring should be done as a separate step, on top of
which we should add the new feature, i.e., "give list of possible
candidates", as a separate step.There was a problem hiding this comment. Yoichi Nakayama wrote on the Git mailing list (how to reply to this email): On Thu, Aug 20, 2026 at 11:18 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>
> >> +static void be_explicit(const char *branch,
> >
> > Be explicit about what? Reading below, a better name might be
> > "advise_ambiguous_remote_branch_name" or something, idk.
>
> It stands for "tell the user to be more explicit". I agree with you
> that the refactoring should be done as a separate step, on top of
> which we should add the new feature, i.e., "give list of possible
> candidates", as a separate step.
I think it's a good idea to separate the steps, so I'll split the commits.
I am considering "advise_disambiguating_remotes" as a better function name.
Thanks,
--
Yoichi NAKAYAMA |
||
| }; | ||
|
|
||
| static void advise_disambiguating_remotes(enum checkout_command which_command, | ||
| const char *branch, | ||
| const struct string_list *matched_remote_names) | ||
| { | ||
| const char *cmdname; | ||
| struct string_list_item *item; | ||
|
|
||
| switch (which_command) { | ||
| case CHECKOUT_CHECKOUT: | ||
| cmdname = "checkout"; | ||
| break; | ||
| case CHECKOUT_SWITCH: | ||
| cmdname = "switch"; | ||
| break; | ||
| default: | ||
| BUG("command <%d> should not reach parse_remote_branch", | ||
| which_command); | ||
| break; | ||
| } | ||
|
|
||
| advise(_("Branch name '%s' appears in multiple remotes:"), branch); | ||
| for_each_string_list_item(item, matched_remote_names) { | ||
| advise(_(" %s"), item->string); | ||
| } | ||
| advise(_("If you meant to check out a remote tracking branch on <remote>,\n" | ||
| "you can do so by fully qualifying the name with the --track option:\n" | ||
| "\n" | ||
| " git %s --track <remote>/%s\n" | ||
| "\n" | ||
| "If you'd like to always have checkouts of an ambiguous name prefer\n" | ||
| "one remote, e.g. the 'origin' remote, consider setting\n" | ||
| "checkout.defaultRemote=origin in your config."), | ||
| cmdname, branch); | ||
| } | ||
|
|
||
| static char *parse_remote_branch(const char *arg, | ||
| struct object_id *rev, | ||
| int could_be_checkout_paths, | ||
| enum checkout_command which_command) | ||
| { | ||
| int num_matches = 0; | ||
| struct string_list matched_remote_names = STRING_LIST_INIT_DUP; | ||
|
|
||
| char *remote = unique_tracking_name(arg, rev, &num_matches, | ||
| &matched_remote_names); | ||
|
|
||
| if (remote && could_be_checkout_paths) { | ||
| die(_("'%s' could be both a local file and a tracking branch.\n" | ||
|
|
@@ -1358,37 +1396,15 @@ static char *parse_remote_branch(const char *arg, | |
| } | ||
|
|
||
| if (!remote && num_matches > 1) { | ||
| if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME)) | ||
| advise_disambiguating_remotes(which_command, arg, | ||
| &matched_remote_names); | ||
| die(_("'%s' matched multiple (%d) remote tracking branches"), | ||
| arg, num_matches); | ||
| } | ||
|
|
||
| string_list_clear(&matched_remote_names, 0); | ||
|
|
||
| return remote; | ||
| } | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -764,7 +764,26 @@ static int dwim_orphan(const struct add_opts *opts, int opt_track, int remote) | |
| return 1; | ||
| } | ||
|
|
||
| static void advise_disambiguating_remotes(const char *path, const char *branch, | ||
| const struct string_list *matched_remote_names) | ||
| { | ||
| struct string_list_item *item; | ||
|
|
||
| advise(_("Branch name '%s' appears in multiple remotes:"), branch); | ||
| for_each_string_list_item(item, matched_remote_names) { | ||
| advise(_(" %s"), item->string); | ||
| } | ||
| advise(_("If you meant to create a worktree from a remote tracking branch on\n" | ||
| "<remote>, you can do so by:\n" | ||
| "\n" | ||
| " git worktree add -b %s %s <remote>/%s\n" | ||
| "\n" | ||
| "If you'd like to always prefer some remote, e.g. 'origin',\n" | ||
| "consider setting checkout.defaultRemote=origin in your config."), | ||
| branch, path, branch); | ||
| } | ||
|
|
||
| static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch) | ||
| { | ||
| int n; | ||
| int branch_exists; | ||
|
|
@@ -782,7 +801,21 @@ static char *dwim_branch(const char *path, char **new_branch) | |
| *new_branch = branchname; | ||
| if (guess_remote) { | ||
| struct object_id oid; | ||
| char *remote; | ||
| int num_matches = 0; | ||
| struct string_list matched_remote_names = STRING_LIST_INIT_DUP; | ||
|
|
||
| remote = unique_tracking_name(*new_branch, &oid, &num_matches, | ||
| &matched_remote_names); | ||
| if (!remote && num_matches > 1) { | ||
| if (!opts->quiet && | ||
| advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME)) | ||
| advise_disambiguating_remotes(path, *new_branch, | ||
| &matched_remote_names); | ||
| die(_("'%s' matched multiple (%d) remote tracking branches"), | ||
| *new_branch, num_matches); | ||
| } | ||
| string_list_clear(&matched_remote_names, 0); | ||
| return remote; | ||
| } | ||
| return NULL; | ||
|
There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): "Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> When the user runs 'git worktree add ../foo-dir bar-topic' command
> that does not exactly say which remote they want to work with, and
> there is no local branch named bar-topic, we try to guess which remote
> by passing bar-topic then create a new branch named bar-topic which
> tracks the remote branch.
>
> If there are multiple remotes that have branch named bar-topic, we
> silently gave up, leaving the variable 'branch' intact. Then we
> entered the conditional clause 'if (!opts.orphan &&
> !lookup_commit_reference_by_name(branch))' and triggered "invalid
> reference" error. This error message did not contain enough
> information to resolve the issue where the remote could not be
> guessed.
>
> To improve the situation, we display a hint and a descriptive error
> message and die immediately when multiple matching branches are found.
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> ---
> builtin/worktree.c | 35 +++++++++++++++++++++++++++++++++--
> t/t2400-worktree-add.sh | 4 ++--
> 2 files changed, 35 insertions(+), 4 deletions(-)
>
> diff --git a/builtin/worktree.c b/builtin/worktree.c
> index 22c8e5e131..8286c283e0 100644
> --- a/builtin/worktree.c
> +++ b/builtin/worktree.c
> @@ -788,6 +788,25 @@ static char *dwim_branch(const char *path, char **new_branch)
> return NULL;
> }
>
> +static void advise_disambiguating_remotes(const char *path, const char *branch,
> + const struct string_list *matched_remote_names)
> +{
> + struct string_list_item *item;
> +
> + advise(_("Branches with the same name appears in multiple remotes:"));
The subject "Branches" calls for plural verb "appear" (not
"appears"). The same issue appears in [PATCH 2/3].
> if (!commit) {
> - remote = unique_tracking_name(branch, &oid, NULL, NULL);
> + char *remote;
> + int num_matches = 0;
> + struct string_list matched_remote_names = STRING_LIST_INIT_DUP;
> +
> + remote = unique_tracking_name(branch, &oid, &num_matches,
> + &matched_remote_names);
> if (remote) {
> new_branch = branch;
> branch = new_branch_to_free = remote;
> + } else if (num_matches > 1) {
> + if (!opts.quiet &&
> + advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> + advise_disambiguating_remotes(path, branch,
> + &matched_remote_names);
> + die(_("'%s' matched multiple (%d) remote tracking branches"),
> + branch, num_matches);
> }
> + string_list_clear(&matched_remote_names, 0);
> }
This appears inside "} else if (ac == 2) {" to catch an invocation
like
git worktree add ../over-there topic-branch
where the origin of topic-branch is ambiguous (in other words,
appears in multiple remotes). But don't we have the same issue for
1 argument case that appears just above this (ac == 2) case that
handles
git worktree add ../topic-branch
invocation? The code reads like:
} else if (ac < 2) {
/* DWIM: Guess branch name from path. */
char *s = dwim_branch(path, &new_branch_to_free);
if (s)
branch = branch_to_free = s;
new_branch = new_branch_to_free;
/* DWIM: Infer --orphan when repo has no refs. */
opts.orphan = (!s) && dwim_orphan(&opts, !!opt_track, 1);
} else if (ac == 2) {
where the branch name "topic-branch" is guessed from the path by
calling dwim_branch(), and we would get NULL in s. branch is left
as-is, so it becomes "HEAD" that was assigned much earlier in the
same function.
branch = ac < 2 ? "HEAD" : av[1];
We would create a new directory in ../topic-branch next door, and
then which branch would we check out? Would dwim_orphan() kick in?
Perhaps we want to update that code path to disambiguate the same way?
> diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
> index 87b926728a..5c105cf252 100755
> --- a/t/t2400-worktree-add.sh
> +++ b/t/t2400-worktree-add.sh
> @@ -624,12 +624,12 @@ test_expect_success '"add" <path> <branch> dwims' '
> test_expect_success '"add" <path> <branch> dwims with checkout.defaultRemote' '
> test_when_finished rm -rf repo_upstream repo_dwim foo &&
> setup_remote_repo repo_upstream repo_dwim &&
> - git init repo_dwim &&
> (
> cd repo_dwim &&
> git remote add repo_upstream2 ../repo_upstream &&
> git fetch repo_upstream2 &&
> - test_must_fail git worktree add ../foo foo &&
> + test_must_fail git worktree add ../foo foo 2>error.actual &&
> + test_grep "matched multiple (2) remote tracking branches" error.actual &&
> git -c checkout.defaultRemote=repo_upstream worktree add ../foo foo &&
> git status -uno --porcelain >status.actual &&
> test_must_be_empty status.actualThere was a problem hiding this comment. Yoichi Nakayama wrote on the Git mailing list (how to reply to this email): On Fri, Aug 21, 2026 at 12:54 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> >
> > diff --git a/builtin/worktree.c b/builtin/worktree.c
> > index 22c8e5e131..8286c283e0 100644
> > --- a/builtin/worktree.c
> > +++ b/builtin/worktree.c
> > @@ -788,6 +788,25 @@ static char *dwim_branch(const char *path, char **new_branch)
> > return NULL;
> > }
> >
> > +static void advise_disambiguating_remotes(const char *path, const char *branch,
> > + const struct string_list *matched_remote_names)
> > +{
> > + struct string_list_item *item;
> > +
> > + advise(_("Branches with the same name appears in multiple remotes:"));
>
> The subject "Branches" calls for plural verb "appear" (not
> "appears"). The same issue appears in [PATCH 2/3].
I overlooked that. Thank you.
Rather than simply matching the verb to the subject, I want to clarify
what (as specified by the user) exists on multiple remotes:
advise(_("Branch name '%s' appears in multiple remotes:"), branch);
> > if (!commit) {
> > - remote = unique_tracking_name(branch, &oid, NULL, NULL);
> > + char *remote;
> > + int num_matches = 0;
> > + struct string_list matched_remote_names = STRING_LIST_INIT_DUP;
> > +
> > + remote = unique_tracking_name(branch, &oid, &num_matches,
> > + &matched_remote_names);
> > if (remote) {
> > new_branch = branch;
> > branch = new_branch_to_free = remote;
> > + } else if (num_matches > 1) {
> > + if (!opts.quiet &&
> > + advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> > + advise_disambiguating_remotes(path, branch,
> > + &matched_remote_names);
> > + die(_("'%s' matched multiple (%d) remote tracking branches"),
> > + branch, num_matches);
> > }
> > + string_list_clear(&matched_remote_names, 0);
> > }
>
> This appears inside "} else if (ac == 2) {" to catch an invocation
> like
>
> git worktree add ../over-there topic-branch
>
> where the origin of topic-branch is ambiguous (in other words,
> appears in multiple remotes). But don't we have the same issue for
> 1 argument case that appears just above this (ac == 2) case that
> handles
>
> git worktree add ../topic-branch
>
> invocation? The code reads like:
>
> } else if (ac < 2) {
> /* DWIM: Guess branch name from path. */
> char *s = dwim_branch(path, &new_branch_to_free);
> if (s)
> branch = branch_to_free = s;
> new_branch = new_branch_to_free;
>
> /* DWIM: Infer --orphan when repo has no refs. */
> opts.orphan = (!s) && dwim_orphan(&opts, !!opt_track, 1);
> } else if (ac == 2) {
>
> where the branch name "topic-branch" is guessed from the path by
> calling dwim_branch(), and we would get NULL in s. branch is left
> as-is, so it becomes "HEAD" that was assigned much earlier in the
> same function.
>
> branch = ac < 2 ? "HEAD" : av[1];
>
> We would create a new directory in ../topic-branch next door, and
> then which branch would we check out? Would dwim_orphan() kick in?
>
> Perhaps we want to update that code path to disambiguate the same way?
In the case of
git worktree add ../topic-branch
invocation, multiple match can occur in dwim_branch() if there is a
'worktree.guessremote=true' config or one specifies '--guess-remote'
option.Then it creates a branch named 'topic-branch' from HEAD, and
the command exits with success.
My initial patch included a warning and advice here,
but now I don't think they are necessary.
Even if multiple remotes match here, the command completes
successfully. This could well be the intended behavior
(just as when there is no match). In that case, a warning
or advice might be superfluous.
From the perspective of offering advice that actually
helps the user, since the branch and worktree have already
been created, the appropriate guidance would be to suggest
deleting them and starting over. That, however, would
likely make the message even longer.
If there were an option (which currently doesn't exist)
to make the command fail when remote inference fails,
then I think it would be appropriate to issue the same
advice and error message as in "ac == 2" case.
Thanks,
--
Yoichi NAKAYAMAThere was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
> My initial patch included a warning and advice here,
> but now I don't think they are necessary.
>
> Even if multiple remotes match here, the command completes
> successfully. This could well be the intended behavior
> (just as when there is no match). In that case, a warning
> or advice might be superfluous.
In other words, there is no point in calling dwim_branch() from that
code path, as the end result is exactly the same whether no remotes
match, exactly one remote matches, or two or more remotes match?
Would it then make sense to leave a note there to consider later if
the dwim_branch() call can be removed?
It is a bit hard to believe that is the intended behavior, but OK.
It does not regress the current behavior in any way.
Thanks.
There was a problem hiding this comment. Yoichi Nakayama wrote on the Git mailing list (how to reply to this email): On Sat, Aug 22, 2026 at 8:49 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
>
> > My initial patch included a warning and advice here,
> > but now I don't think they are necessary.
> >
> > Even if multiple remotes match here, the command completes
> > successfully. This could well be the intended behavior
> > (just as when there is no match). In that case, a warning
> > or advice might be superfluous.
>
> In other words, there is no point in calling dwim_branch() from that
> code path, as the end result is exactly the same whether no remotes
> match, exactly one remote matches, or two or more remotes match?
> Would it then make sense to leave a note there to consider later if
> the dwim_branch() call can be removed?
No. The exit codes of the command 'git worktree add ../topic-branch'
are the same (== 0). but the results are different.
If there is a unique match found in dwim_branch(), it creates a local
branch named topic-branch which tracks <remote>/topic-branch.
In case of no match or multiple matches, it creates a local branch
named topic-branch from HEAD.
Since Git treats both cases as successful, either can be considered
the intended behavior.
(Although, if there are multiple matches, there is a fair chance the
result might not be what was intended.)
I am confident that it is appropriate to provide a hint when a command
fails, but it is difficult to decide what to do when a command succeeds.
Thanks,
--
Yoichi NAKAYAMAThere was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
> No. The exit codes of the command 'git worktree add ../topic-branch'
> are the same (== 0). but the results are different.
>
> If there is a unique match found in dwim_branch(), it creates a local
> branch named topic-branch which tracks <remote>/topic-branch.
> In case of no match or multiple matches, it creates a local branch
> named topic-branch from HEAD.
>
> Since Git treats both cases as successful, either can be considered
> the intended behavior.
> (Although, if there are multiple matches, there is a fair chance the
> result might not be what was intended.)
>
> I am confident that it is appropriate to provide a hint when a command
> fails, but it is difficult to decide what to do when a command succeeds.
I actually think it falls into the same class of bug you are fixing
in this topic, which was caused by not considering the possibility
that there can be any case other than 0-match and 1-match, and not
thinking through the ramifications of treating 2-match and 0-match
the same way.
It is of course OK to fix one bug and leave the other one
unaddressed, to be fixed in a later follow-up effort.
The rest of this message is only for those who will tackle the
"later follow-up effort" part after the dust settles once the
current topic lands (aka #leftoverbits).
In the beginning, before Thomas Gummerer started his topic in
November 2017 [*1*], 'git worktree add <path> [<branch>]' created a
new branch from the checked-out HEAD, without looking at any
remote.
- 'git worktree add <path> <branch>' before Thomas's effort errored
out if <branch> did not exist. It was safe to add DWIM from
remote-tracking branches without requiring any option.
- 'git worktree add <path>' used to create a new branch whose name
is derived from basename(path) that points at the current HEAD,
without erroring out. Enabling DWIM from remote-tracking
branches unconditionally would have meant a silent behavior
change. So DWIM was added to this case to require the
'--guess-remote' option to enable [*2*].
Back then, unique_tracking_name() did not let the callers
distinguish between 0-match and multiple-match cases, so when you
had multiple matches, 'git worktree add <path> [<branch>]' triggered
the same code path as 0-matches. When the DWIM feature was
designed, handling the multiple-match case correctly was on nobody's
radar.
Even when Ævar Arnfjörð Bjarmason updated unique_tracking_name() in
3c87aa946a (checkout: pass the "num_matches" up to callers,
2018-06-05), in a topic that ends at 8d7b558bae (checkout &
worktree: introduce checkout.defaultRemote, 2018-06-05), to allow
callers to distinguish between 0-match and ambiguous multi-match
cases, this work unfortunately concentrated on improving "git
checkout", and callers of unique_tracking_name() in "git worktree"
were updated to pass NULL, i.e., teaching them to count how many
matches they got was postponed.
We know that the update to unique_tracking_name() in this work back
then was not complete on the "git worktree" side. After all, that
is how this topic arose to fix one of the two code paths that call
the function so that we react differently between 0-match and
multiple-match cases.
Now that we are aware of the issue, I think the code should error
out, instead of creating the new branch out of HEAD, when there are
multiple remotes with the name of the branch. In other words, the
existing code that behaves the same way in 0-match and 2-match cases
is buggy, and we should eventually fix it.
[Footnotes]
*1* https://lore.kernel.org/git/20171112134305.3949-1-t.gummerer@gmail.com/
*2* https://lore.kernel.org/git/20171126194356.16187-1-t.gummerer@gmail.com/There was a problem hiding this comment. Yoichi Nakayama wrote on the Git mailing list (how to reply to this email): On Sun, Aug 23, 2026 at 2:22 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
>
> > No. The exit codes of the command 'git worktree add ../topic-branch'
> > are the same (== 0). but the results are different.
> >
> > If there is a unique match found in dwim_branch(), it creates a local
> > branch named topic-branch which tracks <remote>/topic-branch.
> > In case of no match or multiple matches, it creates a local branch
> > named topic-branch from HEAD.
> >
> > Since Git treats both cases as successful, either can be considered
> > the intended behavior.
> > (Although, if there are multiple matches, there is a fair chance the
> > result might not be what was intended.)
> >
> > I am confident that it is appropriate to provide a hint when a command
> > fails, but it is difficult to decide what to do when a command succeeds.
>
> I actually think it falls into the same class of bug you are fixing
> in this topic, which was caused by not considering the possibility
> that there can be any case other than 0-match and 1-match, and not
> thinking through the ramifications of treating 2-match and 0-match
> the same way.
>
> It is of course OK to fix one bug and leave the other one
> unaddressed, to be fixed in a later follow-up effort.
>
> The rest of this message is only for those who will tackle the
> "later follow-up effort" part after the dust settles once the
> current topic lands (aka #leftoverbits).
>
> In the beginning, before Thomas Gummerer started his topic in
> November 2017 [*1*], 'git worktree add <path> [<branch>]' created a
> new branch from the checked-out HEAD, without looking at any
> remote.
>
> - 'git worktree add <path> <branch>' before Thomas's effort errored
> out if <branch> did not exist. It was safe to add DWIM from
> remote-tracking branches without requiring any option.
>
> - 'git worktree add <path>' used to create a new branch whose name
> is derived from basename(path) that points at the current HEAD,
> without erroring out. Enabling DWIM from remote-tracking
> branches unconditionally would have meant a silent behavior
> change. So DWIM was added to this case to require the
> '--guess-remote' option to enable [*2*].
>
> Back then, unique_tracking_name() did not let the callers
> distinguish between 0-match and multiple-match cases, so when you
> had multiple matches, 'git worktree add <path> [<branch>]' triggered
> the same code path as 0-matches. When the DWIM feature was
> designed, handling the multiple-match case correctly was on nobody's
> radar.
>
> Even when Ævar Arnfjörð Bjarmason updated unique_tracking_name() in
> 3c87aa946a (checkout: pass the "num_matches" up to callers,
> 2018-06-05), in a topic that ends at 8d7b558bae (checkout &
> worktree: introduce checkout.defaultRemote, 2018-06-05), to allow
> callers to distinguish between 0-match and ambiguous multi-match
> cases, this work unfortunately concentrated on improving "git
> checkout", and callers of unique_tracking_name() in "git worktree"
> were updated to pass NULL, i.e., teaching them to count how many
> matches they got was postponed.
>
> We know that the update to unique_tracking_name() in this work back
> then was not complete on the "git worktree" side. After all, that
> is how this topic arose to fix one of the two code paths that call
> the function so that we react differently between 0-match and
> multiple-match cases.
>
> Now that we are aware of the issue, I think the code should error
> out, instead of creating the new branch out of HEAD, when there are
> multiple remotes with the name of the branch. In other words, the
> existing code that behaves the same way in 0-match and 2-match cases
> is buggy, and we should eventually fix it.
>
>
> [Footnotes]
>
> *1* https://lore.kernel.org/git/20171112134305.3949-1-t.gummerer@gmail.com/
> *2* https://lore.kernel.org/git/20171126194356.16187-1-t.gummerer@gmail.com/
Thank you for the analysis. I believe the behavior of treating multiple matches
as an error is appropriate.
I feel that now is the time to implement the fix that had been postponed.
I'll make another commit for it.
Thanks,
--
Yoichi NAKAYAMA |
||
|
|
@@ -890,25 +923,37 @@ static int add(int ac, const char **av, const char *prefix, | |
| opts.orphan = dwim_orphan(&opts, !!opt_track, 0); | ||
| } else if (ac < 2) { | ||
| /* DWIM: Guess branch name from path. */ | ||
| char *s = dwim_branch(&opts, path, &new_branch_to_free); | ||
| if (s) | ||
| branch = branch_to_free = s; | ||
| new_branch = new_branch_to_free; | ||
|
|
||
| /* DWIM: Infer --orphan when repo has no refs. */ | ||
| opts.orphan = (!s) && dwim_orphan(&opts, !!opt_track, 1); | ||
| } else if (ac == 2) { | ||
| struct commit *commit; | ||
|
|
||
| commit = lookup_commit_reference_by_name(branch); | ||
| if (!commit) { | ||
| struct object_id oid; | ||
| char *remote; | ||
| int num_matches = 0; | ||
| struct string_list matched_remote_names = STRING_LIST_INIT_DUP; | ||
|
|
||
| remote = unique_tracking_name(branch, &oid, &num_matches, | ||
| &matched_remote_names); | ||
| if (remote) { | ||
| new_branch = branch; | ||
| branch = new_branch_to_free = remote; | ||
| } else if (num_matches > 1) { | ||
| if (!opts.quiet && | ||
| advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME)) | ||
| advise_disambiguating_remotes(path, branch, | ||
| &matched_remote_names); | ||
| die(_("'%s' matched multiple (%d) remote tracking branches"), | ||
| branch, num_matches); | ||
| } | ||
| string_list_clear(&matched_remote_names, 0); | ||
| } | ||
|
|
||
| if (!strcmp(branch, "HEAD")) | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Junio C Hamano wrote on the Git mailing list (how to reply to this email):