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