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

On Sun, Aug 9, 2026 at 6:57 AM Junio C Hamano <[email protected]> wrote:
>
> Junio C Hamano <[email protected]> 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