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:

* [1/4] fix the function name and add detailed commit message
* [2/4] change type of tracking_name_data.remote_names

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                         | 13 ++++-
 checkout.h                         |  5 +-
 t/t2400-worktree-add.sh            | 17 ++++++-
 7 files changed, 133 insertions(+), 44 deletions(-)

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

Range-diff vs v9:

1: e3f7d88520 ! 1: 7650c38d6b checkout: extract function to display advice for ambiguous remotes

     @@ Metadata
       ## Commit message ##
          checkout: extract function to display advice for ambiguous remotes
      
     +    Fix incorrect indentation and reduce nesting. We are going to extend
     +    this function in subsequent commits.
     +
          Signed-off-by: Yoichi NAKAYAMA <[email protected]>
      
       ## builtin/checkout.c ##
     @@ builtin/checkout.c: enum checkout_command {
       	CHECKOUT_RESTORE = 3,
       };
       
     -+static void advice_disambiguating_remotes(enum checkout_command which_command)
     ++static void advise_disambiguating_remotes(enum checkout_command which_command)
      +{
      +	const char *cmdname;
      +
     @@ builtin/checkout.c: enum checkout_command {
      +		cmdname = "switch";
      +		break;
      +	default:
     -+		BUG("command <%d> should not reach parse_remote_branch",
     ++		BUG("command <%d> should not reach advise_disambiguating_remotes",
      +		    which_command);
      +		break;
      +	}
     @@ builtin/checkout.c: static char *parse_remote_branch(const char *arg,
      -	    die(_("'%s' matched multiple (%d) remote tracking branches"),
      -		arg, num_matches);
      +		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     -+			advice_disambiguating_remotes(which_command);
     ++			advise_disambiguating_remotes(which_command);
      +
      +		die(_("'%s' matched multiple (%d) remote tracking branches"),
      +		    arg, num_matches);
 2:  89c0f4d303 ! 2:  c37c9c237a checkout: improve message for ambiguous remote branch name
     @@ builtin/checkout.c: enum checkout_command {
       	CHECKOUT_RESTORE = 3,
       };
       
     --static void advice_disambiguating_remotes(enum checkout_command which_command)
     +-static void advise_disambiguating_remotes(enum checkout_command which_command)
      +static void advise_disambiguating_remotes(enum checkout_command which_command,
      +					  const char *branch,
      +					  const struct string_list *matched_remote_names)
     @@ builtin/checkout.c: enum checkout_command {
       
       	switch (which_command) {
       	case CHECKOUT_CHECKOUT:
     -@@ builtin/checkout.c: static void advice_disambiguating_remotes(enum checkout_command which_command)
     +@@ builtin/checkout.c: static void advise_disambiguating_remotes(enum checkout_command which_command)
       		break;
       	}
       
     @@ builtin/checkout.c: static char *parse_remote_branch(const char *arg,
       
       	if (!remote && num_matches > 1) {
       		if (advice_enabled(ADVICE_CHECKOUT_AMBIGUOUS_REMOTE_BRANCH_NAME))
     --			advice_disambiguating_remotes(which_command);
     +-			advise_disambiguating_remotes(which_command);
      -
      +			advise_disambiguating_remotes(which_command, arg,
      +						      &matched_remote_names);
     @@ checkout.c: struct tracking_name_data {
       	const char *default_remote;
       	char *default_dst_ref;
       	struct object_id *default_dst_oid;
     -+	struct string_list **remote_names;
     ++	struct string_list *remote_names;
       };
       
       #define TRACKING_NAME_DATA_INIT { 0 }
     @@ checkout.c: static int check_tracking_name(struct remote *remote, void *cb_data)
       		cb->default_dst_oid = dst;
       	}
      +	if (cb->remote_names)
     -+		string_list_append(*cb->remote_names, remote->name);
     ++		string_list_append(cb->remote_names, remote->name);
       	if (cb->dst_ref) {
       		free(query.dst);
       		return 0;
     @@ checkout.c: static int check_tracking_name(struct remote *remote, void *cb_data)
       		cb_data.default_remote = default_remote;
       	cb_data.src_ref = xstrfmt("refs/heads/%s", name);
       	cb_data.dst_oid = oid;
     -+	if (dwim_remote_names)
     -+		cb_data.remote_names = &dwim_remote_names;
     ++	cb_data.remote_names = dwim_remote_names;
       	for_each_remote(check_tracking_name, &cb_data);
       	if (dwim_remotes_matched)
       		*dwim_remotes_matched = cb_data.num_matches;
 3:  1010ac3295 = 3:  35814b47a4 worktree add: improve message for ambiguous remote branch name
 4:  edb88b658a = 4:  407c53b33c worktree add: treat multiple matches with --guess-remote as an error

gitgitgadget