[PATCH v5 0/2] 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.

The changes to 'checkout' are almost identical to what Junio proposed; I have made minor adjustments to use the specified branch name. I'm not sure how to handle the "Author" field in this case, so I've set it to myself for now, but I'll correct it if that's not appropriate.

Yoichi NAKAYAMA (2):
  checkout: improve message for ambiguous remote branch name
  worktree add: improve message for ambiguous remote branch name

 builtin/checkout.c      | 75 ++++++++++++++++++++++++-----------------
 builtin/worktree.c      | 36 ++++++++++++++++++--
 checkout.c              | 14 ++++++--
 checkout.h              |  5 ++-
 t/t2400-worktree-add.sh |  4 +--
 5 files changed, 96 insertions(+), 38 deletions(-)

base-commit: dea0ea3582e6980ddbc1173cc8e3e9f9db91cde0
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2197%2Fyoichi%2Fimprove-worktree-add-error-message-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2197/yoichi/improve-worktree-add-error-message-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/2197

Range-diff vs v4:

 -:  ---------- > 1:  b838fdabb7 checkout: improve message for ambiguous remote branch name
 1:  f7c413b588 ! 2:  777862235e worktree add: improve message for ambiguous remote branch name
     @@ Commit message
          Signed-off-by: Yoichi NAKAYAMA <yoichi.nakayama@gmail.com>
      
       ## builtin/worktree.c ##
     -@@
     - 	"\n" \
     - 	"    git worktree add --orphan %s\n")
     +@@ builtin/worktree.c: static char *dwim_branch(const char *path, char **new_branch)
     + 	return NULL;
     + }
       
     -+#define WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT \
     -+	_("Matched multiple remote tracking branches, you can list them by:\n" \
     -+	"\n" \
     -+	"    git branch -r --list \"*/%s\"\n" \
     -+	"\n" \
     -+	"If you meant to create a worktree from a remote tracking branch on,\n" \
     -+	"e.g. 'origin', you can do so by:\n" \
     -+	"\n" \
     -+	"    git worktree add -b %s %s origin/%s\n" \
     -+	"\n" \
     -+	"If you'd like to always prefer some remote, e.g. 'origin',\n" \
     -+	"consider setting checkout.defaultRemote=origin in your config.")
     ++static void advise_ambiguous_remote(const char *path, const char *branch,
     ++				    const struct string_list *matched_remote_names)
     ++{
     ++	struct string_list_item *item;
      +
     - static const char * const git_worktree_usage[] = {
     - 	BUILTIN_WORKTREE_ADD_USAGE,
     - 	BUILTIN_WORKTREE_LIST_USAGE,
     ++	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)
     + {
      @@ builtin/worktree.c: 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);
     +-			remote = unique_tracking_name(branch, &oid, NULL, NULL);
     ++			char *remote;
      +			int num_matches = 0;
     -+			remote = unique_tracking_name(branch, &oid, &num_matches);
     ++			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)
     -+					advise_if_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME,
     -+							  WORKTREE_ADD_AMBIGUOUS_REMOTE_BRANCH_NAME_HINT_TEXT,
     -+							  branch, branch, path, branch);
     ++				if (!opts.quiet &&
     ++				    advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     ++					advise_ambiguous_remote(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"))
      
       ## t/t2400-worktree-add.sh ##
      @@ t/t2400-worktree-add.sh: test_expect_success '"add" <path> <branch> dwims' '