worktree add: improve message for ambiguous remote branch name #2197
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -782,12 +782,31 @@ static char *dwim_branch(const char *path, char **new_branch) | |
| *new_branch = branchname; | ||
| if (guess_remote) { | ||
| struct object_id oid; | ||
| char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL); | ||
| 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/ |
||
| } | ||
|
|
||
| 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 int add(int ac, const char **av, const char *prefix, | ||
| struct repository *repo UNUSED) | ||
| { | ||
|
|
@@ -898,17 +917,29 @@ static int add(int ac, const char **av, const char *prefix, | |
| /* 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.
"D. Ben Knoble" wrote on the Git mailing list (how to reply to this email):
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):
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.
Yoichi Nakayama wrote on the Git mailing list (how to reply to this email):