[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) {