Skip to content

worktree add: improve message for ambiguous remote branch name #2197

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yoichi wants to merge 3 commits into
base: master
Choose a base branch
from
Open

worktree add: improve message for ambiguous remote branch name #2197

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e3f7d88
checkout: extract function to display advice for ambiguous remotes
yoichi Aug 20, 2026
97e99ae
checkout: improve message for ambiguous remote branch name
yoichi Aug 20, 2026
dcb84a6
worktree add: improve message for ambiguous remote branch name
yoichi Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 46 additions & 30 deletions builtin/checkout.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1343,13 +1343,51 @@ enum checkout_command {
CHECKOUT_RESTORE = 3,

@gitgitgadget gitgitgadget Bot Aug 19, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"D. Ben Knoble" wrote on the Git mailing list (how to reply to this email):

On Wed, Aug 19, 2026 at 8:51 AM Yoichi NAKAYAMA via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> When the user runs 'git checkout bar-topic' command that does not
> exactly say which remote they want to work with, and there is no local
> branch named bar-topic, we try to guess which remote by passing
> bar-topic then create a new branch named bar-topic which tracks the
> remote branch.
>
> If multiple remotes have a branch named bar-topic, we cannot determine
> a single specific remote. Therefore, we provide information that the
> user can utilize to resolve the issue.
>
> To make the advice more feasible, we will provide matched remote names
> for the specified branch name.
>
> To achive that, we add an optional feature to the
> `unique_tracking_name()` function that allows the matched remote name
> to be exposed to the caller.
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> ---
>  builtin/checkout.c | 75 +++++++++++++++++++++++++++-------------------
>  builtin/worktree.c |  4 +--
>  checkout.c         | 14 +++++++--
>  checkout.h         |  5 +++-
>  4 files changed, 63 insertions(+), 35 deletions(-)
>
> diff --git a/builtin/checkout.c b/builtin/checkout.c
> index 55e3a89a85..a2749352e6 100644
> --- a/builtin/checkout.c
> +++ b/builtin/checkout.c
> @@ -1343,13 +1343,51 @@ enum checkout_command {
>         CHECKOUT_RESTORE = 3,
>  };
>
> +static void be_explicit(const char *branch,

Be explicit about what? Reading below, a better name might be
"advise_ambiguous_remote_branch_name" or something, idk.

> +                       enum checkout_command which_command,
> +                       const struct string_list *matched_remote_names)
> +{
> +       const char *cmdname;
> +       struct string_list_item *item;
> +
> +       switch (which_command) {
> +       case CHECKOUT_CHECKOUT:
> +               cmdname = "checkout";
> +               break;
> +       case CHECKOUT_SWITCH:
> +               cmdname = "switch";
> +               break;
> +       default:
> +               BUG("command <%d> should not reach parse_remote_branch",
> +                    which_command);
> +               break;
> +       }
> +
> +       advise(_("Branches with the same name appears in multiple remotes:"));
> +       for_each_string_list_item(item, matched_remote_names) {
> +               advise(_("  %s"), item->string);
> +       }
> +       advise(_("If you meant to check out a remote tracking branch on <remote>,\n"
> +                "you can do so by fully qualifying the name with the --track option:\n"
> +                "\n"
> +                "    git %s --track <remote>/%s\n"
> +                "\n"
> +                "If you'd like to always have checkouts of an ambiguous name prefer\n"
> +                "one remote, e.g. the 'origin' remote, consider setting\n"
> +                "checkout.defaultRemote=origin in your config."),
> +              cmdname, branch);
> +}
> +

I think it's possible this refactor is a bit distracting from the
overall goal of the patch, though I don't think extracting the
function is a bad thing. Maybe split the steps up into

- mechanical refactoring (no behavior change)
- changes to improve the message (easier to see the diff)

? Just my 2 cents.

>  static char *parse_remote_branch(const char *arg,
>                                  struct object_id *rev,
>                                  int could_be_checkout_paths,
>                                  enum checkout_command which_command)
>  {
>         int num_matches = 0;
> -       char *remote = unique_tracking_name(arg, rev, &num_matches);
> +       struct string_list matched_remote_names = STRING_LIST_INIT_DUP;
> +
> +       char *remote = unique_tracking_name(arg, rev, &num_matches,
> +                                           &matched_remote_names);
>
>         if (remote && could_be_checkout_paths) {
>                 die(_("'%s' could be both a local file and a tracking branch.\n"
> @@ -1358,37 +1396,14 @@ static char *parse_remote_branch(const char *arg,
>         }
>
>         if (!remote && num_matches > 1) {
> -           if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME)) {
> -                   const char *cmdname;
> -
> -                   switch (which_command) {
> -                   case CHECKOUT_CHECKOUT:
> -                           cmdname = "checkout";
> -                           break;
> -                   case CHECKOUT_SWITCH:
> -                           cmdname = "switch";
> -                           break;
> -                   default:
> -                           BUG("command <%d> should not reach parse_remote_branch",
> -                               which_command);
> -                           break;
> -                   }
> -
> -                   advise(_("If you meant to check out a remote tracking branch on, e.g. 'origin',\n"
> -                            "you can do so by fully qualifying the name with the --track option:\n"
> -                            "\n"
> -                            "    git %s --track origin/<name>\n"
> -                            "\n"
> -                            "If you'd like to always have checkouts of an ambiguous <name> prefer\n"
> -                            "one remote, e.g. the 'origin' remote, consider setting\n"
> -                            "checkout.defaultRemote=origin in your config."),
> -                          cmdname);
> -           }
> -
> -           die(_("'%s' matched multiple (%d) remote tracking branches"),
> -               arg, num_matches);
> +               if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> +                       be_explicit(arg, which_command, &matched_remote_names);
> +               die(_("'%s' matched multiple (%d) remote tracking branches"),
> +                   arg, num_matches);
>         }
>
> +       string_list_clear(&matched_remote_names, 0);
> +
>         return remote;
>  }

[rest of diff snipped]

@gitgitgadget gitgitgadget Bot Aug 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

@gitgitgadget gitgitgadget Bot Aug 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yoichi Nakayama wrote on the Git mailing list (how to reply to this email):

On Thu, Aug 20, 2026 at 11:18 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>
> >> +static void be_explicit(const char *branch,
> >
> > Be explicit about what? Reading below, a better name might be
> > "advise_ambiguous_remote_branch_name" or something, idk.
>
> It stands for "tell the user to be more explicit".  I agree with you
> that the refactoring should be done as a separate step, on top of
> which we should add the new feature, i.e., "give list of possible
> candidates", as a separate step.

I think it's a good idea to separate the steps, so I'll split the commits.
I am considering "advise_disambiguating_remotes" as a better function name.

Thanks,
-- 
Yoichi NAKAYAMA

};

static void advise_disambiguating_remotes(enum checkout_command which_command,
const char *branch,
const struct string_list *matched_remote_names)
{
const char *cmdname;
struct string_list_item *item;

switch (which_command) {
case CHECKOUT_CHECKOUT:
cmdname = "checkout";
break;
case CHECKOUT_SWITCH:
cmdname = "switch";
break;
default:
BUG("command <%d> should not reach parse_remote_branch",
which_command);
break;
}

advise(_("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"
Expand All @@ -1358,37 +1396,15 @@ static char *parse_remote_branch(const char *arg,
}

if (!remote && num_matches > 1) {
if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME)) {
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, arg,
&matched_remote_names);
die(_("'%s' matched multiple (%d) remote tracking branches"),
arg, num_matches);
}

string_list_clear(&matched_remote_names, 0);

return remote;
}

Expand Down
37 changes: 34 additions & 3 deletions builtin/worktree.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -782,12 +782,31 @@ static char *dwim_branch(const char *path, char **new_branch)
*new_branch = branchname;
if (guess_remote) {
struct object_id oid;
char *remote = unique_tracking_name(*new_branch, &oid, NULL);
char *remote = unique_tracking_name(*new_branch, &oid, NULL, NULL);
return remote;
}
return NULL;

@gitgitgadget gitgitgadget Bot Aug 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

"Yoichi NAKAYAMA via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
>
> When the user runs 'git worktree add ../foo-dir bar-topic' command
> that does not exactly say which remote they want to work with, and
> there is no local branch named bar-topic, we try to guess which remote
> by passing bar-topic then create a new branch named bar-topic which
> tracks the remote branch.
>
> If there are multiple remotes that have branch named bar-topic, we
> silently gave up, leaving the variable 'branch' intact.  Then we
> entered the conditional clause 'if (!opts.orphan &&
> !lookup_commit_reference_by_name(branch))' and triggered "invalid
> reference" error.  This error message did not contain enough
> information to resolve the issue where the remote could not be
> guessed.
>
> To improve the situation, we display a hint and a descriptive error
> message and die immediately when multiple matching branches are found.
>
> Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
> ---
>  builtin/worktree.c      | 35 +++++++++++++++++++++++++++++++++--
>  t/t2400-worktree-add.sh |  4 ++--
>  2 files changed, 35 insertions(+), 4 deletions(-)
>
> diff --git a/builtin/worktree.c b/builtin/worktree.c
> index 22c8e5e131..8286c283e0 100644
> --- a/builtin/worktree.c
> +++ b/builtin/worktree.c
> @@ -788,6 +788,25 @@ static char *dwim_branch(const char *path, char **new_branch)
>  	return NULL;
>  }
>  
> +static void advise_disambiguating_remotes(const char *path, const char *branch,
> +					  const struct string_list *matched_remote_names)
> +{
> +	struct string_list_item *item;
> +
> +	advise(_("Branches with the same name appears in multiple remotes:"));

The subject "Branches" calls for plural verb "appear" (not
"appears").  The same issue appears in [PATCH 2/3].

>  		if (!commit) {
> -			remote = unique_tracking_name(branch, &oid, NULL, NULL);
> +			char *remote;
> +			int num_matches = 0;
> +			struct string_list matched_remote_names = STRING_LIST_INIT_DUP;
> +
> +			remote = unique_tracking_name(branch, &oid, &num_matches,
> +						      &matched_remote_names);
>  			if (remote) {
>  				new_branch = branch;
>  				branch = new_branch_to_free = remote;
> +			} else if (num_matches > 1) {
> +				if (!opts.quiet &&
> +				    advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
> +					advise_disambiguating_remotes(path, branch,
> +								      &matched_remote_names);
> +				die(_("'%s' matched multiple (%d) remote tracking branches"),
> +				    branch, num_matches);
>  			}
> +			string_list_clear(&matched_remote_names, 0);
>  		}

This appears inside "} else if (ac == 2) {" to catch an invocation
like

	git worktree add ../over-there topic-branch

where the origin of topic-branch is ambiguous (in other words,
appears in multiple remotes).  But don't we have the same issue for
1 argument case that appears just above this (ac == 2) case that
handles

	git worktree add ../topic-branch

invocation?  The code reads like:

	} else if (ac < 2) {
		/* DWIM: Guess branch name from path. */
		char *s = dwim_branch(path, &new_branch_to_free);
		if (s)
			branch = branch_to_free = s;
		new_branch = new_branch_to_free;

		/* DWIM: Infer --orphan when repo has no refs. */
		opts.orphan = (!s) && dwim_orphan(&opts, !!opt_track, 1);
	} else if (ac == 2) {

where the branch name "topic-branch" is guessed from the path by
calling dwim_branch(), and we would get NULL in s.  branch is left
as-is, so it becomes "HEAD" that was assigned much earlier in the
same function.

        branch = ac < 2 ? "HEAD" : av[1];

We would create a new directory in ../topic-branch next door, and
then which branch would we check out?  Would dwim_orphan() kick in?

Perhaps we want to update that code path to disambiguate the same way?

> diff --git a/t/t2400-worktree-add.sh b/t/t2400-worktree-add.sh
> index 87b926728a..5c105cf252 100755
> --- a/t/t2400-worktree-add.sh
> +++ b/t/t2400-worktree-add.sh
> @@ -624,12 +624,12 @@ test_expect_success '"add" <path> <branch> dwims' '
>  test_expect_success '"add" <path> <branch> dwims with checkout.defaultRemote' '
>  	test_when_finished rm -rf repo_upstream repo_dwim foo &&
>  	setup_remote_repo repo_upstream repo_dwim &&
> -	git init repo_dwim &&
>  	(
>  		cd repo_dwim &&
>  		git remote add repo_upstream2 ../repo_upstream &&
>  		git fetch repo_upstream2 &&
> -		test_must_fail git worktree add ../foo foo &&
> +		test_must_fail git worktree add ../foo foo 2>error.actual &&
> +		test_grep "matched multiple (2) remote tracking branches" error.actual &&
>  		git -c checkout.defaultRemote=repo_upstream worktree add ../foo foo &&
>  		git status -uno --porcelain >status.actual &&
>  		test_must_be_empty status.actual

}

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)
{
Expand Down Expand Up @@ -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);
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"))
Expand Down
14 changes: 12 additions & 2 deletions checkout.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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 }
Expand All @@ -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;
Expand All @@ -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;
Expand Down
5 changes: 4 additions & 1 deletion checkout.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,16 @@

#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
* exists, NULL otherwise.
*/
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 */
4 changes: 2 additions & 2 deletions t/t2400-worktree-add.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading