Volume XXII, number 279Tuesday, October 6, 2026Latest message 10 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

patchworktree add: improve message for ambiguous remote branch name

62 messages between Aug 8, 2026 and Aug 27, 2026, from Yoichi NAKAYAMA via GitGitGadget, Junio C Hamano, Harald Nordgren, Yoichi Nakayama, D. Ben Knoble, Ben Knoble.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Yoichi NAKAYAMA via GitGitGadgetAug 8, 2026, 08:21 UTC on lore
From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
Display a descriptive message when DWIM fails.

Add advice on how to work around this by specifying the fully qualified name or by setting checkout.defaultRemote.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
    worktree add: improve message for ambiguous remote branch name
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
 builtin/worktree.c      | 30 ++++++++++++++++++++++++++----
 t/t2400-worktree-add.sh | 21 +++++++++++++++++++--
 2 files changed, 45 insertions(+), 6 deletions(-)
Show changes to 2 files +45 −6

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..46bc305116 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -116,6 +116,16 @@ static const char * const git_worktree_unlock_usage[] = {
 	NULL
 };
 
+static const char message_advice_ambiguous_remote_tracking_branch[] =
+	N_("If you meant to create a worktree from a remote tracking branch on,\n"
+	   "e.g. 'origin', you can do so by fully qualifying the name:\n"
+	   "\n"
+	   "    git worktree add <path> 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.");
+
 struct add_opts {
 	int force;
 	int detach;
@@ -764,7 +774,7 @@ static int dwim_orphan(const struct add_opts *opts, int opt_track, int remote)
 	return 1;
 }
 
-static char *dwim_branch(const char *path, char **new_branch)
+static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
 {
 	int n;
 	int branch_exists;
@@ -781,8 +791,14 @@ static char *dwim_branch(const char *path, char **new_branch)
 
 	*new_branch = branchname;
 	if (guess_remote) {
+		int num_matches = 0;
 		struct object_id oid;
-		char *remote = unique_tracking_name(*new_branch, &oid, NULL);
+		char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
+		if (!opts->quiet && !remote && num_matches > 1) {
+			if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
+				advise(_(message_advice_ambiguous_remote_tracking_branch));
+			warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
+		}
 		return remote;
 	}
 	return NULL;
@@ -890,7 +906,7 @@ 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(path, &new_branch_to_free);
+		char *s = dwim_branch(&opts, path, &new_branch_to_free);
 		if (s)
 			branch = branch_to_free = s;
 		new_branch = new_branch_to_free;
@@ -904,10 +920,16 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			int num_matches = 0;
+			remote = unique_tracking_name(branch, &oid, &num_matches);
 			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(_(message_advice_ambiguous_remote_tracking_branch));
+				}
+				die(_("'%s' matched multiple (%d) remote tracking branches"), branch, num_matches);
 			}
 		}
 
diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
index 87b926728a..4d21c8eba4 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.actual
@@ -669,6 +669,23 @@ test_expect_success 'git worktree add --guess-remote sets up tracking' '
 		test_cmp_rev refs/remotes/repo_a/foo refs/heads/foo
 	)
 '
+test_expect_success 'git worktree add --guess-remote with ambiguous name' '
+	test_when_finished rm -rf repo_a repo_b foo &&
+	setup_remote_repo repo_a repo_b &&
+	(
+		cd repo_b &&
+		git remote add upstream2 ../repo_a &&
+		git fetch upstream2 &&
+		git worktree add --guess-remote ../foo 2>actual &&
+		test_grep "matched multiple (2) remote tracking branches" actual
+	) &&
+	(
+		cd foo &&
+		test_must_fail git config "branch.foo.remote" &&
+		test_must_fail git config "branch.foo.merge" &&
+		test_cmp_rev refs/heads/main refs/heads/foo
+	)
+'
 test_expect_success 'git worktree add --guess-remote sets up tracking (quiet)' '
 	test_when_finished rm -rf repo_a repo_b foo &&
 	setup_remote_repo repo_a repo_b &&

base-commit: 010afd3166ddc64c9863b1506f12cbcdda0d4ea1
-- 
gitgitgadget
Junio C HamanoAug 8, 2026, 17:00 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 33 quoted lines
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> Display a descriptive message when DWIM fails.
>
> Add advice on how to work around this by specifying the fully
> qualified name or by setting checkout.defaultRemote.
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> ---
>     worktree add: improve message for ambiguous remote branch name
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/2197
>
>  builtin/worktree.c      | 30 ++++++++++++++++++++++++++----
>  t/t2400-worktree-add.sh | 21 +++++++++++++++++++--
>  2 files changed, 45 insertions(+), 6 deletions(-)
>
> diff --git a/builtin/worktree.c b/builtin/worktree.c
> index 654d27c3e1..46bc305116 100644
> --- a/builtin/worktree.c
> +++ b/builtin/worktree.c
> @@ -116,6 +116,16 @@ static const char * const git_worktree_unlock_usage[] = {
>  	NULL
>  };
>  
> +static const char message_advice_ambiguous_remote_tracking_branch[] =
> +	N_("If you meant to create a worktree from a remote tracking branch on,\n"
> +	   "e.g. 'origin', you can do so by fully qualifying the name:\n"
> +	   "\n"
> +	   "    git worktree add <path> origin/<name>\n"
> +	   "\n"

This is shown in two places, but what did the user exactly type in these two situations? Can their intent be different, in which case different suggestions might be more appropriate to each of them?

Let's see.
Show 15 quoted lines
> @@ -781,8 +791,14 @@ static char *dwim_branch(const char *path, char **new_branch)
>  
>  	*new_branch = branchname;
>  	if (guess_remote) {
> +		int num_matches = 0;
>  		struct object_id oid;
> -		char *remote = unique_tracking_name(*new_branch, &oid, NULL);
> +		char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
> +		if (!opts->quiet && !remote && num_matches > 1) {
> +			if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> +				advise(_(message_advice_ambiguous_remote_tracking_branch));
> +			warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
> +		}
>  		return remote;
>  	}

The worktree.guessremote configuration is set. dwim_branch() is called when "git worktree add A/B/X" is run with a single argument "A/B/X", which comes here as "path", and that is munged into the branchname "X".

We used to pass NULL as the second parameter to unique_tracking_name(), so we were only interested in the case where we have exactly one matching remote, and if there is 0 or multiple remotes with the named branch, we returned NULL from here.

The patch does not change that, but using the branch name, we try to see if there are multiple matches, in that case, we give the advice message to say "hey, don't be so lazy, as X appears in more than one remote, so tell me which one you mean".

Show 9 quoted lines
> @@ -890,7 +906,7 @@ 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(path, &new_branch_to_free);
> +		char *s = dwim_branch(&opts, path, &new_branch_to_free);
>  		if (s)
>  			branch = branch_to_free = s;
>  		new_branch = new_branch_to_free;
But shouldn't we do a bit better than 
    git worktree add <path> origin/<name>

The above makes the user think that just like 'git', 'worktree' and 'add', 'origin/' is a fixed part, and they would need to substitute <path> and <name>, but that is not really what we want to tell them. The most crucial part to correct is 'origin/', as that is what we could not guess from the given information.

We know that the user gave us "A/B/X" (path) and probably they want to create local "X" from it. Or not. We also should know, in caller's opt_track and used_new_branch_options, that the user gave us "-t -b Y" from the command line.

Show 15 quoted lines
> @@ -904,10 +920,16 @@ static int add(int ac, const char **av, const char *prefix,
>  
>  		commit = lookup_commit_reference_by_name(branch);
>  		if (!commit) {
> -			remote = unique_tracking_name(branch, &oid, NULL);
> +			int num_matches = 0;
> +			remote = unique_tracking_name(branch, &oid, &num_matches);
>  			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(_(message_advice_ambiguous_remote_tracking_branch));
> +				}
> +				die(_("'%s' matched multiple (%d) remote tracking branches"), branch, num_matches);
Style: overly long line, with {braces} around a single statement block.

What does this case handle? Can you make a similar analysis to come up with the list of things we know the user gave us, to give a bit better command line to suggest here?

>  			}
>  		}
Thanks.
Junio C HamanoAug 8, 2026, 21:57 UTC in reply to Junio C Hamano on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

Junio C Hamano <gitster@pobox.com> writes:
Show 30 quoted lines
>> +static const char message_advice_ambiguous_remote_tracking_branch[] =
>> +	N_("If you meant to create a worktree from a remote tracking branch on,\n"
>> +	   "e.g. 'origin', you can do so by fully qualifying the name:\n"
>> +	   "\n"
>> +	   "    git worktree add <path> origin/<name>\n"
>> +	   "\n"
>> ...
>> +		char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
>> +		if (!opts->quiet && !remote && num_matches > 1) {
>> +			if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
>> +				advise(_(message_advice_ambiguous_remote_tracking_branch));
>> +			warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
>> +		}
>>  		return remote;
>>  	}
>
> The worktree.guessremote configuration is set.  dwim_branch() is
> called when "git worktree add A/B/X" is run with a single argument
> "A/B/X", which comes here as "path", and that is munged into the
> branchname "X".
>
> We used to pass NULL as the second parameter to unique_tracking_name(),
> so we were only interested in the case where we have exactly one
> matching remote, and if there is 0 or multiple remotes with the
> named branch, we returned NULL from here.
>
> The patch does not change that, but using the branch name, we try to
> see if there are multiple matches, in that case, we give the advice
> message to say "hey, don't be so lazy, as X appears in more than one
> remote, so tell me which one you mean".

Stepping back a bit, I think what I find lacking in the proposed warning message is not that we lose what the user gave us, such as '-b <branch>' or '-t'. While this loss makes it impossible to simply copy and paste to reproduce what the user may have intended, it is not the end of the world.

What disturbs me more is that the code holds back information only it possesses, which would immediately help the user if we shared it.

The reason we got this error may not be that the user did not know exactly how to spell out the necessary information (such as which branch to use from which remote) on the command line. It may be that the user did not remember some of the necessary details (such as which remotes have the branch they have in mind). Displaying the command line and advising them to use the fully qualified name might not be the best approach in that case. Telling them that they may have meant 'origin', 'upstream', or 'home' (all of which are remotes with the named branch, though we could not guess which one of the three to choose) may be much more helpful.

Harald NordgrenAug 9, 2026, 07:45 UTC in reply to Junio C Hamano on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

This is an interesting idea!
Harald
Junio C HamanoAug 9, 2026, 18:17 UTC in reply to Junio C Hamano on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

Junio C Hamano <gitster@pobox.com> writes:
Show 15 quoted lines
> Junio C Hamano <gitster@pobox.com> writes:
>
>>> +static const char message_advice_ambiguous_remote_tracking_branch[] =
>>> +	N_("If you meant to create a worktree from a remote tracking branch on,\n"
>>> +	   "e.g. 'origin', you can do so by fully qualifying the name:\n"
>>> +	   "\n"
>>> +	   "    git worktree add <path> origin/<name>\n"
>>> +	   "\n"
>>> ...
>>> +		char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
>>> +		if (!opts->quiet && !remote && num_matches > 1) {
>>> +			if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
>>> +				advise(_(message_advice_ambiguous_remote_tracking_branch));
>>> +			warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
>>> +		}

Sorry for piecemeal reviews, but I just noticed that you have a terminating LF at the end of a single-liner warning message. As die/error/warning ffamily of helpers give the terminating newline themselves, you must not. Unless you want to leave a blank line after your message, that is.

Thanks.
Junio C HamanoAug 9, 2026, 18:19 UTC in reply to Harald Nordgren on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

Harald Nordgren <haraldnordgren@gmail.com> writes:
> This is an interesting idea!
>
>
> Harald

When expressing your opinion on what another said, quote a bit from the message you are responding to so that people know what you are referring to. I cannot easily tell which part of what I said you found interesting.

Thanks.
Harald NordgrenAug 10, 2026, 10:12 UTC in reply to Junio C Hamano on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

> When expressing your opinion on what another said, quote a bit from
> the message you are responding to so that people know what you are
> referring to.  I cannot easily tell which part of what I said you
> found interesting.
Sorry, yes this was about:
> Telling them that
> they may have meant 'origin', 'upstream', or 'home' (all of which
> are remotes with the named branch, though we could not guess which
> one of the three to choose) may be much more helpful.
Harald
Yoichi NakayamaAug 10, 2026, 13:00 UTC in reply to Junio C Hamano on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

On Sun, Aug 9, 2026 at 2:00 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 30 quoted lines
> > @@ -781,8 +791,14 @@ static char *dwim_branch(const char *path, char **new_branch)
> >
> >       *new_branch = branchname;
> >       if (guess_remote) {
> > +             int num_matches = 0;
> >               struct object_id oid;
> > -             char *remote = unique_tracking_name(*new_branch, &oid, NULL);
> > +             char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
> > +             if (!opts->quiet && !remote && num_matches > 1) {
> > +                     if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> > +                             advise(_(message_advice_ambiguous_remote_tracking_branch));
> > +                     warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
> > +             }
> >               return remote;
> >       }
>
> The worktree.guessremote configuration is set.  dwim_branch() is
> called when "git worktree add A/B/X" is run with a single argument
> "A/B/X", which comes here as "path", and that is munged into the
> branchname "X".
>
> We used to pass NULL as the second parameter to unique_tracking_name(),
> so we were only interested in the case where we have exactly one
> matching remote, and if there is 0 or multiple remotes with the
> named branch, we returned NULL from here.
>
> The patch does not change that, but using the branch name, we try to
> see if there are multiple matches, in that case, we give the advice
> message to say "hey, don't be so lazy, as X appears in more than one
> remote, so tell me which one you mean".
I thought the problem here was that it was impossible to distinguish whether
the guess was successful, but it was not true. We can distinguish by
the message:
    branch 'name' set up to track 'remote/name'.
I will not make changes to this part.
Thanks,
-- 
Yoichi NAKAYAMA
Yoichi NakayamaAug 10, 2026, 13:04 UTC in reply to Junio C Hamano on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

On Sun, Aug 9, 2026 at 6:57 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 53 quoted lines
>
> Junio C Hamano <gitster@pobox.com> writes:
>
> >> +static const char message_advice_ambiguous_remote_tracking_branch[] =
> >> +    N_("If you meant to create a worktree from a remote tracking branch on,\n"
> >> +       "e.g. 'origin', you can do so by fully qualifying the name:\n"
> >> +       "\n"
> >> +       "    git worktree add <path> origin/<name>\n"
> >> +       "\n"
> >> ...
> >> +            char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
> >> +            if (!opts->quiet && !remote && num_matches > 1) {
> >> +                    if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> >> +                            advise(_(message_advice_ambiguous_remote_tracking_branch));
> >> +                    warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
> >> +            }
> >>              return remote;
> >>      }
> >
> > The worktree.guessremote configuration is set.  dwim_branch() is
> > called when "git worktree add A/B/X" is run with a single argument
> > "A/B/X", which comes here as "path", and that is munged into the
> > branchname "X".
> >
> > We used to pass NULL as the second parameter to unique_tracking_name(),
> > so we were only interested in the case where we have exactly one
> > matching remote, and if there is 0 or multiple remotes with the
> > named branch, we returned NULL from here.
> >
> > The patch does not change that, but using the branch name, we try to
> > see if there are multiple matches, in that case, we give the advice
> > message to say "hey, don't be so lazy, as X appears in more than one
> > remote, so tell me which one you mean".
>
> Stepping back a bit, I think what I find lacking in the proposed
> warning message is not that we lose what the user gave us, such as
> '-b <branch>' or '-t'.  While this loss makes it impossible to
> simply copy and paste to reproduce what the user may have intended,
> it is not the end of the world.
>
> What disturbs me more is that the code holds back information only
> it possesses, which would immediately help the user if we shared it.
>
> The reason we got this error may not be that the user did not know
> exactly how to spell out the necessary information (such as which
> branch to use from which remote) on the command line.  It may be
> that the user did not remember some of the necessary details (such
> as which remotes have the branch they have in mind).  Displaying
> the command line and advising them to use the fully qualified name
> might not be the best approach in that case.  Telling them that
> they may have meant 'origin', 'upstream', or 'home' (all of which
> are remotes with the named branch, though we could not guess which
> one of the three to choose) may be much more helpful.

I realized that instead of placing a burden on the user, we should present a solution.

When a multiple match occurs, the only decision the user needs to make is which remote to select. For everything else, the hint should give a specific command with arguments that achieve the same behavior as when exactly one remote matches.

Rather than presenting a list of candidates, I think it is preferable to explain how to generate that list. This allows users to process the list e.g. by piping it into a command.

I'll submit an updated patch.
Thanks,
-- 
Yoichi NAKAYAMA
D. Ben KnobleAug 10, 2026, 13:07 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

Hi Yoichi,

On Sat, Aug 8, 2026 at 4:21 AM Yoichi NAKAYAMA via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 10 quoted lines
>
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> Display a descriptive message when DWIM fails.
>
> Add advice on how to work around this by specifying the fully
> qualified name or by setting checkout.defaultRemote.
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> ---
[snip]
Show 21 quoted lines
> -static char *dwim_branch(const char *path, char **new_branch)
> +static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
>  {
>         int n;
>         int branch_exists;
> @@ -781,8 +791,14 @@ static char *dwim_branch(const char *path, char **new_branch)
>
>         *new_branch = branchname;
>         if (guess_remote) {
> +               int num_matches = 0;
>                 struct object_id oid;
> -               char *remote = unique_tracking_name(*new_branch, &oid, NULL);
> +               char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
> +               if (!opts->quiet && !remote && num_matches > 1) {
> +                       if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> +                               advise(_(message_advice_ambiguous_remote_tracking_branch));
> +                       warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
> +               }
>                 return remote;
>         }
>         return NULL;
I suppose the extra warning won't hurt anyone's workflow :) so that's good.
[snip]
Show 17 quoted lines
> @@ -904,10 +920,16 @@ static int add(int ac, const char **av, const char *prefix,
>
>                 commit = lookup_commit_reference_by_name(branch);
>                 if (!commit) {
> -                       remote = unique_tracking_name(branch, &oid, NULL);
> +                       int num_matches = 0;
> +                       remote = unique_tracking_name(branch, &oid, &num_matches);
>                         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(_(message_advice_ambiguous_remote_tracking_branch));
> +                               }
> +                               die(_("'%s' matched multiple (%d) remote tracking branches"), branch, num_matches);
>                         }
>                 }

We would now die() here where we didn't before. I'm not suggesting that is wrong (I haven't given it much thought), but I was surprised to see it in the code without mention in the message, which I've left quoted above. In particular, the proposed log message talks about giving new advice, so I wasn't expecting us to abort.

Now, it may be that this case already causes an error later on (I haven't analyzed that), in which case dying early with a better diagnostic is definitely helpful. If that's the case, it would be nice to spell that out for the rest of us :)

If not, I would want to know why we can die() here without bothering anyone's workflow that is expecting us to carry on.

Thanks!
-- 
D. Ben Knoble
Yoichi NakayamaAug 10, 2026, 13:35 UTC in reply to D. Ben Knoble on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

On Mon, Aug 10, 2026 at 10:08 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:
Show 31 quoted lines
> > @@ -904,10 +920,16 @@ static int add(int ac, const char **av, const char *prefix,
> >
> >                 commit = lookup_commit_reference_by_name(branch);
> >                 if (!commit) {
> > -                       remote = unique_tracking_name(branch, &oid, NULL);
> > +                       int num_matches = 0;
> > +                       remote = unique_tracking_name(branch, &oid, &num_matches);
> >                         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(_(message_advice_ambiguous_remote_tracking_branch));
> > +                               }
> > +                               die(_("'%s' matched multiple (%d) remote tracking branches"), branch, num_matches);
> >                         }
> >                 }
>
> We would now die() here where we didn't before. I'm not suggesting
> that is wrong (I haven't given it much thought), but I was surprised
> to see it in the code without mention in the message, which I've left
> quoted above. In particular, the proposed log message talks about
> giving new advice, so I wasn't expecting us to abort.
>
> Now, it may be that this case already causes an error later on (I
> haven't analyzed that), in which case dying early with a better
> diagnostic is definitely helpful. If that's the case, it would be nice
> to spell that out for the rest of us :)
>
> If not, I would want to know why we can die() here without bothering
> anyone's workflow that is expecting us to carry on.

Before the change, it calles lookup_commit_reference_by_name() again in the if condition and die() at:

    if (!opts.orphan && !lookup_commit_reference_by_name(branch)) {
        /* snip */
        die(_("invalid reference: %s"), branch);
    }

The motivation for the fix was that this error message did not accurately reflect the situation.

Thanks,
-- 
Yoichi NAKAYAMA
Junio C HamanoAug 10, 2026, 15:06 UTC in reply to Yoichi Nakayama on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
Show 10 quoted lines
> Before the change, it calles lookup_commit_reference_by_name() again
> in the if condition and die() at:
>
>     if (!opts.orphan && !lookup_commit_reference_by_name(branch)) {
>         /* snip */
>         die(_("invalid reference: %s"), branch);
>     }
>
> The motivation for the fix was that this error message did not
> accurately reflect the situation.

The location of this die() is a tad away from the places that the patch touched. The proposed log message could be made a bit more helpful by mentioning it. What was posted reads:

    Display a descriptive message when DWIM fails.
    Add advice on how to work around this by specifying the fully
    qualified name or by setting checkout.defaultRemote.

but telling the readers what they will see instead of a descriptive message and how that happens would be very helpful to understand why it is a good idea to die early. Perhaps

    When the user runs 'git worktree add x y z' command that does
    not exactly say which remote they want to work with, we try to
    guess which remote by passing y.  If there are multiple remotes
    that have branch named y, we silently gave up, leaving remote
    still NULL.  This later causes A and B not happen, and we end up
    with passing an non-existing branch to
    lookup_commit_reference_by_name(), triggering "invalid
    reference" error and die.

or something like that that describes the issue to a similar degree as above mock-up message.

Thanks.
Yoichi NAKAYAMA via GitGitGadgetAug 10, 2026, 15:07 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v2] worktree add: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
Display a hint and a descriptive error message when DWIM fails.
Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
    worktree add: improve message for ambiguous remote branch name
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v1:
 1:  00b814fe09 ! 1:  1bc57ce497 worktree add: improve message for ambiguous remote branch name
     @@ Metadata
       ## Commit message ##
          worktree add: improve message for ambiguous remote branch name
      
     -    Display a descriptive message when DWIM fails.
     -
     -    Add advice on how to work around this by specifying the fully
     -    qualified name or by setting checkout.defaultRemote.
     +    Display a hint and a descriptive error message when DWIM fails.
      
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
       ## builtin/worktree.c ##
     -@@ builtin/worktree.c: static const char * const git_worktree_unlock_usage[] = {
     - 	NULL
     - };
     +@@
     + 	"\n" \
     + 	"    git worktree add --orphan %s\n")
       
     -+static const char message_advice_ambiguous_remote_tracking_branch[] =
     -+	N_("If you meant to create a worktree from a remote tracking branch on,\n"
     -+	   "e.g. 'origin', you can do so by fully qualifying the name:\n"
     -+	   "\n"
     -+	   "    git worktree add <path> 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.");
     ++#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
     ++	_("Matched multiple remote tracking branches, you can list them by:\n" \
     ++	"\n" \
     ++	"    git branch -r --list \"*/%s\"\n" \
     ++	"\n" \
     ++	"If you meant to create a worktree from a remote tracking branch on,\n" \
     ++	"e.g. 'origin', you can do so by:\n" \
     ++	"\n" \
     ++	"    git worktree add -b %s %s origin/%s\n" \
     ++	"\n" \
     ++	"If you'd like to always prefer some remote, e.g. 'origin',\n" \
     ++	"consider setting checkout.defaultRemote=origin in your config.")
      +
     - struct add_opts {
     - 	int force;
     - 	int detach;
     -@@ builtin/worktree.c: static int dwim_orphan(const struct add_opts *opts, int opt_track, int remote)
     - 	return 1;
     - }
     - 
     --static char *dwim_branch(const char *path, char **new_branch)
     -+static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
     - {
     - 	int n;
     - 	int branch_exists;
     -@@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch)
     - 
     - 	*new_branch = branchname;
     - 	if (guess_remote) {
     -+		int num_matches = 0;
     - 		struct object_id oid;
     --		char *remote = unique_tracking_name(*new_branch, &oid, NULL);
     -+		char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
     -+		if (!opts->quiet && !remote && num_matches > 1) {
     -+			if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     -+				advise(_(message_advice_ambiguous_remote_tracking_branch));
     -+			warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
     -+		}
     - 		return remote;
     - 	}
     - 	return NULL;
     -@@ builtin/worktree.c: 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(path, &new_branch_to_free);
     -+		char *s = dwim_branch(&opts, path, &new_branch_to_free);
     - 		if (s)
     - 			branch = branch_to_free = s;
     - 		new_branch = new_branch_to_free;
     + static const char * const git_worktree_usage[] = {
     + 	BUILTIN_WORKTREE_ADD_USAGE,
     + 	BUILTIN_WORKTREE_LIST_USAGE,
      @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix,
       
       		commit = lookup_commit_reference_by_name(branch);
     @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix,
       				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(_(message_advice_ambiguous_remote_tracking_branch));
     -+				}
     -+				die(_("'%s' matched multiple (%d) remote tracking branches"), branch, num_matches);
     ++				if (!opts.quiet)
     ++					advise_if_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
     ++							  WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT,
     ++							  branch, branch, path, branch);
     ++				die(_("'%s' matched multiple (%d) remote tracking branches"),
     ++				    branch, num_matches);
       			}
       		}
       
     @@ t/t2400-worktree-add.sh: test_expect_success '"add" <path> <branch> dwims' '
       		git -c checkout.defaultRemote=repo_upstream worktree add ../foo foo &&
       		git status -uno --porcelain >status.actual &&
       		test_must_be_empty status.actual
     -@@ t/t2400-worktree-add.sh: test_expect_success 'git worktree add --guess-remote sets up tracking' '
     - 		test_cmp_rev refs/remotes/repo_a/foo refs/heads/foo
     - 	)
     - '
     -+test_expect_success 'git worktree add --guess-remote with ambiguous name' '
     -+	test_when_finished rm -rf repo_a repo_b foo &&
     -+	setup_remote_repo repo_a repo_b &&
     -+	(
     -+		cd repo_b &&
     -+		git remote add upstream2 ../repo_a &&
     -+		git fetch upstream2 &&
     -+		git worktree add --guess-remote ../foo 2>actual &&
     -+		test_grep "matched multiple (2) remote tracking branches" actual
     -+	) &&
     -+	(
     -+		cd foo &&
     -+		test_must_fail git config "branch.foo.remote" &&
     -+		test_must_fail git config "branch.foo.merge" &&
     -+		test_cmp_rev refs/heads/main refs/heads/foo
     -+	)
     -+'
     - test_expect_success 'git worktree add --guess-remote sets up tracking (quiet)' '
     - 	test_when_finished rm -rf repo_a repo_b foo &&
     - 	setup_remote_repo repo_a repo_b &&
 builtin/worktree.c      | 23 ++++++++++++++++++++++-
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 24 insertions(+), 3 deletions(-)
Show changes to 2 files +24 −3

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..b29c3a3755 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -64,6 +64,19 @@
 	"\n" \
 	"    git worktree add --orphan %s\n")
 
+#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
+	_("Matched multiple remote tracking branches, you can list them by:\n" \
+	"\n" \
+	"    git branch -r --list \"*/%s\"\n" \
+	"\n" \
+	"If you meant to create a worktree from a remote tracking branch on,\n" \
+	"e.g. 'origin', you can do so by:\n" \
+	"\n" \
+	"    git worktree add -b %s %s origin/%s\n" \
+	"\n" \
+	"If you'd like to always prefer some remote, e.g. 'origin',\n" \
+	"consider setting checkout.defaultRemote=origin in your config.")
+
 static const char * const git_worktree_usage[] = {
 	BUILTIN_WORKTREE_ADD_USAGE,
 	BUILTIN_WORKTREE_LIST_USAGE,
@@ -904,10 +917,18 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			int num_matches = 0;
+			remote = unique_tracking_name(branch, &oid, &num_matches);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
+			} else if (num_matches > 1) {
+				if (!opts.quiet)
+					advise_if_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
+							  WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT,
+							  branch, branch, path, branch);
+				die(_("'%s' matched multiple (%d) remote tracking branches"),
+				    branch, num_matches);
 			}
 		}
 
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.actual

base-commit: 010afd3166ddc64c9863b1506f12cbcdda0d4ea1
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 10, 2026, 20:55 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v3] worktree add: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git worktree add x y' command that does not exactly say which remote they want to work with, and there is no local branch named y, we try to guess which remote by passing y then create a new branch named y which tracks the remote branch.

If there are multiple remotes that have branch named y, we silently gave up, leaving the variable branch intact. This later causes creating local branch and worktree not happen, and we end up with passing an non-existing branch to lookup_commit_reference_by_name(), triggering "invalid reference" error and die.

To resolve this issue, display a hint and a descriptive error message and die immediately when multiple mathing branches are found.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
    worktree add: improve message for ambiguous remote branch name
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v2:
 1:  1bc57ce497 ! 1:  1b9364da7e worktree add: improve message for ambiguous remote branch name
     @@ Metadata
       ## Commit message ##
          worktree add: improve message for ambiguous remote branch name
      
     -    Display a hint and a descriptive error message when DWIM fails.
     +    When the user runs 'git worktree add x y' command that does not
     +    exactly say which remote they want to work with, and there is no local
     +    branch named y, we try to guess which remote by passing y then create
     +    a new branch named y which tracks the remote branch.
     +
     +    If there are multiple remotes that have branch named y, we silently
     +    gave up, leaving the variable branch intact.  This later causes
     +    creating local branch and worktree not happen, and we end up with
     +    passing an non-existing branch to lookup_commit_reference_by_name(),
     +    triggering "invalid reference" error and die.
     +
     +    To resolve this issue, display a hint and a descriptive error message
     +    and die immediately when multiple mathing branches are found.
      
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
 builtin/worktree.c      | 23 ++++++++++++++++++++++-
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 24 insertions(+), 3 deletions(-)
Show changes to 2 files +24 −3

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..b29c3a3755 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -64,6 +64,19 @@
 	"\n" \
 	"    git worktree add --orphan %s\n")
 
+#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
+	_("Matched multiple remote tracking branches, you can list them by:\n" \
+	"\n" \
+	"    git branch -r --list \"*/%s\"\n" \
+	"\n" \
+	"If you meant to create a worktree from a remote tracking branch on,\n" \
+	"e.g. 'origin', you can do so by:\n" \
+	"\n" \
+	"    git worktree add -b %s %s origin/%s\n" \
+	"\n" \
+	"If you'd like to always prefer some remote, e.g. 'origin',\n" \
+	"consider setting checkout.defaultRemote=origin in your config.")
+
 static const char * const git_worktree_usage[] = {
 	BUILTIN_WORKTREE_ADD_USAGE,
 	BUILTIN_WORKTREE_LIST_USAGE,
@@ -904,10 +917,18 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			int num_matches = 0;
+			remote = unique_tracking_name(branch, &oid, &num_matches);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
+			} else if (num_matches > 1) {
+				if (!opts.quiet)
+					advise_if_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
+							  WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT,
+							  branch, branch, path, branch);
+				die(_("'%s' matched multiple (%d) remote tracking branches"),
+				    branch, num_matches);
 			}
 		}
 
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.actual

base-commit: 010afd3166ddc64c9863b1506f12cbcdda0d4ea1
-- 
gitgitgadget
Yoichi NakayamaAug 10, 2026, 21:36 UTC in reply to D. Ben Knoble on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

On Mon, Aug 10, 2026 at 10:08 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:
Show 23 quoted lines
> > -static char *dwim_branch(const char *path, char **new_branch)
> > +static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
> >  {
> >         int n;
> >         int branch_exists;
> > @@ -781,8 +791,14 @@ static char *dwim_branch(const char *path, char **new_branch)
> >
> >         *new_branch = branchname;
> >         if (guess_remote) {
> > +               int num_matches = 0;
> >                 struct object_id oid;
> > -               char *remote = unique_tracking_name(*new_branch, &oid, NULL);
> > +               char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
> > +               if (!opts->quiet && !remote && num_matches > 1) {
> > +                       if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> > +                               advise(_(message_advice_ambiguous_remote_tracking_branch));
> > +                       warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
> > +               }
> >                 return remote;
> >         }
> >         return NULL;
>
> I suppose the extra warning won't hurt anyone's workflow :) so that's good.

I removed the change (advise and warn) here in the latest patch. But I am still wondering what I should do. I think a warning would be excessive if there is no match, but the user might want to know if there are multiple matches.

Thanks,
-- 
Yoichi NAKAYAMA
Junio C HamanoAug 11, 2026, 00:03 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v3] worktree add: improve message for ambiguous remote branch name

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 6 quoted lines
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> When the user runs 'git worktree add x y' command that does not
> exactly say which remote they want to work with, and there is no local
> branch named y, we try to guess which remote by passing y then create
> a new branch named y which tracks the remote branch.

I used x and y as placeholders. The readers would be helped if you used a more plausible sounding names, e.g., naming directory as something like foo-dir (the point being 'dir' somewhere in its name) and naming a branch as something like bar-topic. If this were 'git worktree add', it is probably more than likely that the destination directory would begin with ../ to have the new worktree next to the primary repository we are running in, no?

Show 5 quoted lines
> If there are multiple remotes that have branch named y, we silently
> gave up, leaving the variable branch intact.  This later causes
> creating local branch and worktree not happen, and we end up with
> passing an non-existing branch to lookup_commit_reference_by_name(),
> triggering "invalid reference" error and die.

"This later causes" part still seems a bit too sketchy to help a totally new reader, even though I've stared at this code long enough so it would be sufficient for me personally. But these logs are not about helping me, but helping other developers, so...

Show 12 quoted lines
> +#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
> +	_("Matched multiple remote tracking branches, you can list them by:\n" \
> +	"\n" \
> +	"    git branch -r --list \"*/%s\"\n" \
> +	"\n" \
> +	"If you meant to create a worktree from a remote tracking branch on,\n" \
> +	"e.g. 'origin', you can do so by:\n" \
> +	"\n" \
> +	"    git worktree add -b %s %s origin/%s\n" \
> +	"\n" \
> +	"If you'd like to always prefer some remote, e.g. 'origin',\n" \
> +	"consider setting checkout.defaultRemote=origin in your config.")

Instead of throwing the problem back to the user with four extra lines of message telling them how to run 'git branch', I would have expected this patch to teach unique_tracking_name() to optionally return the list of remotes with that branch name, and to use that result in this message. However, if the goal is simply to provide something better than 'invalid reference', we do not even need to go that far. Just stating that branch 'y' appears on multiple remotes and asking them to clarify which one they mean might be a sufficient improvement.

Could the original request be aiming to create a new worktree with the HEAD detached at the commit pointed at by the remote-tracking branch, instead of creating a local branch forked from it? I am just wondering if "-b %s" is too specific to one possible interpretation that may contradict to what the user actually wanted to do.

Thanks.
Yoichi NakayamaAug 11, 2026, 06:31 UTC in reply to Junio C Hamano on lore

Re: [PATCH v3] worktree add: improve message for ambiguous remote branch name

On Tue, Aug 11, 2026 at 9:04 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 51 quoted lines
>
> "Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> >
> > When the user runs 'git worktree add x y' command that does not
> > exactly say which remote they want to work with, and there is no local
> > branch named y, we try to guess which remote by passing y then create
> > a new branch named y which tracks the remote branch.
>
> I used x and y as placeholders.  The readers would be helped if you
> used a more plausible sounding names, e.g., naming directory as
> something like foo-dir (the point being 'dir' somewhere in its name)
> and naming a branch as something like bar-topic.  If this were 'git
> worktree add', it is probably more than likely that the destination
> directory would begin with ../ to have the new worktree next to the
> primary repository we are running in, no?
>
> > If there are multiple remotes that have branch named y, we silently
> > gave up, leaving the variable branch intact.  This later causes
> > creating local branch and worktree not happen, and we end up with
> > passing an non-existing branch to lookup_commit_reference_by_name(),
> > triggering "invalid reference" error and die.
>
> "This later causes" part still seems a bit too sketchy to help a
> totally new reader, even though I've stared at this code long enough
> so it would be sufficient for me personally.  But these logs are not
> about helping me, but helping other developers, so...
>
> > +#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
> > +     _("Matched multiple remote tracking branches, you can list them by:\n" \
> > +     "\n" \
> > +     "    git branch -r --list \"*/%s\"\n" \
> > +     "\n" \
> > +     "If you meant to create a worktree from a remote tracking branch on,\n" \
> > +     "e.g. 'origin', you can do so by:\n" \
> > +     "\n" \
> > +     "    git worktree add -b %s %s origin/%s\n" \
> > +     "\n" \
> > +     "If you'd like to always prefer some remote, e.g. 'origin',\n" \
> > +     "consider setting checkout.defaultRemote=origin in your config.")
>
> Instead of throwing the problem back to the user with four extra
> lines of message telling them how to run 'git branch', I would have
> expected this patch to teach unique_tracking_name() to optionally
> return the list of remotes with that branch name, and to use that
> result in this message.  However, if the goal is simply to provide
> something better than 'invalid reference', we do not even need to
> go that far.  Just stating that branch 'y' appears on multiple
> remotes and asking them to clarify which one they mean might be a
> sufficient improvement.

Extending `unique_tracking_name()` would also affect the implementation in `checkout.c`, and since the goal here is to improve the messages (making them as helpful as those in `checkout`), I will hold off on doing that for now.

I will rewrite the log messages a bit.
Show 6 quoted lines
> Could the original request be aiming to create a new worktree with
> the HEAD detached at the commit pointed at by the remote-tracking
> branch, instead of creating a local branch forked from it?  I am
> just wondering if "-b %s" is too specific to one possible
> interpretation that may contradict to what the user actually wanted
> to do.

If the user is aiming to create a new worktree with the HEAD detached, one would specify a fully qualified branch name like origin/bar-topic, starting with a remote name. If a branch name starts with a remote name, multiple matches (condition to show this hint) rarely occur.

Thanks,
-- 
Yoichi NAKAYAMA
Yoichi NAKAYAMA via GitGitGadgetAug 11, 2026, 06:35 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v4] worktree add: improve message for ambiguous remote branch name

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>
---
    worktree add: improve message for ambiguous remote branch name
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v4
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v4
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v3:
 1:  1b9364da7e ! 1:  f7c413b588 worktree add: improve message for ambiguous remote branch name
     @@ Metadata
       ## Commit message ##
          worktree add: improve message for ambiguous remote branch name
      
     -    When the user runs 'git worktree add x y' command that does not
     -    exactly say which remote they want to work with, and there is no local
     -    branch named y, we try to guess which remote by passing y then create
     -    a new branch named y which tracks the remote branch.
     +    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 y, we silently
     -    gave up, leaving the variable branch intact.  This later causes
     -    creating local branch and worktree not happen, and we end up with
     -    passing an non-existing branch to lookup_commit_reference_by_name(),
     -    triggering "invalid reference" error and die.
     +    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 resolve this issue, display a hint and a descriptive error message
     -    and die immediately when multiple mathing branches are found.
     +    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      | 23 ++++++++++++++++++++++-
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 24 insertions(+), 3 deletions(-)
Show changes to 2 files +24 −3

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..b29c3a3755 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -64,6 +64,19 @@
 	"\n" \
 	"    git worktree add --orphan %s\n")
 
+#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
+	_("Matched multiple remote tracking branches, you can list them by:\n" \
+	"\n" \
+	"    git branch -r --list \"*/%s\"\n" \
+	"\n" \
+	"If you meant to create a worktree from a remote tracking branch on,\n" \
+	"e.g. 'origin', you can do so by:\n" \
+	"\n" \
+	"    git worktree add -b %s %s origin/%s\n" \
+	"\n" \
+	"If you'd like to always prefer some remote, e.g. 'origin',\n" \
+	"consider setting checkout.defaultRemote=origin in your config.")
+
 static const char * const git_worktree_usage[] = {
 	BUILTIN_WORKTREE_ADD_USAGE,
 	BUILTIN_WORKTREE_LIST_USAGE,
@@ -904,10 +917,18 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			int num_matches = 0;
+			remote = unique_tracking_name(branch, &oid, &num_matches);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
+			} else if (num_matches > 1) {
+				if (!opts.quiet)
+					advise_if_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
+							  WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT,
+							  branch, branch, path, branch);
+				die(_("'%s' matched multiple (%d) remote tracking branches"),
+				    branch, num_matches);
 			}
 		}
 
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.actual

base-commit: 010afd3166ddc64c9863b1506f12cbcdda0d4ea1
-- 
gitgitgadget
Ben KnobleAug 11, 2026, 16:38 UTC in reply to Yoichi Nakayama on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

Show 36 quoted lines
> 
> Le 10 août 2026 à 17:36, Yoichi Nakayama <yoichi.nakayama@gmail.com> a écrit :
> 
> On Mon, Aug 10, 2026 at 10:08 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:
>>> -static char *dwim_branch(const char *path, char **new_branch)
>>> +static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
>>> {
>>>        int n;
>>>        int branch_exists;
>>> @@ -781,8 +791,14 @@ static char *dwim_branch(const char *path, char **new_branch)
>>> 
>>>        *new_branch = branchname;
>>>        if (guess_remote) {
>>> +               int num_matches = 0;
>>>                struct object_id oid;
>>> -               char *remote = unique_tracking_name(*new_branch, &oid, NULL);
>>> +               char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
>>> +               if (!opts->quiet && !remote && num_matches > 1) {
>>> +                       if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
>>> +                               advise(_(message_advice_ambiguous_remote_tracking_branch));
>>> +                       warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
>>> +               }
>>>                return remote;
>>>        }
>>>        return NULL;
>> 
>> I suppose the extra warning won't hurt anyone's workflow :) so that's good.
> 
> I removed the change (advise and warn) here in the latest patch. But I am still
> wondering what I should do. I think a warning would be excessive if
> there is no match,
> but the user might want to know if there are multiple matches.
> 
> Thanks,
> --
> Yoichi NAKAYAMA
Sorry if I was unclear: I don’t know what hits this particular code path offhand, and I don’t think adding the warning is wrong! I meant « as opposed to dying, a warning won’t break anyone but will let them know of potentially unintended consequences », maybe.
I’m not particularly invested in how we signal ambiguity, but if we don’t have a documented policy for resolving it in a particular way then I agree we should signal it. 
Yoichi NakayamaAug 12, 2026, 13:14 UTC in reply to Ben Knoble on lore

Re: [PATCH] worktree add: improve message for ambiguous remote branch name

On Wed, Aug 12, 2026 at 1:38 AM Ben Knoble <ben.knoble@gmail.com> wrote:
Show 42 quoted lines
>
>
> >
> > Le 10 août 2026 à 17:36, Yoichi Nakayama <yoichi.nakayama@gmail.com> a écrit :
> >
> > On Mon, Aug 10, 2026 at 10:08 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:
> >>> -static char *dwim_branch(const char *path, char **new_branch)
> >>> +static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
> >>> {
> >>>        int n;
> >>>        int branch_exists;
> >>> @@ -781,8 +791,14 @@ static char *dwim_branch(const char *path, char **new_branch)
> >>>
> >>>        *new_branch = branchname;
> >>>        if (guess_remote) {
> >>> +               int num_matches = 0;
> >>>                struct object_id oid;
> >>> -               char *remote = unique_tracking_name(*new_branch, &oid, NULL);
> >>> +               char *remote = unique_tracking_name(*new_branch, &oid, &num_matches);
> >>> +               if (!opts->quiet && !remote && num_matches > 1) {
> >>> +                       if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> >>> +                               advise(_(message_advice_ambiguous_remote_tracking_branch));
> >>> +                       warning(_("'%s' matched multiple (%d) remote tracking branches\n"), branchname, num_matches);
> >>> +               }
> >>>                return remote;
> >>>        }
> >>>        return NULL;
> >>
> >> I suppose the extra warning won't hurt anyone's workflow :) so that's good.
> >
> > I removed the change (advise and warn) here in the latest patch. But I am still
> > wondering what I should do. I think a warning would be excessive if
> > there is no match,
> > but the user might want to know if there are multiple matches.
> >
> > Thanks,
> > --
> > Yoichi NAKAYAMA
>
> Sorry if I was unclear: I don’t know what hits this particular code path offhand, and I don’t think adding the warning is wrong! I meant « as opposed to dying, a warning won’t break anyone but will let them know of potentially unintended consequences », maybe.
>
> I’m not particularly invested in how we signal ambiguity, but if we don’t have a documented policy for resolving it in a particular way then I agree we should signal it.

Thank you for the additional information. I think the intention behind your comment was clear. The reason I was wondering was simply that I hadn't yet found a clear direction for what I should do.

The `git worktree add --guess-remote ../foo` command (without <commit-ish>) is
designed to successfully create the worktree even if the guess fails.
If we are to
issue a warning and advice, we need to indicate what to do next, given that the
worktree and the branch has already been created. It would be something like
    git -C ../foo reset –hard origin/foo
    git -C ../foo branch –set-upstream-to=origin/foo
but they are too complicated. So I now think it is a valid choice to
interpret the
behavior as normal and refrain from issuing a warning or advice.
Thanks,
-- 
Yoichi NAKAYAMA
Junio C HamanoAug 12, 2026, 19:22 UTC in reply to Yoichi Nakayama on lore

Re: [PATCH v3] worktree add: improve message for ambiguous remote branch name

Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
Show 14 quoted lines
>> Instead of throwing the problem back to the user with four extra
>> lines of message telling them how to run 'git branch', I would have
>> expected this patch to teach unique_tracking_name() to optionally
>> return the list of remotes with that branch name, and to use that
>> result in this message.  However, if the goal is simply to provide
>> something better than 'invalid reference', we do not even need to
>> go that far.  Just stating that branch 'y' appears on multiple
>> remotes and asking them to clarify which one they mean might be a
>> sufficient improvement.
>
> Extending `unique_tracking_name()` would also affect the implementation
> in `checkout.c`, and since the goal here is to improve the messages
> (making them as helpful as those in `checkout`), I will hold off on doing
> that for now.
Sorry but I do not quite understand this logic.

Giving unique_tracking_name() the optional ability to report which remotes have a branch with the given name does not have to affect other callers of the function at all; that is the definition of a new feature being "optional."

Furthermore, the goal of improving these messages falls short if we withhold the list of remotes the user could have meant, which we are already computing internally to decide that the original request is ambiguous.

Show 10 quoted lines
>> Could the original request be aiming to create a new worktree with
>> the HEAD detached at the commit pointed at by the remote-tracking
>> branch, instead of creating a local branch forked from it?  I am
>> just wondering if "-b %s" is too specific to one possible
>> interpretation that may contradict to what the user actually wanted
>> to do.
>
> If the user is aiming to create a new worktree with the HEAD detached,
> one would specify a fully qualified branch name like origin/bar-topic,
> starting with a remote name.

I am not sure about this part, either. After all, we are trying to help a user who made a mistake composing their command-line arguments. If they specify a fully qualified branch name like 'origin/bar-topic' (regardless of whether they want to create a detached 'HEAD' or not), they would not hit the 'saying bar-topic alone is ambiguous' error path, would they?

Here is a patch to show what I mean. To 'improve the message for an ambiguous remote branch name' for the 'checkout' command, we can add this optional feature to the unique_tracking_name() function and we can do so without affecting the 'worktree add' command.

Regardless of whether we modify unique_tracking_name(), I think refactoring be_explicit() is worth doing, as the original code in parse_remote_branch() was badly misindented.

 builtin/checkout.c | 74 ++++++++++++++++++++++++++++++++----------------------
 builtin/worktree.c |  4 +--
 checkout.c         | 14 +++++++++--
 checkout.h         |  5 +++-
 4 files changed, 62 insertions(+), 35 deletions(-)
Show changes to diff +62 −35
diff --git c/builtin/checkout.c w/builtin/checkout.c
index 55e3a89a85..8d61973a11 100644
--- c/builtin/checkout.c
+++ w/builtin/checkout.c
@@ -1343,13 +1343,50 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
+static void be_explicit(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, 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);
+}
+
 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 +1395,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(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;
 }
 
diff --git c/builtin/worktree.c w/builtin/worktree.c
index 654d27c3e1..22c8e5e131 100644
--- c/builtin/worktree.c
+++ w/builtin/worktree.c
@@ -782,7 +782,7 @@ 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);
+		char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
 		return remote;
 	}
 	return NULL;
@@ -904,7 +904,7 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			remote = unique_tracking_name(branch, &oid, NULL, NULL);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
diff --git c/checkout.c w/checkout.c
index 1588b116ee..2806b783ec 100644
--- c/checkout.c
+++ w/checkout.c
@@ -8,6 +8,7 @@
 #include "checkout.h"
 #include "config.h"
 #include "strbuf.h"
+#include "string-list.h"
 
 struct tracking_name_data {
 	/* const */ char *src_ref;
@@ -17,6 +18,7 @@ struct tracking_name_data {
 	const char *default_remote;
 	char *default_dst_ref;
 	struct object_id *default_dst_oid;
+	struct string_list **remote_names;
 };
 
 #define TRACKING_NAME_DATA_INIT { 0 }
@@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 		oidcpy(dst, cb->dst_oid);
 		cb->default_dst_oid = dst;
 	}
+	if (cb->remote_names)
+		string_list_append(*cb->remote_names, remote->name);
 	if (cb->dst_ref) {
 		free(query.dst);
 		return 0;
@@ -48,14 +52,20 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 }
 
 char *unique_tracking_name(const char *name, struct object_id *oid,
-			   int *dwim_remotes_matched)
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names)
 {
 	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
 	const char *default_remote = NULL;
-	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
+
+	if (!repo_config_get_string_tmp(the_repository,
+					"checkout.defaultremote",
+					&default_remote))
 		cb_data.default_remote = default_remote;
 	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
 	cb_data.dst_oid = oid;
+	if (dwim_remote_names)
+		cb_data.remote_names = &dwim_remote_names;
 	for_each_remote(check_tracking_name, &cb_data);
 	if (dwim_remotes_matched)
 		*dwim_remotes_matched = cb_data.num_matches;
diff --git c/checkout.h w/checkout.h
index 55920e7aeb..0b185a0fc9 100644
--- c/checkout.h
+++ w/checkout.h
@@ -3,6 +3,8 @@
 
 #include "hash.h"
 
+struct string_list;
+
 /*
  * Check if the branch name uniquely matches a branch name on a remote
  * tracking branch.  Return the name of the remote if such a branch
@@ -10,6 +12,7 @@
  */
 char *unique_tracking_name(const char *name,
 			   struct object_id *oid,
-			   int *dwim_remotes_matched);
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names);
 
 #endif /* CHECKOUT_H */
Yoichi NakayamaAug 15, 2026, 04:36 UTC in reply to Junio C Hamano on lore

Re: [PATCH v3] worktree add: improve message for ambiguous remote branch name

On Thu, Aug 13, 2026 at 4:22 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 29 quoted lines
>
> Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
>
> >> Instead of throwing the problem back to the user with four extra
> >> lines of message telling them how to run 'git branch', I would have
> >> expected this patch to teach unique_tracking_name() to optionally
> >> return the list of remotes with that branch name, and to use that
> >> result in this message.  However, if the goal is simply to provide
> >> something better than 'invalid reference', we do not even need to
> >> go that far.  Just stating that branch 'y' appears on multiple
> >> remotes and asking them to clarify which one they mean might be a
> >> sufficient improvement.
> >
> > Extending `unique_tracking_name()` would also affect the implementation
> > in `checkout.c`, and since the goal here is to improve the messages
> > (making them as helpful as those in `checkout`), I will hold off on doing
> > that for now.
>
> Sorry but I do not quite understand this logic.
>
> Giving unique_tracking_name() the optional ability to report which
> remotes have a branch with the given name does not have to affect
> other callers of the function at all; that is the definition of a
> new feature being "optional."
>
> Furthermore, the goal of improving these messages falls short if we
> withhold the list of remotes the user could have meant, which we are
> already computing internally to decide that the original request is
> ambiguous.

That is certainly true. I think the modification to `unique_tracking_name()` that you shared is good.

Show 17 quoted lines
> >> Could the original request be aiming to create a new worktree with
> >> the HEAD detached at the commit pointed at by the remote-tracking
> >> branch, instead of creating a local branch forked from it?  I am
> >> just wondering if "-b %s" is too specific to one possible
> >> interpretation that may contradict to what the user actually wanted
> >> to do.
> >
> > If the user is aiming to create a new worktree with the HEAD detached,
> > one would specify a fully qualified branch name like origin/bar-topic,
> > starting with a remote name.
>
> I am not sure about this part, either.  After all, we are trying to
> help a user who made a mistake composing their command-line
> arguments.  If they specify a fully qualified branch name like
> 'origin/bar-topic' (regardless of whether they want to create a
> detached 'HEAD' or not), they would not hit the 'saying bar-topic
> alone is ambiguous' error path, would they?
If the user specifies a fully qualified branch name like
    git worktree add ../foo-dir origin/bar-topic
the 2nd argument 'origin/bar-topic' will be resolved by
    commit = lookup_commit_reference_by_name(branch);
before calling unique_tracking_name(), so the ambiguous warning
won't occur.

In a worst-case scenario, a user might make a typo in the 2nd argument (e.g. origin/bar-topik) that fails to match a local ref (e.g. refs/remotes/origin/bar-topic) but accidentally matches multiple remote branch names (e.g. branches related to refs/remotes/remote1/origin/bar-topik and refs/remotes/remote2/origin/bar-topik), then it could cause an issue. However, I think this is an edge case that doesn't need to be considered.

Thanks,
-- 
Yoichi NAKAYAMA
Yoichi NAKAYAMA via GitGitGadgetAug 19, 2026, 12:50 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v5 0/2] worktree add: improve message for ambiguous remote branch name

'git worktree add ../foo-dir bar-topic' fails to dwim when there are multiple remote branches with name `bar-topic'. But it doesn't display meaningful message as 'git checkout bar-topic' does under the same situation.

We improve this by adding advice and modify the error message for worktree add.

By Junio's suggestion, we include matched remote names in the advice. It is applied to checkout, too.

The changes to 'checkout' are almost identical to what Junio proposed; I have made minor adjustments to use the specified branch name. I'm not sure how to handle the "Author" field in this case, so I've set it to myself for now, but I'll correct it if that's not appropriate.

Yoichi NAKAYAMA (2):
  checkout: improve message for ambiguous remote branch name
  worktree add: improve message for ambiguous remote branch name
 builtin/checkout.c      | 75 ++++++++++++++++++++++++-----------------
 builtin/worktree.c      | 36 ++++++++++++++++++--
 checkout.c              | 14 ++++++--
 checkout.h              |  5 ++-
 t/t2400-worktree-add.sh |  4 +--
 5 files changed, 96 insertions(+), 38 deletions(-)
base-commit: dea0ea3582e6980ddbc1173cc8e3e9f9db91cde0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v4:
 -:  ---------- > 1:  b838fdabb7 checkout: improve message for ambiguous remote branch name
 1:  f7c413b588 ! 2:  777862235e worktree add: improve message for ambiguous remote branch name
     @@ Commit message
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
       ## builtin/worktree.c ##
     -@@
     - 	"\n" \
     - 	"    git worktree add --orphan %s\n")
     +@@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch)
     + 	return NULL;
     + }
       
     -+#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
     -+	_("Matched multiple remote tracking branches, you can list them by:\n" \
     -+	"\n" \
     -+	"    git branch -r --list \"*/%s\"\n" \
     -+	"\n" \
     -+	"If you meant to create a worktree from a remote tracking branch on,\n" \
     -+	"e.g. 'origin', you can do so by:\n" \
     -+	"\n" \
     -+	"    git worktree add -b %s %s origin/%s\n" \
     -+	"\n" \
     -+	"If you'd like to always prefer some remote, e.g. 'origin',\n" \
     -+	"consider setting checkout.defaultRemote=origin in your config.")
     ++static void advise_ambiguous_remote(const char *path, const char *branch,
     ++				    const struct string_list *matched_remote_names)
     ++{
     ++	struct string_list_item *item;
      +
     - static const char * const git_worktree_usage[] = {
     - 	BUILTIN_WORKTREE_ADD_USAGE,
     - 	BUILTIN_WORKTREE_LIST_USAGE,
     ++	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 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)
     + {
      @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix,
     + 	} else if (ac == 2) {
     + 		struct object_id oid;
     + 		struct commit *commit;
     +-		char *remote;
       
       		commit = lookup_commit_reference_by_name(branch);
       		if (!commit) {
     --			remote = unique_tracking_name(branch, &oid, NULL);
     +-			remote = unique_tracking_name(branch, &oid, NULL, NULL);
     ++			char *remote;
      +			int num_matches = 0;
     -+			remote = unique_tracking_name(branch, &oid, &num_matches);
     ++			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)
     -+					advise_if_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
     -+							  WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT,
     -+							  branch, branch, path, branch);
     ++				if (!opts.quiet &&
     ++				    advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     ++					advise_ambiguous_remote(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"))
      
       ## t/t2400-worktree-add.sh ##
      @@ t/t2400-worktree-add.sh: test_expect_success '"add" <path> <branch> dwims' '
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 19, 2026, 12:50 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v5 1/2] checkout: improve message for ambiguous remote branch name

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(-)
Show changes to 4 files +63 −35

builtin/checkout.c, builtin/worktree.c, checkout.c, checkout.h

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,
+			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);
+}
+
 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;
 }
 
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..22c8e5e131 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -782,7 +782,7 @@ 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);
+		char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
 		return remote;
 	}
 	return NULL;
@@ -904,7 +904,7 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			remote = unique_tracking_name(branch, &oid, NULL, NULL);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
diff --git a/checkout.c b/checkout.c
index 1588b116ee..2806b783ec 100644
--- a/checkout.c
+++ b/checkout.c
@@ -8,6 +8,7 @@
 #include "checkout.h"
 #include "config.h"
 #include "strbuf.h"
+#include "string-list.h"
 
 struct tracking_name_data {
 	/* const */ char *src_ref;
@@ -17,6 +18,7 @@ struct tracking_name_data {
 	const char *default_remote;
 	char *default_dst_ref;
 	struct object_id *default_dst_oid;
+	struct string_list **remote_names;
 };
 
 #define TRACKING_NAME_DATA_INIT { 0 }
@@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 		oidcpy(dst, cb->dst_oid);
 		cb->default_dst_oid = dst;
 	}
+	if (cb->remote_names)
+		string_list_append(*cb->remote_names, remote->name);
 	if (cb->dst_ref) {
 		free(query.dst);
 		return 0;
@@ -48,14 +52,20 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 }
 
 char *unique_tracking_name(const char *name, struct object_id *oid,
-			   int *dwim_remotes_matched)
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names)
 {
 	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
 	const char *default_remote = NULL;
-	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
+
+	if (!repo_config_get_string_tmp(the_repository,
+					"checkout.defaultremote",
+					&default_remote))
 		cb_data.default_remote = default_remote;
 	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
 	cb_data.dst_oid = oid;
+	if (dwim_remote_names)
+		cb_data.remote_names = &dwim_remote_names;
 	for_each_remote(check_tracking_name, &cb_data);
 	if (dwim_remotes_matched)
 		*dwim_remotes_matched = cb_data.num_matches;
diff --git a/checkout.h b/checkout.h
index 55920e7aeb..0b185a0fc9 100644
--- a/checkout.h
+++ b/checkout.h
@@ -3,6 +3,8 @@
 
 #include "hash.h"
 
+struct string_list;
+
 /*
  * Check if the branch name uniquely matches a branch name on a remote
  * tracking branch.  Return the name of the remote if such a branch
@@ -10,6 +12,7 @@
  */
 char *unique_tracking_name(const char *name,
 			   struct object_id *oid,
-			   int *dwim_remotes_matched);
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names);
 
 #endif /* CHECKOUT_H */
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 19, 2026, 12:50 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v5 2/2] worktree add: improve message for ambiguous remote branch name

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      | 34 ++++++++++++++++++++++++++++++++--
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 34 insertions(+), 4 deletions(-)
Show changes to 2 files +34 −4

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 22c8e5e131..30d7a8c340 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_ambiguous_remote(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:"));
+	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)
 {
@@ -900,15 +919,26 @@ static int add(int ac, const char **av, const char *prefix,
 	} else if (ac == 2) {
 		struct object_id oid;
 		struct commit *commit;
-		char *remote;
 
 		commit = lookup_commit_reference_by_name(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_ambiguous_remote(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"))
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.actual
-- 
gitgitgadget
D. Ben KnobleAug 19, 2026, 22:54 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v5 1/2] checkout: improve message for ambiguous remote branch name

On Wed, Aug 19, 2026 at 8:51 AM Yoichi NAKAYAMA via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 37 quoted lines
>
> 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.

Show 34 quoted lines
> +                       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.
Show 57 quoted lines
>  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]
Junio C HamanoAug 20, 2026, 02:18 UTC in reply to D. Ben Knoble on lore

Re: [PATCH v5 1/2] checkout: improve message for ambiguous remote branch name

"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.

Yoichi NakayamaAug 20, 2026, 15:41 UTC in reply to Junio C Hamano on lore

Re: [PATCH v5 1/2] checkout: improve message for ambiguous remote branch name

On Thu, Aug 20, 2026 at 11:18 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 12 quoted lines
>
> "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
Yoichi NAKAYAMA via GitGitGadgetAug 20, 2026, 21:03 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v6 0/3] worktree add: improve message for ambiguous remote branch name

'git worktree add ../foo-dir bar-topic' fails to dwim when there are multiple remote branches with name `bar-topic'. But it doesn't display meaningful message as 'git checkout bar-topic' does under the same situation.

We improve this by adding advice and modify the error message for worktree add.

By Junio's suggestion, we include matched remote names in the advice. It is applied to checkout, too.

The changes to 'checkout' are almost identical to what Junio proposed; I have made minor adjustments to use the specified branch name. I'm not sure how to handle the "Author" field in this case, so I've set it to myself for now, but I'll correct it if that's not appropriate.

Yoichi NAKAYAMA (3):
  checkout: extract function to display advice for ambiguous remotes
  checkout: improve message for ambiguous remote branch name
  worktree add: improve message for ambiguous remote branch name
 builtin/checkout.c      | 76 +++++++++++++++++++++++++----------------
 builtin/worktree.c      | 37 ++++++++++++++++++--
 checkout.c              | 14 ++++++--
 checkout.h              |  5 ++-
 t/t2400-worktree-add.sh |  4 +--
 5 files changed, 98 insertions(+), 38 deletions(-)
base-commit: dea0ea3582e6980ddbc1173cc8e3e9f9db91cde0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v6
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v6
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v5:
 -:  ---------- > 1:  e3f7d88520 checkout: extract function to display advice for ambiguous remotes
 1:  b838fdabb7 ! 2:  97e99ae31e checkout: improve message for ambiguous remote branch name
     @@ Commit message
          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
     +    To achieve that, we add an optional feature to the
          `unique_tracking_name()` function that allows the matched remote name
          to be exposed to the caller.
      
     @@ builtin/checkout.c: enum checkout_command {
       	CHECKOUT_RESTORE = 3,
       };
       
     -+static void be_explicit(const char *branch,
     -+			enum checkout_command which_command,
     -+			const struct string_list *matched_remote_names)
     -+{
     -+	const char *cmdname;
     +-static void advice_disambiguating_remotes(enum checkout_command which_command)
     ++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;
     -+	}
     -+
     + 
     + 	switch (which_command) {
     + 	case CHECKOUT_CHECKOUT:
     +@@ builtin/checkout.c: static void advice_disambiguating_remotes(enum checkout_command which_command)
     + 		break;
     + 	}
     + 
     +-	advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
      +	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"
     + 		 "you can do so by fully qualifying the name with the --track option:\n"
     + 		 "\n"
     +-		 "    git %s --track origin/<name>\n"
      +		 "    git %s --track <remote>/%s\n"
     -+		 "\n"
     + 		 "\n"
     +-		 "If you'd like to always have checkouts of an ambiguous <name> prefer\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."),
     + 		 "one remote, e.g. the 'origin' remote, consider setting\n"
     + 		 "checkout.defaultRemote=origin in your config."),
     +-	       cmdname);
      +	       cmdname, branch);
     -+}
     -+
     + }
     + 
       static char *parse_remote_branch(const char *arg,
     - 				 struct object_id *rev,
     - 				 int could_be_checkout_paths,
     +@@ builtin/checkout.c: static char *parse_remote_branch(const char *arg,
       				 enum checkout_command which_command)
       {
       	int num_matches = 0;
     @@ builtin/checkout.c: enum checkout_command {
       	if (remote && could_be_checkout_paths) {
       		die(_("'%s' could be both a local file and a tracking branch.\n"
      @@ builtin/checkout.c: 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);
     --	    }
     + 		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     +-			advice_disambiguating_remotes(which_command);
      -
     --	    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);
     ++			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);
 2:  777862235e ! 3:  dcb84a69a6 worktree add: improve message for ambiguous remote branch name
     @@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch
       	return NULL;
       }
       
     -+static void advise_ambiguous_remote(const char *path, const char *branch,
     -+				    const struct string_list *matched_remote_names)
     ++static void advise_disambiguating_remotes(const char *path, const char *branch,
     ++					  const struct string_list *matched_remote_names)
      +{
      +	struct string_list_item *item;
      +
     @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix,
      +			} else if (num_matches > 1) {
      +				if (!opts.quiet &&
      +				    advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     -+					advise_ambiguous_remote(path, branch, &matched_remote_names);
     ++					advise_disambiguating_remotes(path, branch,
     ++								      &matched_remote_names);
      +				die(_("'%s' matched multiple (%d) remote tracking branches"),
      +				    branch, num_matches);
       			}
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 20, 2026, 21:03 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v6 1/3] checkout: extract function to display advice for ambiguous remotes

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 62 ++++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 29 deletions(-)
Show changes to builtin/checkout.c +33 −29
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 55e3a89a85..650eda735f 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,6 +1343,34 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
+static void advice_disambiguating_remotes(enum checkout_command which_command)
+{
+	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);
+}
+
 static char *parse_remote_branch(const char *arg,
 				 struct object_id *rev,
 				 int could_be_checkout_paths,
@@ -1358,35 +1386,11 @@ 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))
+			advice_disambiguating_remotes(which_command);
+
+		die(_("'%s' matched multiple (%d) remote tracking branches"),
+		    arg, num_matches);
 	}
 
 	return remote;
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 20, 2026, 21:03 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v6 2/3] checkout: improve message for ambiguous remote branch name

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 achieve 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 | 28 ++++++++++++++++++++--------
 builtin/worktree.c |  4 ++--
 checkout.c         | 14 ++++++++++++--
 checkout.h         |  5 ++++-
 4 files changed, 38 insertions(+), 13 deletions(-)
Show changes to 4 files +38 −13

builtin/checkout.c, builtin/worktree.c, checkout.c, checkout.h

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 650eda735f..35227f7cbd 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,9 +1343,12 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
-static void advice_disambiguating_remotes(enum checkout_command which_command)
+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:
@@ -1360,15 +1363,19 @@ static void advice_disambiguating_remotes(enum checkout_command which_command)
 		break;
 	}
 
-	advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
+	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 origin/<name>\n"
+		 "    git %s --track <remote>/%s\n"
 		 "\n"
-		 "If you'd like to always have checkouts of an ambiguous <name> prefer\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);
+	       cmdname, branch);
 }
 
 static char *parse_remote_branch(const char *arg,
@@ -1377,7 +1384,10 @@ static char *parse_remote_branch(const char *arg,
 				 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"
@@ -1387,12 +1397,14 @@ static char *parse_remote_branch(const char *arg,
 
 	if (!remote && num_matches > 1) {
 		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
-			advice_disambiguating_remotes(which_command);
-
+			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;
 }
 
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..22c8e5e131 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -782,7 +782,7 @@ 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);
+		char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
 		return remote;
 	}
 	return NULL;
@@ -904,7 +904,7 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			remote = unique_tracking_name(branch, &oid, NULL, NULL);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
diff --git a/checkout.c b/checkout.c
index 1588b116ee..2806b783ec 100644
--- a/checkout.c
+++ b/checkout.c
@@ -8,6 +8,7 @@
 #include "checkout.h"
 #include "config.h"
 #include "strbuf.h"
+#include "string-list.h"
 
 struct tracking_name_data {
 	/* const */ char *src_ref;
@@ -17,6 +18,7 @@ struct tracking_name_data {
 	const char *default_remote;
 	char *default_dst_ref;
 	struct object_id *default_dst_oid;
+	struct string_list **remote_names;
 };
 
 #define TRACKING_NAME_DATA_INIT { 0 }
@@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 		oidcpy(dst, cb->dst_oid);
 		cb->default_dst_oid = dst;
 	}
+	if (cb->remote_names)
+		string_list_append(*cb->remote_names, remote->name);
 	if (cb->dst_ref) {
 		free(query.dst);
 		return 0;
@@ -48,14 +52,20 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 }
 
 char *unique_tracking_name(const char *name, struct object_id *oid,
-			   int *dwim_remotes_matched)
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names)
 {
 	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
 	const char *default_remote = NULL;
-	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
+
+	if (!repo_config_get_string_tmp(the_repository,
+					"checkout.defaultremote",
+					&default_remote))
 		cb_data.default_remote = default_remote;
 	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
 	cb_data.dst_oid = oid;
+	if (dwim_remote_names)
+		cb_data.remote_names = &dwim_remote_names;
 	for_each_remote(check_tracking_name, &cb_data);
 	if (dwim_remotes_matched)
 		*dwim_remotes_matched = cb_data.num_matches;
diff --git a/checkout.h b/checkout.h
index 55920e7aeb..0b185a0fc9 100644
--- a/checkout.h
+++ b/checkout.h
@@ -3,6 +3,8 @@
 
 #include "hash.h"
 
+struct string_list;
+
 /*
  * Check if the branch name uniquely matches a branch name on a remote
  * tracking branch.  Return the name of the remote if such a branch
@@ -10,6 +12,7 @@
  */
 char *unique_tracking_name(const char *name,
 			   struct object_id *oid,
-			   int *dwim_remotes_matched);
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names);
 
 #endif /* CHECKOUT_H */
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 20, 2026, 21:03 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v6 3/3] worktree add: improve message for ambiguous remote branch name

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(-)
Show changes to 2 files +35 −4

builtin/worktree.c, t/t2400-worktree-add.sh

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:"));
+	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)
 {
@@ -900,15 +919,27 @@ static int add(int ac, const char **av, const char *prefix,
 	} else if (ac == 2) {
 		struct object_id oid;
 		struct commit *commit;
-		char *remote;
 
 		commit = lookup_commit_reference_by_name(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);
 		}
 
 		if (!strcmp(branch, "HEAD"))
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.actual
-- 
gitgitgadget
Junio C HamanoAug 21, 2026, 03:54 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v6 3/3] worktree add: improve message for ambiguous remote branch name

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 39 quoted lines
> 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].

Show 21 quoted lines
>  		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?
Show 19 quoted lines
> 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.actual
Yoichi NakayamaAug 21, 2026, 23:15 UTC in reply to Junio C Hamano on lore

Re: [PATCH v6 3/3] worktree add: improve message for ambiguous remote branch name

On Fri, Aug 21, 2026 at 12:54 PM Junio C Hamano <gitster@pobox.com> wrote:
Show 22 quoted lines
>
> "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);
Show 58 quoted lines
> >               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 NAKAYAMA

Junio C HamanoAug 21, 2026, 23:49 UTC in reply to Yoichi Nakayama on lore

Re: [PATCH v6 3/3] worktree add: improve message for ambiguous remote branch name

Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
Show 7 quoted lines
> 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.
Yoichi NakayamaAug 22, 2026, 00:50 UTC in reply to Junio C Hamano on lore

Re: [PATCH v6 3/3] worktree add: improve message for ambiguous remote branch name

On Sat, Aug 22, 2026 at 8:49 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 16 quoted lines
>
> 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 NAKAYAMA
Yoichi NAKAYAMA via GitGitGadgetAug 22, 2026, 03:22 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v7 0/3] worktree add: improve message for ambiguous remote branch name

'git worktree add ../foo-dir bar-topic' fails to dwim when there are multiple remote branches with name `bar-topic'. But it doesn't display meaningful message as 'git checkout bar-topic' does under the same situation.

We improve this by adding advice and modify the error message for worktree add.

By Junio's suggestion, we include matched remote names in the advice. It is applied to checkout, too.

Changes from the previous patch:
 * fix grammatical errors in hints
 * narrow the scope of local variable oid
Yoichi NAKAYAMA (3):
  checkout: extract function to display advice for ambiguous remotes
  checkout: improve message for ambiguous remote branch name
  worktree add: improve message for ambiguous remote branch name
 builtin/checkout.c      | 76 +++++++++++++++++++++++++----------------
 builtin/worktree.c      | 39 ++++++++++++++++++---
 checkout.c              | 14 ++++++--
 checkout.h              |  5 ++-
 t/t2400-worktree-add.sh |  4 +--
 5 files changed, 99 insertions(+), 39 deletions(-)
base-commit: dea0ea3582e6980ddbc1173cc8e3e9f9db91cde0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v7
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v7
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v6:
 1:  e3f7d88520 = 1:  e3f7d88520 checkout: extract function to display advice for ambiguous remotes
 2:  97e99ae31e ! 2:  89c0f4d303 checkout: improve message for ambiguous remote branch name
     @@ Metadata
       ## Commit message ##
          checkout: improve message for ambiguous remote branch name
      
     -    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.
     +    When the user runs 'git checkout bar-topic' without specifying a
     +    remote, and there is no local branch named bar-topic, we try to guess
     +    which remote branch bar-topic refers to, then create a new branch
     +    named bar-topic that 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.
     +    a single remote.
      
     -    To make the advice more feasible, we will provide matched remote names
     -    for the specified branch name.
     +    To make it easier to resolve the ambiguity, provide the names of the
     +    matching remotes for the specified branch name.
      
     -    To achieve that, we add an optional feature to the
     -    `unique_tracking_name()` function that allows the matched remote name
     -    to be exposed to the caller.
     +    To achieve that, add an optional feature to the
     +    `unique_tracking_name()` function that allows the matching remote
     +    names to be exposed to the caller.
      
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
     @@ builtin/checkout.c: static void advice_disambiguating_remotes(enum checkout_comm
       	}
       
      -	advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
     -+	advise(_("Branches with the same name appears in multiple remotes:"));
     ++	advise(_("Branch name '%s' appears in multiple remotes:"), branch);
      +	for_each_string_list_item(item, matched_remote_names) {
      +		advise(_("  %s"), item->string);
      +	}
 3:  dcb84a69a6 ! 3:  095a5796d4 worktree add: improve message for ambiguous remote branch name
     @@ Metadata
       ## Commit message ##
          worktree add: improve message for ambiguous remote branch name
      
     -    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.
     +    When the user runs 'git worktree add ../foo-dir bar-topic' without
     +    specifying a remote, and there is no local branch named bar-topic, we
     +    try to guess which remote branch bar-topic refers to, then create a
     +    new branch named bar-topic that 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.
     +    If multiple remotes have a branch named bar-topic, we silently gave
     +    up, leaving the variable 'branch' intact.  We then entered the
     +    conditional clause 'if (!opts.orphan &&
     +    !lookup_commit_reference_by_name(branch))' and triggered an "invalid
     +    reference" error.  This error message did not provide enough
     +    information to resolve the ambiguity.
      
     -    To improve the situation, we display a hint and a descriptive error
     -    message and die immediately when multiple matching branches are found.
     +    When multiple matching branches are found, display a hint and a
     +    descriptive error message and die immediately.
      
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
     @@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch
      +{
      +	struct string_list_item *item;
      +
     -+	advise(_("Branches with the same name appears in multiple remotes:"));
     ++	advise(_("Branch name '%s' appears in multiple remotes:"), branch);
      +	for_each_string_list_item(item, matched_remote_names) {
      +		advise(_("  %s"), item->string);
      +	}
     @@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch
       	       struct repository *repo UNUSED)
       {
      @@ builtin/worktree.c: 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 object_id oid;
     +-		struct object_id oid;
       		struct commit *commit;
      -		char *remote;
       
       		commit = lookup_commit_reference_by_name(branch);
       		if (!commit) {
      -			remote = unique_tracking_name(branch, &oid, NULL, NULL);
     ++			struct object_id oid;
      +			char *remote;
      +			int num_matches = 0;
      +			struct string_list matched_remote_names = STRING_LIST_INIT_DUP;
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 22, 2026, 03:22 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v7 1/3] checkout: extract function to display advice for ambiguous remotes

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 62 ++++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 29 deletions(-)
Show changes to builtin/checkout.c +33 −29
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 55e3a89a85..650eda735f 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,6 +1343,34 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
+static void advice_disambiguating_remotes(enum checkout_command which_command)
+{
+	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);
+}
+
 static char *parse_remote_branch(const char *arg,
 				 struct object_id *rev,
 				 int could_be_checkout_paths,
@@ -1358,35 +1386,11 @@ 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))
+			advice_disambiguating_remotes(which_command);
+
+		die(_("'%s' matched multiple (%d) remote tracking branches"),
+		    arg, num_matches);
 	}
 
 	return remote;
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 22, 2026, 03:22 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v7 2/3] checkout: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git checkout bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we cannot determine a single remote.

To make it easier to resolve the ambiguity, provide the names of the matching remotes for the specified branch name.

To achieve that, add an optional feature to the `unique_tracking_name()` function that allows the matching remote names to be exposed to the caller.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 28 ++++++++++++++++++++--------
 builtin/worktree.c |  4 ++--
 checkout.c         | 14 ++++++++++++--
 checkout.h         |  5 ++++-
 4 files changed, 38 insertions(+), 13 deletions(-)
Show changes to 4 files +38 −13

builtin/checkout.c, builtin/worktree.c, checkout.c, checkout.h

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 650eda735f..07373615d8 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,9 +1343,12 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
-static void advice_disambiguating_remotes(enum checkout_command which_command)
+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:
@@ -1360,15 +1363,19 @@ static void advice_disambiguating_remotes(enum checkout_command which_command)
 		break;
 	}
 
-	advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
+	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 origin/<name>\n"
+		 "    git %s --track <remote>/%s\n"
 		 "\n"
-		 "If you'd like to always have checkouts of an ambiguous <name> prefer\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);
+	       cmdname, branch);
 }
 
 static char *parse_remote_branch(const char *arg,
@@ -1377,7 +1384,10 @@ static char *parse_remote_branch(const char *arg,
 				 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"
@@ -1387,12 +1397,14 @@ static char *parse_remote_branch(const char *arg,
 
 	if (!remote && num_matches > 1) {
 		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
-			advice_disambiguating_remotes(which_command);
-
+			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;
 }
 
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..22c8e5e131 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -782,7 +782,7 @@ 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);
+		char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
 		return remote;
 	}
 	return NULL;
@@ -904,7 +904,7 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			remote = unique_tracking_name(branch, &oid, NULL, NULL);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
diff --git a/checkout.c b/checkout.c
index 1588b116ee..2806b783ec 100644
--- a/checkout.c
+++ b/checkout.c
@@ -8,6 +8,7 @@
 #include "checkout.h"
 #include "config.h"
 #include "strbuf.h"
+#include "string-list.h"
 
 struct tracking_name_data {
 	/* const */ char *src_ref;
@@ -17,6 +18,7 @@ struct tracking_name_data {
 	const char *default_remote;
 	char *default_dst_ref;
 	struct object_id *default_dst_oid;
+	struct string_list **remote_names;
 };
 
 #define TRACKING_NAME_DATA_INIT { 0 }
@@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 		oidcpy(dst, cb->dst_oid);
 		cb->default_dst_oid = dst;
 	}
+	if (cb->remote_names)
+		string_list_append(*cb->remote_names, remote->name);
 	if (cb->dst_ref) {
 		free(query.dst);
 		return 0;
@@ -48,14 +52,20 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 }
 
 char *unique_tracking_name(const char *name, struct object_id *oid,
-			   int *dwim_remotes_matched)
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names)
 {
 	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
 	const char *default_remote = NULL;
-	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
+
+	if (!repo_config_get_string_tmp(the_repository,
+					"checkout.defaultremote",
+					&default_remote))
 		cb_data.default_remote = default_remote;
 	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
 	cb_data.dst_oid = oid;
+	if (dwim_remote_names)
+		cb_data.remote_names = &dwim_remote_names;
 	for_each_remote(check_tracking_name, &cb_data);
 	if (dwim_remotes_matched)
 		*dwim_remotes_matched = cb_data.num_matches;
diff --git a/checkout.h b/checkout.h
index 55920e7aeb..0b185a0fc9 100644
--- a/checkout.h
+++ b/checkout.h
@@ -3,6 +3,8 @@
 
 #include "hash.h"
 
+struct string_list;
+
 /*
  * Check if the branch name uniquely matches a branch name on a remote
  * tracking branch.  Return the name of the remote if such a branch
@@ -10,6 +12,7 @@
  */
 char *unique_tracking_name(const char *name,
 			   struct object_id *oid,
-			   int *dwim_remotes_matched);
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names);
 
 #endif /* CHECKOUT_H */
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 22, 2026, 03:22 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v7 3/3] worktree add: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git worktree add ../foo-dir bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we silently gave up, leaving the variable 'branch' intact. We then entered the conditional clause 'if (!opts.orphan && !lookup_commit_reference_by_name(branch))' and triggered an "invalid reference" error. This error message did not provide enough information to resolve the ambiguity.

When multiple matching branches are found, display a hint and a descriptive error message and die immediately.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/worktree.c      | 37 ++++++++++++++++++++++++++++++++++---
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 36 insertions(+), 5 deletions(-)
Show changes to 2 files +36 −5

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 22c8e5e131..320b18873d 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(_("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 object_id oid;
 		struct commit *commit;
-		char *remote;
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL, NULL);
+			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"))
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.actual
-- 
gitgitgadget
Junio C HamanoAug 22, 2026, 17:22 UTC in reply to Yoichi Nakayama on lore

Re: [PATCH v6 3/3] worktree add: improve message for ambiguous remote branch name

Yoichi Nakayama <yoichi.nakayama@gmail.com> writes:
Show 15 quoted lines
> 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/
Junio C HamanoAug 22, 2026, 18:08 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v7 0/3] worktree add: improve message for ambiguous remote branch name

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
>  * fix grammatical errors in hints
>  * narrow the scope of local variable oid

Both changes look sensible. I very much like the new advise() message that is much more concise.

>      -+	advise(_("Branches with the same name appears in multiple remotes:"));
>      ++	advise(_("Branch name '%s' appears in multiple remotes:"), branch);
>      -+	advise(_("Branches with the same name appears in multiple remotes:"));
>      ++	advise(_("Branch name '%s' appears in multiple remotes:"), branch);
Will queue.
Yoichi NakayamaAug 24, 2026, 22:25 UTC in reply to Junio C Hamano on lore

Re: [PATCH v6 3/3] worktree add: improve message for ambiguous remote branch name

On Sun, Aug 23, 2026 at 2:22 AM Junio C Hamano <gitster@pobox.com> wrote:
Show 82 quoted lines
>
> 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
Yoichi NAKAYAMA via GitGitGadgetAug 25, 2026, 21:04 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v8 0/4] worktree add: improve message for ambiguous remote branch name

'git worktree add ../foo-dir bar-topic' fails to dwim when there are multiple remote branches with name `bar-topic'. But it doesn't display meaningful message as 'git checkout bar-topic' does under the same situation.

We improve this by adding advice and modify the error message for worktree add.

By Junio's suggestion, we include matched remote names in the advice. It is applied to checkout, too.

We also fix the behavior of --guess-remote when there are multiple matches.
Changes from the previous patch:
 * add another commit to fix the behavior of --guess-remote
Yoichi NAKAYAMA (4):
  checkout: extract function to display advice for ambiguous remotes
  checkout: improve message for ambiguous remote branch name
  worktree add: improve message for ambiguous remote branch name
  worktree add: treat multiple matches with --guess-remote as an error
 Documentation/config/worktree.adoc |  5 +-
 Documentation/git-worktree.adoc    |  4 +-
 builtin/checkout.c                 | 76 ++++++++++++++++++------------
 builtin/worktree.c                 | 57 +++++++++++++++++++---
 checkout.c                         | 14 +++++-
 checkout.h                         |  5 +-
 t/t2400-worktree-add.sh            | 17 ++++++-
 7 files changed, 134 insertions(+), 44 deletions(-)
base-commit: dea0ea3582e6980ddbc1173cc8e3e9f9db91cde0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v8
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v8
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v7:
 1:  e3f7d88520 = 1:  e3f7d88520 checkout: extract function to display advice for ambiguous remotes
 2:  89c0f4d303 = 2:  89c0f4d303 checkout: improve message for ambiguous remote branch name
 3:  095a5796d4 = 3:  095a5796d4 worktree add: improve message for ambiguous remote branch name
 -:  ---------- > 4:  927856e0a0 worktree add: treat multiple matches with --guess-remote as an error
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 25, 2026, 21:04 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v8 1/4] checkout: extract function to display advice for ambiguous remotes

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 62 ++++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 29 deletions(-)
Show changes to builtin/checkout.c +33 −29
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 55e3a89a85..650eda735f 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,6 +1343,34 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
+static void advice_disambiguating_remotes(enum checkout_command which_command)
+{
+	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);
+}
+
 static char *parse_remote_branch(const char *arg,
 				 struct object_id *rev,
 				 int could_be_checkout_paths,
@@ -1358,35 +1386,11 @@ 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))
+			advice_disambiguating_remotes(which_command);
+
+		die(_("'%s' matched multiple (%d) remote tracking branches"),
+		    arg, num_matches);
 	}
 
 	return remote;
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 25, 2026, 21:04 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v8 2/4] checkout: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git checkout bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we cannot determine a single remote.

To make it easier to resolve the ambiguity, provide the names of the matching remotes for the specified branch name.

To achieve that, add an optional feature to the `unique_tracking_name()` function that allows the matching remote names to be exposed to the caller.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 28 ++++++++++++++++++++--------
 builtin/worktree.c |  4 ++--
 checkout.c         | 14 ++++++++++++--
 checkout.h         |  5 ++++-
 4 files changed, 38 insertions(+), 13 deletions(-)
Show changes to 4 files +38 −13

builtin/checkout.c, builtin/worktree.c, checkout.c, checkout.h

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 650eda735f..07373615d8 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,9 +1343,12 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
-static void advice_disambiguating_remotes(enum checkout_command which_command)
+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:
@@ -1360,15 +1363,19 @@ static void advice_disambiguating_remotes(enum checkout_command which_command)
 		break;
 	}
 
-	advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
+	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 origin/<name>\n"
+		 "    git %s --track <remote>/%s\n"
 		 "\n"
-		 "If you'd like to always have checkouts of an ambiguous <name> prefer\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);
+	       cmdname, branch);
 }
 
 static char *parse_remote_branch(const char *arg,
@@ -1377,7 +1384,10 @@ static char *parse_remote_branch(const char *arg,
 				 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"
@@ -1387,12 +1397,14 @@ static char *parse_remote_branch(const char *arg,
 
 	if (!remote && num_matches > 1) {
 		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
-			advice_disambiguating_remotes(which_command);
-
+			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;
 }
 
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..22c8e5e131 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -782,7 +782,7 @@ 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);
+		char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
 		return remote;
 	}
 	return NULL;
@@ -904,7 +904,7 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			remote = unique_tracking_name(branch, &oid, NULL, NULL);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
diff --git a/checkout.c b/checkout.c
index 1588b116ee..2806b783ec 100644
--- a/checkout.c
+++ b/checkout.c
@@ -8,6 +8,7 @@
 #include "checkout.h"
 #include "config.h"
 #include "strbuf.h"
+#include "string-list.h"
 
 struct tracking_name_data {
 	/* const */ char *src_ref;
@@ -17,6 +18,7 @@ struct tracking_name_data {
 	const char *default_remote;
 	char *default_dst_ref;
 	struct object_id *default_dst_oid;
+	struct string_list **remote_names;
 };
 
 #define TRACKING_NAME_DATA_INIT { 0 }
@@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 		oidcpy(dst, cb->dst_oid);
 		cb->default_dst_oid = dst;
 	}
+	if (cb->remote_names)
+		string_list_append(*cb->remote_names, remote->name);
 	if (cb->dst_ref) {
 		free(query.dst);
 		return 0;
@@ -48,14 +52,20 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 }
 
 char *unique_tracking_name(const char *name, struct object_id *oid,
-			   int *dwim_remotes_matched)
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names)
 {
 	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
 	const char *default_remote = NULL;
-	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
+
+	if (!repo_config_get_string_tmp(the_repository,
+					"checkout.defaultremote",
+					&default_remote))
 		cb_data.default_remote = default_remote;
 	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
 	cb_data.dst_oid = oid;
+	if (dwim_remote_names)
+		cb_data.remote_names = &dwim_remote_names;
 	for_each_remote(check_tracking_name, &cb_data);
 	if (dwim_remotes_matched)
 		*dwim_remotes_matched = cb_data.num_matches;
diff --git a/checkout.h b/checkout.h
index 55920e7aeb..0b185a0fc9 100644
--- a/checkout.h
+++ b/checkout.h
@@ -3,6 +3,8 @@
 
 #include "hash.h"
 
+struct string_list;
+
 /*
  * Check if the branch name uniquely matches a branch name on a remote
  * tracking branch.  Return the name of the remote if such a branch
@@ -10,6 +12,7 @@
  */
 char *unique_tracking_name(const char *name,
 			   struct object_id *oid,
-			   int *dwim_remotes_matched);
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names);
 
 #endif /* CHECKOUT_H */
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 25, 2026, 21:04 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v8 3/4] worktree add: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git worktree add ../foo-dir bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we silently gave up, leaving the variable 'branch' intact. We then entered the conditional clause 'if (!opts.orphan && !lookup_commit_reference_by_name(branch))' and triggered an "invalid reference" error. This error message did not provide enough information to resolve the ambiguity.

When multiple matching branches are found, display a hint and a descriptive error message and die immediately.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/worktree.c      | 37 ++++++++++++++++++++++++++++++++++---
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 36 insertions(+), 5 deletions(-)
Show changes to 2 files +36 −5

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 22c8e5e131..320b18873d 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(_("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 object_id oid;
 		struct commit *commit;
-		char *remote;
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL, NULL);
+			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"))
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.actual
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 25, 2026, 21:04 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v8 4/4] worktree add: treat multiple matches with --guess-remote as an error

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When 'git worktree add <path>' is invoked without <commit-ish> and with the --guess-remote option (or when worktree.guessRemote is set to true), it tries to find a remote-tracking branch matching the basename of <path>.

Currently, the behavior when multiple matches are found is the same as when no match is found: it falls back to creating a branch from HEAD. This has been the behavior since 71d6682d8c (worktree: add --guess-remote option to add subcommand, 2017-11-29), when the option was first introduced.

However, if the specified <path> matches any remote-tracking branch, we infer that the user intended to use one of the remote-tracking branches as the start-point rather than HEAD. So we abort the creation of the branch and worktree when there are multiple matches, and instruct the user to choose the start-point.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 Documentation/config/worktree.adoc |  5 +--
 Documentation/git-worktree.adoc    |  4 ++-
 builtin/worktree.c                 | 58 ++++++++++++++++++------------
 t/t2400-worktree-add.sh            | 13 +++++++
 4 files changed, 55 insertions(+), 25 deletions(-)
Show changes to 4 files +55 −25

Documentation/config/worktree.adoc, Documentation/git-worktree.adoc, builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/Documentation/config/worktree.adoc b/Documentation/config/worktree.adoc
index a248076ea5..0930183b91 100644
--- a/Documentation/config/worktree.adoc
+++ b/Documentation/config/worktree.adoc
@@ -5,8 +5,9 @@
 	set to true, `worktree add` tries to find a remote-tracking
 	branch whose name uniquely matches the new branch name.  If
 	such a branch exists, it is checked out and set as "upstream"
-	for the new branch.  If no such match can be found, it falls
-	back to creating a new branch from the current `HEAD`.
+	for the new branch.  If multiple matches are found, the command
+	fails.  If no such match can be found, it falls back to
+	creating a new branch from the current `HEAD`.
 
 `worktree.useRelativePaths`::
 	Link worktrees using relative paths (when "`true`") or absolute
diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index fbf8426cd9..32787eacc3 100644
--- a/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc
@@ -219,7 +219,9 @@ To remove a locked worktree, specify `--force` twice.
 	of creating a new branch from `HEAD`, if there exists a tracking
 	branch in exactly one remote matching the basename of _<path>_,
 	base the new branch on the remote-tracking branch, and mark
-	the remote-tracking branch as "upstream" from the new branch.
+	the remote-tracking branch as "upstream" from the new branch. If
+	there are multiple matches, the command fails. If there is no
+	match, the command falls back to creating a new branch from `HEAD`.
 +
 This can also be set up as the default behaviour by using the
 `worktree.guessRemote` config option.
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 320b18873d..07163bf9b7 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -764,7 +764,26 @@ static int dwim_orphan(const struct add_opts *opts, int opt_track, int remote)
 	return 1;
 }
 
-static char *dwim_branch(const char *path, char **new_branch)
+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,31 +801,26 @@ 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);
+		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;
 }
 
-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)
 {
@@ -909,7 +923,7 @@ 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(path, &new_branch_to_free);
+		char *s = dwim_branch(&opts, path, &new_branch_to_free);
 		if (s)
 			branch = branch_to_free = s;
 		new_branch = new_branch_to_free;
diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
index 5c105cf252..a37137042d 100755
--- a/t/t2400-worktree-add.sh
+++ b/t/t2400-worktree-add.sh
@@ -669,6 +669,19 @@ test_expect_success 'git worktree add --guess-remote sets up tracking' '
 		test_cmp_rev refs/remotes/repo_a/foo refs/heads/foo
 	)
 '
+
+test_expect_success 'git worktree add --guess-remote fails if there are multiple matches' '
+	test_when_finished rm -rf repo_a repo_b foo &&
+	setup_remote_repo repo_a repo_b &&
+	(
+		cd repo_b &&
+		git remote add repo_a2 ../repo_a &&
+		git fetch repo_a2 &&
+		test_must_fail git worktree add --guess-remote ../foo 2>actual &&
+		test_grep "matched multiple (2) remote tracking branches" actual
+	)
+'
+
 test_expect_success 'git worktree add --guess-remote sets up tracking (quiet)' '
 	test_when_finished rm -rf repo_a repo_b foo &&
 	setup_remote_repo repo_a repo_b &&
-- 
gitgitgadget
Junio C HamanoAug 25, 2026, 21:31 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v8 4/4] worktree add: treat multiple matches with --guess-remote as an error

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 18 quoted lines
> +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);
> +}

Wasn't this function added in this series somewhere earlier in the topic? If we add it high enough when we did so, we wouldn't have to move it higher like this patch does.

Show 28 quoted lines
> +static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
>  {
>  	int n;
>  	int branch_exists;
> @@ -782,31 +801,26 @@ 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);
> +		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;
>  }
Looking good.
Thanks.
Yoichi NAKAYAMA via GitGitGadgetAug 26, 2026, 10:45 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v9 0/4] worktree add: improve message for ambiguous remote branch name

'git worktree add ../foo-dir bar-topic' fails to dwim when there are multiple remote branches with name `bar-topic'. But it doesn't display meaningful message as 'git checkout bar-topic' does under the same situation.

We improve this by adding advice and modify the error message for worktree add.

By Junio's suggestion, we include matched remote names in the advice. It is applied to checkout, too.

We also fix the behavior of --guess-remote when there are multiple matches.
Changes from the previous patch:
 * move advise_disambiguating_remotes() definition upper in the 3rd commit
Yoichi NAKAYAMA (4):
  checkout: extract function to display advice for ambiguous remotes
  checkout: improve message for ambiguous remote branch name
  worktree add: improve message for ambiguous remote branch name
  worktree add: treat multiple matches with --guess-remote as an error
 Documentation/config/worktree.adoc |  5 +-
 Documentation/git-worktree.adoc    |  4 +-
 builtin/checkout.c                 | 76 ++++++++++++++++++------------
 builtin/worktree.c                 | 57 +++++++++++++++++++---
 checkout.c                         | 14 +++++-
 checkout.h                         |  5 +-
 t/t2400-worktree-add.sh            | 17 ++++++-
 7 files changed, 134 insertions(+), 44 deletions(-)
base-commit: dea0ea3582e6980ddbc1173cc8e3e9f9db91cde0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v9
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v9
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v8:
 1:  e3f7d88520 = 1:  e3f7d88520 checkout: extract function to display advice for ambiguous remotes
 2:  89c0f4d303 = 2:  89c0f4d303 checkout: improve message for ambiguous remote branch name
 3:  095a5796d4 ! 3:  1010ac3295 worktree add: improve message for ambiguous remote branch name
     @@ Commit message
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
       ## builtin/worktree.c ##
     -@@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch)
     - 	return NULL;
     +@@ builtin/worktree.c: 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,
     @@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch
      +	       branch, path, branch);
      +}
      +
     - static int add(int ac, const char **av, const char *prefix,
     - 	       struct repository *repo UNUSED)
     + static char *dwim_branch(const char *path, char **new_branch)
       {
     + 	int n;
      @@ builtin/worktree.c: 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);
 4:  927856e0a0 ! 4:  edb88b658a worktree add: treat multiple matches with --guess-remote as an error
     @@ Documentation/git-worktree.adoc: To remove a locked worktree, specify `--force`
       `worktree.guessRemote` config option.
      
       ## builtin/worktree.c ##
     -@@ builtin/worktree.c: static int dwim_orphan(const struct add_opts *opts, int opt_track, int remote)
     - 	return 1;
     +@@ builtin/worktree.c: static void advise_disambiguating_remotes(const char *path, const char *branch,
     + 	       branch, path, branch);
       }
       
      -static char *dwim_branch(const char *path, char **new_branch)
     -+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;
     @@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch
       		return remote;
       	}
       	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(_("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)
     - {
      @@ builtin/worktree.c: static int add(int ac, const char **av, const char *prefix,
       		opts.orphan = dwim_orphan(&opts, !!opt_track, 0);
       	} else if (ac < 2) {
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 26, 2026, 10:45 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v9 1/4] checkout: extract function to display advice for ambiguous remotes

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 62 ++++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 29 deletions(-)
Show changes to builtin/checkout.c +33 −29
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 55e3a89a85..650eda735f 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,6 +1343,34 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
+static void advice_disambiguating_remotes(enum checkout_command which_command)
+{
+	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);
+}
+
 static char *parse_remote_branch(const char *arg,
 				 struct object_id *rev,
 				 int could_be_checkout_paths,
@@ -1358,35 +1386,11 @@ 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))
+			advice_disambiguating_remotes(which_command);
+
+		die(_("'%s' matched multiple (%d) remote tracking branches"),
+		    arg, num_matches);
 	}
 
 	return remote;
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 26, 2026, 10:45 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v9 2/4] checkout: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git checkout bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we cannot determine a single remote.

To make it easier to resolve the ambiguity, provide the names of the matching remotes for the specified branch name.

To achieve that, add an optional feature to the `unique_tracking_name()` function that allows the matching remote names to be exposed to the caller.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 28 ++++++++++++++++++++--------
 builtin/worktree.c |  4 ++--
 checkout.c         | 14 ++++++++++++--
 checkout.h         |  5 ++++-
 4 files changed, 38 insertions(+), 13 deletions(-)
Show changes to 4 files +38 −13

builtin/checkout.c, builtin/worktree.c, checkout.c, checkout.h

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 650eda735f..07373615d8 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,9 +1343,12 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
-static void advice_disambiguating_remotes(enum checkout_command which_command)
+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:
@@ -1360,15 +1363,19 @@ static void advice_disambiguating_remotes(enum checkout_command which_command)
 		break;
 	}
 
-	advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
+	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 origin/<name>\n"
+		 "    git %s --track <remote>/%s\n"
 		 "\n"
-		 "If you'd like to always have checkouts of an ambiguous <name> prefer\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);
+	       cmdname, branch);
 }
 
 static char *parse_remote_branch(const char *arg,
@@ -1377,7 +1384,10 @@ static char *parse_remote_branch(const char *arg,
 				 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"
@@ -1387,12 +1397,14 @@ static char *parse_remote_branch(const char *arg,
 
 	if (!remote && num_matches > 1) {
 		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
-			advice_disambiguating_remotes(which_command);
-
+			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;
 }
 
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..22c8e5e131 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -782,7 +782,7 @@ 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);
+		char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
 		return remote;
 	}
 	return NULL;
@@ -904,7 +904,7 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			remote = unique_tracking_name(branch, &oid, NULL, NULL);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
diff --git a/checkout.c b/checkout.c
index 1588b116ee..2806b783ec 100644
--- a/checkout.c
+++ b/checkout.c
@@ -8,6 +8,7 @@
 #include "checkout.h"
 #include "config.h"
 #include "strbuf.h"
+#include "string-list.h"
 
 struct tracking_name_data {
 	/* const */ char *src_ref;
@@ -17,6 +18,7 @@ struct tracking_name_data {
 	const char *default_remote;
 	char *default_dst_ref;
 	struct object_id *default_dst_oid;
+	struct string_list **remote_names;
 };
 
 #define TRACKING_NAME_DATA_INIT { 0 }
@@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 		oidcpy(dst, cb->dst_oid);
 		cb->default_dst_oid = dst;
 	}
+	if (cb->remote_names)
+		string_list_append(*cb->remote_names, remote->name);
 	if (cb->dst_ref) {
 		free(query.dst);
 		return 0;
@@ -48,14 +52,20 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 }
 
 char *unique_tracking_name(const char *name, struct object_id *oid,
-			   int *dwim_remotes_matched)
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names)
 {
 	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
 	const char *default_remote = NULL;
-	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
+
+	if (!repo_config_get_string_tmp(the_repository,
+					"checkout.defaultremote",
+					&default_remote))
 		cb_data.default_remote = default_remote;
 	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
 	cb_data.dst_oid = oid;
+	if (dwim_remote_names)
+		cb_data.remote_names = &dwim_remote_names;
 	for_each_remote(check_tracking_name, &cb_data);
 	if (dwim_remotes_matched)
 		*dwim_remotes_matched = cb_data.num_matches;
diff --git a/checkout.h b/checkout.h
index 55920e7aeb..0b185a0fc9 100644
--- a/checkout.h
+++ b/checkout.h
@@ -3,6 +3,8 @@
 
 #include "hash.h"
 
+struct string_list;
+
 /*
  * Check if the branch name uniquely matches a branch name on a remote
  * tracking branch.  Return the name of the remote if such a branch
@@ -10,6 +12,7 @@
  */
 char *unique_tracking_name(const char *name,
 			   struct object_id *oid,
-			   int *dwim_remotes_matched);
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names);
 
 #endif /* CHECKOUT_H */
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 26, 2026, 10:45 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v9 3/4] worktree add: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git worktree add ../foo-dir bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we silently gave up, leaving the variable 'branch' intact. We then entered the conditional clause 'if (!opts.orphan && !lookup_commit_reference_by_name(branch))' and triggered an "invalid reference" error. This error message did not provide enough information to resolve the ambiguity.

When multiple matching branches are found, display a hint and a descriptive error message and die immediately.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/worktree.c      | 37 ++++++++++++++++++++++++++++++++++---
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 36 insertions(+), 5 deletions(-)
Show changes to 2 files +36 −5

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 22c8e5e131..c745deddde 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -764,6 +764,25 @@ 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 char *path, char **new_branch)
 {
 	int n;
@@ -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 object_id oid;
 		struct commit *commit;
-		char *remote;
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL, NULL);
+			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"))
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.actual
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 26, 2026, 10:45 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v9 4/4] worktree add: treat multiple matches with --guess-remote as an error

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When 'git worktree add <path>' is invoked without <commit-ish> and with the --guess-remote option (or when worktree.guessRemote is set to true), it tries to find a remote-tracking branch matching the basename of <path>.

Currently, the behavior when multiple matches are found is the same as when no match is found: it falls back to creating a branch from HEAD. This has been the behavior since 71d6682d8c (worktree: add --guess-remote option to add subcommand, 2017-11-29), when the option was first introduced.

However, if the specified <path> matches any remote-tracking branch, we infer that the user intended to use one of the remote-tracking branches as the start-point rather than HEAD. So we abort the creation of the branch and worktree when there are multiple matches, and instruct the user to choose the start-point.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 Documentation/config/worktree.adoc |  5 +++--
 Documentation/git-worktree.adoc    |  4 +++-
 builtin/worktree.c                 | 20 +++++++++++++++++---
 t/t2400-worktree-add.sh            | 13 +++++++++++++
 4 files changed, 36 insertions(+), 6 deletions(-)
Show changes to 4 files +36 −6

Documentation/config/worktree.adoc, Documentation/git-worktree.adoc, builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/Documentation/config/worktree.adoc b/Documentation/config/worktree.adoc
index a248076ea5..0930183b91 100644
--- a/Documentation/config/worktree.adoc
+++ b/Documentation/config/worktree.adoc
@@ -5,8 +5,9 @@
 	set to true, `worktree add` tries to find a remote-tracking
 	branch whose name uniquely matches the new branch name.  If
 	such a branch exists, it is checked out and set as "upstream"
-	for the new branch.  If no such match can be found, it falls
-	back to creating a new branch from the current `HEAD`.
+	for the new branch.  If multiple matches are found, the command
+	fails.  If no such match can be found, it falls back to
+	creating a new branch from the current `HEAD`.
 
 `worktree.useRelativePaths`::
 	Link worktrees using relative paths (when "`true`") or absolute
diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index fbf8426cd9..32787eacc3 100644
--- a/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc
@@ -219,7 +219,9 @@ To remove a locked worktree, specify `--force` twice.
 	of creating a new branch from `HEAD`, if there exists a tracking
 	branch in exactly one remote matching the basename of _<path>_,
 	base the new branch on the remote-tracking branch, and mark
-	the remote-tracking branch as "upstream" from the new branch.
+	the remote-tracking branch as "upstream" from the new branch. If
+	there are multiple matches, the command fails. If there is no
+	match, the command falls back to creating a new branch from `HEAD`.
 +
 This can also be set up as the default behaviour by using the
 `worktree.guessRemote` config option.
diff --git a/builtin/worktree.c b/builtin/worktree.c
index c745deddde..07163bf9b7 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -783,7 +783,7 @@ static void advise_disambiguating_remotes(const char *path, const char *branch,
 	       branch, path, branch);
 }
 
-static char *dwim_branch(const char *path, char **new_branch)
+static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
 {
 	int n;
 	int branch_exists;
@@ -801,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 = unique_tracking_name(*new_branch, &oid, NULL, NULL);
+		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;
@@ -909,7 +923,7 @@ 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(path, &new_branch_to_free);
+		char *s = dwim_branch(&opts, path, &new_branch_to_free);
 		if (s)
 			branch = branch_to_free = s;
 		new_branch = new_branch_to_free;
diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
index 5c105cf252..a37137042d 100755
--- a/t/t2400-worktree-add.sh
+++ b/t/t2400-worktree-add.sh
@@ -669,6 +669,19 @@ test_expect_success 'git worktree add --guess-remote sets up tracking' '
 		test_cmp_rev refs/remotes/repo_a/foo refs/heads/foo
 	)
 '
+
+test_expect_success 'git worktree add --guess-remote fails if there are multiple matches' '
+	test_when_finished rm -rf repo_a repo_b foo &&
+	setup_remote_repo repo_a repo_b &&
+	(
+		cd repo_b &&
+		git remote add repo_a2 ../repo_a &&
+		git fetch repo_a2 &&
+		test_must_fail git worktree add --guess-remote ../foo 2>actual &&
+		test_grep "matched multiple (2) remote tracking branches" actual
+	)
+'
+
 test_expect_success 'git worktree add --guess-remote sets up tracking (quiet)' '
 	test_when_finished rm -rf repo_a repo_b foo &&
 	setup_remote_repo repo_a repo_b &&
-- 
gitgitgadget
Junio C HamanoAug 26, 2026, 15:24 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v9 1/4] checkout: extract function to display advice for ambiguous remotes

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

Don't we want to describe a bit of explanation between these two lines? There are a few things that immediately come to mind as motivation for such changes, like that the original place was too deeply nested, that the original code was incorrectly indented, and that we are going to extend this function in later steps in the series.

> +static void advice_disambiguating_remotes(enum checkout_command which_command)
> +{

[2/4] updates this function to a better name; let's give it that name from the beginning.

Junio C HamanoAug 26, 2026, 16:46 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v9 2/4] checkout: improve message for ambiguous remote branch name

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 18 quoted lines
> diff --git a/checkout.c b/checkout.c
> index 1588b116ee..2806b783ec 100644
> --- a/checkout.c
> +++ b/checkout.c
> @@ -8,6 +8,7 @@
>  #include "checkout.h"
>  #include "config.h"
>  #include "strbuf.h"
> +#include "string-list.h"
>  
>  struct tracking_name_data {
>  	/* const */ char *src_ref;
> @@ -17,6 +18,7 @@ struct tracking_name_data {
>  	const char *default_remote;
>  	char *default_dst_ref;
>  	struct object_id *default_dst_oid;
> +	struct string_list **remote_names;
>  };

Do we really need double indirection? The unique_tracking_name() function that uses this struct for callback receives a pointer to the string list the caller has, and the job of the callback is to append to the supplied string list.

It is not like it wants to swap the given pointer to a string list to the pointer to another string list, so I do not see a reason for anybody involved in the callchain to want this as a pointer to a pointer.

Show 7 quoted lines
>  #define TRACKING_NAME_DATA_INIT { 0 }
> @@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
>  		oidcpy(dst, cb->dst_oid);
>  		cb->default_dst_oid = dst;
>  	}
> +	if (cb->remote_names)
> +		string_list_append(*cb->remote_names, remote->name);
If we lose the double indirection, this can become
		string_list_append(cb->remote_names, remote->name);
Show 17 quoted lines
>  char *unique_tracking_name(const char *name, struct object_id *oid,
> -			   int *dwim_remotes_matched)
> +			   int *dwim_remotes_matched,
> +			   struct string_list *dwim_remote_names)
>  {
>  	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
>  	const char *default_remote = NULL;
> -	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
> +
> +	if (!repo_config_get_string_tmp(the_repository,
> +					"checkout.defaultremote",
> +					&default_remote))
>  		cb_data.default_remote = default_remote;
>  	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
>  	cb_data.dst_oid = oid;
> +	if (dwim_remote_names)
> +		cb_data.remote_names = &dwim_remote_names;
And this can become
		cb_data.remote_names = dwim_remote_names;
Yoichi NAKAYAMA via GitGitGadgetAug 27, 2026, 14:41 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v10 0/4] worktree add: improve message for ambiguous remote branch name

'git worktree add ../foo-dir bar-topic' fails to dwim when there are multiple remote branches with name `bar-topic'. But it doesn't display meaningful message as 'git checkout bar-topic' does under the same situation.

We improve this by adding advice and modify the error message for worktree add.

By Junio's suggestion, we include matched remote names in the advice. It is applied to checkout, too.

We also fix the behavior of --guess-remote when there are multiple matches.
Changes from the previous patch:
 * [1/4] fix the function name and add detailed commit message
 * [2/4] change type of tracking_name_data.remote_names
Yoichi NAKAYAMA (4):
  checkout: extract function to display advice for ambiguous remotes
  checkout: improve message for ambiguous remote branch name
  worktree add: improve message for ambiguous remote branch name
  worktree add: treat multiple matches with --guess-remote as an error
 Documentation/config/worktree.adoc |  5 +-
 Documentation/git-worktree.adoc    |  4 +-
 builtin/checkout.c                 | 76 ++++++++++++++++++------------
 builtin/worktree.c                 | 57 +++++++++++++++++++---
 checkout.c                         | 13 ++++-
 checkout.h                         |  5 +-
 t/t2400-worktree-add.sh            | 17 ++++++-
 7 files changed, 133 insertions(+), 44 deletions(-)
base-commit: f78ce2f7b6df702f93d40b85d6bda92a3f65da79
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v10
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v10
Pull-Request: https://github.com/gitgitgadget/git/pull/2197
Range-diff vs v9:
 1:  e3f7d88520 ! 1:  7650c38d6b checkout: extract function to display advice for ambiguous remotes
     @@ Metadata
       ## Commit message ##
          checkout: extract function to display advice for ambiguous remotes
      
     +    Fix incorrect indentation and reduce nesting. We are going to extend
     +    this function in subsequent commits.
     +
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
       ## builtin/checkout.c ##
     @@ builtin/checkout.c: enum checkout_command {
       	CHECKOUT_RESTORE = 3,
       };
       
     -+static void advice_disambiguating_remotes(enum checkout_command which_command)
     ++static void advise_disambiguating_remotes(enum checkout_command which_command)
      +{
      +	const char *cmdname;
      +
     @@ builtin/checkout.c: enum checkout_command {
      +		cmdname = "switch";
      +		break;
      +	default:
     -+		BUG("command <%d> should not reach parse_remote_branch",
     ++		BUG("command <%d> should not reach advise_disambiguating_remotes",
      +		    which_command);
      +		break;
      +	}
     @@ builtin/checkout.c: static char *parse_remote_branch(const char *arg,
      -	    die(_("'%s' matched multiple (%d) remote tracking branches"),
      -		arg, num_matches);
      +		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     -+			advice_disambiguating_remotes(which_command);
     ++			advise_disambiguating_remotes(which_command);
      +
      +		die(_("'%s' matched multiple (%d) remote tracking branches"),
      +		    arg, num_matches);
 2:  89c0f4d303 ! 2:  c37c9c237a checkout: improve message for ambiguous remote branch name
     @@ builtin/checkout.c: enum checkout_command {
       	CHECKOUT_RESTORE = 3,
       };
       
     --static void advice_disambiguating_remotes(enum checkout_command which_command)
     +-static void advise_disambiguating_remotes(enum checkout_command which_command)
      +static void advise_disambiguating_remotes(enum checkout_command which_command,
      +					  const char *branch,
      +					  const struct string_list *matched_remote_names)
     @@ builtin/checkout.c: enum checkout_command {
       
       	switch (which_command) {
       	case CHECKOUT_CHECKOUT:
     -@@ builtin/checkout.c: static void advice_disambiguating_remotes(enum checkout_command which_command)
     +@@ builtin/checkout.c: static void advise_disambiguating_remotes(enum checkout_command which_command)
       		break;
       	}
       
     @@ builtin/checkout.c: static char *parse_remote_branch(const char *arg,
       
       	if (!remote && num_matches > 1) {
       		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     --			advice_disambiguating_remotes(which_command);
     +-			advise_disambiguating_remotes(which_command);
      -
      +			advise_disambiguating_remotes(which_command, arg,
      +						      &matched_remote_names);
     @@ checkout.c: struct tracking_name_data {
       	const char *default_remote;
       	char *default_dst_ref;
       	struct object_id *default_dst_oid;
     -+	struct string_list **remote_names;
     ++	struct string_list *remote_names;
       };
       
       #define TRACKING_NAME_DATA_INIT { 0 }
     @@ checkout.c: static int check_tracking_name(struct remote *remote, void *cb_data)
       		cb->default_dst_oid = dst;
       	}
      +	if (cb->remote_names)
     -+		string_list_append(*cb->remote_names, remote->name);
     ++		string_list_append(cb->remote_names, remote->name);
       	if (cb->dst_ref) {
       		free(query.dst);
       		return 0;
     @@ checkout.c: static int check_tracking_name(struct remote *remote, void *cb_data)
       		cb_data.default_remote = default_remote;
       	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
       	cb_data.dst_oid = oid;
     -+	if (dwim_remote_names)
     -+		cb_data.remote_names = &dwim_remote_names;
     ++	cb_data.remote_names = dwim_remote_names;
       	for_each_remote(check_tracking_name, &cb_data);
       	if (dwim_remotes_matched)
       		*dwim_remotes_matched = cb_data.num_matches;
 3:  1010ac3295 = 3:  35814b47a4 worktree add: improve message for ambiguous remote branch name
 4:  edb88b658a = 4:  407c53b33c worktree add: treat multiple matches with --guess-remote as an error
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 27, 2026, 14:41 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v10 1/4] checkout: extract function to display advice for ambiguous remotes

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

Fix incorrect indentation and reduce nesting. We are going to extend this function in subsequent commits.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 62 ++++++++++++++++++++++++----------------------
 1 file changed, 33 insertions(+), 29 deletions(-)
Show changes to builtin/checkout.c +33 −29
diff --git a/builtin/checkout.c b/builtin/checkout.c
index 55e3a89a85..3cd5fff709 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,6 +1343,34 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
+static void advise_disambiguating_remotes(enum checkout_command which_command)
+{
+	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 advise_disambiguating_remotes",
+		    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);
+}
+
 static char *parse_remote_branch(const char *arg,
 				 struct object_id *rev,
 				 int could_be_checkout_paths,
@@ -1358,35 +1386,11 @@ 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))
+			advise_disambiguating_remotes(which_command);
+
+		die(_("'%s' matched multiple (%d) remote tracking branches"),
+		    arg, num_matches);
 	}
 
 	return remote;
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 27, 2026, 14:41 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v10 2/4] checkout: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git checkout bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we cannot determine a single remote.

To make it easier to resolve the ambiguity, provide the names of the matching remotes for the specified branch name.

To achieve that, add an optional feature to the `unique_tracking_name()` function that allows the matching remote names to be exposed to the caller.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/checkout.c | 28 ++++++++++++++++++++--------
 builtin/worktree.c |  4 ++--
 checkout.c         | 13 +++++++++++--
 checkout.h         |  5 ++++-
 4 files changed, 37 insertions(+), 13 deletions(-)
Show changes to 4 files +37 −13

builtin/checkout.c, builtin/worktree.c, checkout.c, checkout.h

diff --git a/builtin/checkout.c b/builtin/checkout.c
index 3cd5fff709..2bc21aa49b 100644
--- a/builtin/checkout.c
+++ b/builtin/checkout.c
@@ -1343,9 +1343,12 @@ enum checkout_command {
 	CHECKOUT_RESTORE = 3,
 };
 
-static void advise_disambiguating_remotes(enum checkout_command which_command)
+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:
@@ -1360,15 +1363,19 @@ static void advise_disambiguating_remotes(enum checkout_command which_command)
 		break;
 	}
 
-	advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
+	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 origin/<name>\n"
+		 "    git %s --track <remote>/%s\n"
 		 "\n"
-		 "If you'd like to always have checkouts of an ambiguous <name> prefer\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);
+	       cmdname, branch);
 }
 
 static char *parse_remote_branch(const char *arg,
@@ -1377,7 +1384,10 @@ static char *parse_remote_branch(const char *arg,
 				 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"
@@ -1387,12 +1397,14 @@ 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);
-
+			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;
 }
 
diff --git a/builtin/worktree.c b/builtin/worktree.c
index 654d27c3e1..22c8e5e131 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -782,7 +782,7 @@ 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);
+		char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
 		return remote;
 	}
 	return NULL;
@@ -904,7 +904,7 @@ static int add(int ac, const char **av, const char *prefix,
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL);
+			remote = unique_tracking_name(branch, &oid, NULL, NULL);
 			if (remote) {
 				new_branch = branch;
 				branch = new_branch_to_free = remote;
diff --git a/checkout.c b/checkout.c
index 1588b116ee..a0d0229435 100644
--- a/checkout.c
+++ b/checkout.c
@@ -8,6 +8,7 @@
 #include "checkout.h"
 #include "config.h"
 #include "strbuf.h"
+#include "string-list.h"
 
 struct tracking_name_data {
 	/* const */ char *src_ref;
@@ -17,6 +18,7 @@ struct tracking_name_data {
 	const char *default_remote;
 	char *default_dst_ref;
 	struct object_id *default_dst_oid;
+	struct string_list *remote_names;
 };
 
 #define TRACKING_NAME_DATA_INIT { 0 }
@@ -39,6 +41,8 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 		oidcpy(dst, cb->dst_oid);
 		cb->default_dst_oid = dst;
 	}
+	if (cb->remote_names)
+		string_list_append(cb->remote_names, remote->name);
 	if (cb->dst_ref) {
 		free(query.dst);
 		return 0;
@@ -48,14 +52,19 @@ static int check_tracking_name(struct remote *remote, void *cb_data)
 }
 
 char *unique_tracking_name(const char *name, struct object_id *oid,
-			   int *dwim_remotes_matched)
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names)
 {
 	struct tracking_name_data cb_data = TRACKING_NAME_DATA_INIT;
 	const char *default_remote = NULL;
-	if (!repo_config_get_string_tmp(the_repository, "checkout.defaultremote", &default_remote))
+
+	if (!repo_config_get_string_tmp(the_repository,
+					"checkout.defaultremote",
+					&default_remote))
 		cb_data.default_remote = default_remote;
 	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
 	cb_data.dst_oid = oid;
+	cb_data.remote_names = dwim_remote_names;
 	for_each_remote(check_tracking_name, &cb_data);
 	if (dwim_remotes_matched)
 		*dwim_remotes_matched = cb_data.num_matches;
diff --git a/checkout.h b/checkout.h
index 55920e7aeb..0b185a0fc9 100644
--- a/checkout.h
+++ b/checkout.h
@@ -3,6 +3,8 @@
 
 #include "hash.h"
 
+struct string_list;
+
 /*
  * Check if the branch name uniquely matches a branch name on a remote
  * tracking branch.  Return the name of the remote if such a branch
@@ -10,6 +12,7 @@
  */
 char *unique_tracking_name(const char *name,
 			   struct object_id *oid,
-			   int *dwim_remotes_matched);
+			   int *dwim_remotes_matched,
+			   struct string_list *dwim_remote_names);
 
 #endif /* CHECKOUT_H */
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 27, 2026, 14:41 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v10 3/4] worktree add: improve message for ambiguous remote branch name

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When the user runs 'git worktree add ../foo-dir bar-topic' without specifying a remote, and there is no local branch named bar-topic, we try to guess which remote branch bar-topic refers to, then create a new branch named bar-topic that tracks the remote branch.

If multiple remotes have a branch named bar-topic, we silently gave up, leaving the variable 'branch' intact. We then entered the conditional clause 'if (!opts.orphan && !lookup_commit_reference_by_name(branch))' and triggered an "invalid reference" error. This error message did not provide enough information to resolve the ambiguity.

When multiple matching branches are found, display a hint and a descriptive error message and die immediately.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 builtin/worktree.c      | 37 ++++++++++++++++++++++++++++++++++---
 t/t2400-worktree-add.sh |  4 ++--
 2 files changed, 36 insertions(+), 5 deletions(-)
Show changes to 2 files +36 −5

builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/builtin/worktree.c b/builtin/worktree.c
index 22c8e5e131..c745deddde 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -764,6 +764,25 @@ 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 char *path, char **new_branch)
 {
 	int n;
@@ -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 object_id oid;
 		struct commit *commit;
-		char *remote;
 
 		commit = lookup_commit_reference_by_name(branch);
 		if (!commit) {
-			remote = unique_tracking_name(branch, &oid, NULL, NULL);
+			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"))
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.actual
-- 
gitgitgadget
Yoichi NAKAYAMA via GitGitGadgetAug 27, 2026, 14:41 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

[PATCH v10 4/4] worktree add: treat multiple matches with --guess-remote as an error

From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>

When 'git worktree add <path>' is invoked without <commit-ish> and with the --guess-remote option (or when worktree.guessRemote is set to true), it tries to find a remote-tracking branch matching the basename of <path>.

Currently, the behavior when multiple matches are found is the same as when no match is found: it falls back to creating a branch from HEAD. This has been the behavior since 71d6682d8c (worktree: add --guess-remote option to add subcommand, 2017-11-29), when the option was first introduced.

However, if the specified <path> matches any remote-tracking branch, we infer that the user intended to use one of the remote-tracking branches as the start-point rather than HEAD. So we abort the creation of the branch and worktree when there are multiple matches, and instruct the user to choose the start-point.

Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
---
 Documentation/config/worktree.adoc |  5 +++--
 Documentation/git-worktree.adoc    |  4 +++-
 builtin/worktree.c                 | 20 +++++++++++++++++---
 t/t2400-worktree-add.sh            | 13 +++++++++++++
 4 files changed, 36 insertions(+), 6 deletions(-)
Show changes to 4 files +36 −6

Documentation/config/worktree.adoc, Documentation/git-worktree.adoc, builtin/worktree.c, t/t2400-worktree-add.sh

diff --git a/Documentation/config/worktree.adoc b/Documentation/config/worktree.adoc
index a248076ea5..0930183b91 100644
--- a/Documentation/config/worktree.adoc
+++ b/Documentation/config/worktree.adoc
@@ -5,8 +5,9 @@
 	set to true, `worktree add` tries to find a remote-tracking
 	branch whose name uniquely matches the new branch name.  If
 	such a branch exists, it is checked out and set as "upstream"
-	for the new branch.  If no such match can be found, it falls
-	back to creating a new branch from the current `HEAD`.
+	for the new branch.  If multiple matches are found, the command
+	fails.  If no such match can be found, it falls back to
+	creating a new branch from the current `HEAD`.
 
 `worktree.useRelativePaths`::
 	Link worktrees using relative paths (when "`true`") or absolute
diff --git a/Documentation/git-worktree.adoc b/Documentation/git-worktree.adoc
index fbf8426cd9..32787eacc3 100644
--- a/Documentation/git-worktree.adoc
+++ b/Documentation/git-worktree.adoc
@@ -219,7 +219,9 @@ To remove a locked worktree, specify `--force` twice.
 	of creating a new branch from `HEAD`, if there exists a tracking
 	branch in exactly one remote matching the basename of _<path>_,
 	base the new branch on the remote-tracking branch, and mark
-	the remote-tracking branch as "upstream" from the new branch.
+	the remote-tracking branch as "upstream" from the new branch. If
+	there are multiple matches, the command fails. If there is no
+	match, the command falls back to creating a new branch from `HEAD`.
 +
 This can also be set up as the default behaviour by using the
 `worktree.guessRemote` config option.
diff --git a/builtin/worktree.c b/builtin/worktree.c
index c745deddde..07163bf9b7 100644
--- a/builtin/worktree.c
+++ b/builtin/worktree.c
@@ -783,7 +783,7 @@ static void advise_disambiguating_remotes(const char *path, const char *branch,
 	       branch, path, branch);
 }
 
-static char *dwim_branch(const char *path, char **new_branch)
+static char *dwim_branch(const struct add_opts *opts, const char *path, char **new_branch)
 {
 	int n;
 	int branch_exists;
@@ -801,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 = unique_tracking_name(*new_branch, &oid, NULL, NULL);
+		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;
@@ -909,7 +923,7 @@ 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(path, &new_branch_to_free);
+		char *s = dwim_branch(&opts, path, &new_branch_to_free);
 		if (s)
 			branch = branch_to_free = s;
 		new_branch = new_branch_to_free;
diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
index 5c105cf252..a37137042d 100755
--- a/t/t2400-worktree-add.sh
+++ b/t/t2400-worktree-add.sh
@@ -669,6 +669,19 @@ test_expect_success 'git worktree add --guess-remote sets up tracking' '
 		test_cmp_rev refs/remotes/repo_a/foo refs/heads/foo
 	)
 '
+
+test_expect_success 'git worktree add --guess-remote fails if there are multiple matches' '
+	test_when_finished rm -rf repo_a repo_b foo &&
+	setup_remote_repo repo_a repo_b &&
+	(
+		cd repo_b &&
+		git remote add repo_a2 ../repo_a &&
+		git fetch repo_a2 &&
+		test_must_fail git worktree add --guess-remote ../foo 2>actual &&
+		test_grep "matched multiple (2) remote tracking branches" actual
+	)
+'
+
 test_expect_success 'git worktree add --guess-remote sets up tracking (quiet)' '
 	test_when_finished rm -rf repo_a repo_b foo &&
 	setup_remote_repo repo_a repo_b &&
-- 
gitgitgadget
Junio C HamanoAug 27, 2026, 17:32 UTC in reply to Yoichi NAKAYAMA via GitGitGadget on lore

Re: [PATCH v10 0/4] worktree add: improve message for ambiguous remote branch name

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 17 quoted lines
> 'git worktree add ../foo-dir bar-topic' fails to dwim when there are
> multiple remote branches with name `bar-topic'. But it doesn't display
> meaningful message as 'git checkout bar-topic' does under the same
> situation.
>
> We improve this by adding advice and modify the error message for worktree
> add.
>
> By Junio's suggestion, we include matched remote names in the advice. It is
> applied to checkout, too.
>
> We also fix the behavior of --guess-remote when there are multiple matches.
>
> Changes from the previous patch:
>
>  * [1/4] fix the function name and add detailed commit message
>  * [2/4] change type of tracking_name_data.remote_names

This iteration looks good to me. Let's mark it for 'next' unless we hear other comments in a few days.

Thanks.

Back to recent threads