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

On Thu, Aug 13, 2026 at 4:22 AM Junio C Hamano <[email protected]> wrote:
>
> Yoichi Nakayama <[email protected]> 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.

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