[PATCH v5] tracking branches: add advice to ambiguous refspec error

From: Tao Klerks <tao@klerks.biz>

The error "not tracking: ambiguous information for ref" is raised when we are evaluating what tracking information to set on a branch, and find that the ref to be added as tracking branch is mapped under multiple remotes' fetch refspecs.

This can easily happen when a user copy-pastes a remote definition in their git config, and forgets to change the tracking path.

Add advice in this situation, explicitly highlighting which remotes are involved and suggesting how to correct the situation.

Signed-off-by: Tao Klerks <tao@klerks.biz>
---
    tracking branches: add advice to ambiguous refspec error
    
    This fifth version attempts to address Junio's concerns over unnecessary
    extra error-preparation work being done in the very-vastly-more-common
    "normal" case.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1183%2FTaoK%2Fadvise-ambiguous-tracking-refspec-v5
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1183/TaoK/advise-ambiguous-tracking-refspec-v5
Pull-Request: https://github.com/gitgitgadget/git/pull/1183

Range-diff vs v4:

 1:  ac6c782f566 ! 1:  4478eaed6df tracking branches: add advice to ambiguous refspec error
     @@ Documentation/config/advice.txt: advice.*::
       +
       --
      +	ambiguousFetchRefspec::
     -+		Advice shown when branch tracking relationship setup fails due
     -+		to multiple remotes' refspecs mapping to the same remote
     -+		tracking namespace in the repo.
     ++		Advice shown when fetch refspec for multiple remotes map to
     ++		the same remote-tracking branch namespace and causes branch
     ++		tracking set-up to fail.
       	fetchShowForcedUpdates::
       		Advice shown when linkgit:git-fetch[1] takes a long time
       		to calculate forced updates after ref updates, or to warn
     @@ branch.c: struct tracking {
       
      +struct find_tracked_branch_cb {
      +	struct tracking *tracking;
     -+	struct strbuf remotes_advice;
     ++	struct string_list ambiguous_remotes;
      +};
      +
       static int find_tracked_branch(struct remote *remote, void *priv)
     @@ branch.c: struct tracking {
      +	struct tracking *tracking = ftb->tracking;
       
       	if (!remote_find_tracking(remote, &tracking->spec)) {
     - 		if (++tracking->matches == 1) {
     -@@ branch.c: static int find_tracked_branch(struct remote *remote, void *priv)
     +-		if (++tracking->matches == 1) {
     ++		switch (++tracking->matches) {
     ++		case 1:
     + 			string_list_append(tracking->srcs, tracking->spec.src);
     + 			tracking->remote = remote->name;
     +-		} else {
     ++			break;
     ++		case 2:
     ++			// there are at least two remotes; backfill the first one
     ++			string_list_append(&ftb->ambiguous_remotes, tracking->spec.src);
     ++			/* fall through */
     ++		default:
     ++			string_list_append(&ftb->ambiguous_remotes, remote->name);
       			free(tracking->spec.src);
       			string_list_clear(tracking->srcs, 0);
     ++		break;
       		}
     -+		/*
     -+		 * TRANSLATORS: This is a line listing a remote with duplicate
     -+		 * refspecs, to be later included in advice message
     -+		 * ambiguousFetchRefspec. For RTL languages you'll probably want
     -+		 * to swap the "%s" and leading "  " space around.
     -+		 */
     -+		strbuf_addf(&ftb->remotes_advice, _("  %s\n"), remote->name);
       		tracking->spec.src = NULL;
       	}
     - 
      @@ branch.c: static int inherit_tracking(struct tracking *tracking, const char *orig_ref)
       	return 0;
       }
     @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
       	int config_flags = quiet ? 0 : BRANCH_CONFIG_VERBOSE;
      +	struct find_tracked_branch_cb ftb_cb = {
      +		.tracking = &tracking,
     -+		.remotes_advice = STRBUF_INIT,
     ++		.ambiguous_remotes = STRING_LIST_INIT_DUP,
      +	};
       
       	memset(&tracking, 0, sizeof(tracking));
     @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
      +	if (tracking.matches > 1) {
      +		int status = die_message(_("not tracking: ambiguous information for ref %s"),
      +					    orig_ref);
     -+		if (advice_enabled(ADVICE_AMBIGUOUS_FETCH_REFSPEC))
     ++		if (advice_enabled(ADVICE_AMBIGUOUS_FETCH_REFSPEC)) {
     ++			struct strbuf remotes_advice = STRBUF_INIT;
     ++			struct string_list_item *item;
     ++
     ++			for_each_string_list_item(item, &ftb_cb.ambiguous_remotes) {
     ++				/*
     ++				 * TRANSLATORS: This is a line listing a remote with duplicate
     ++				 * refspecs in the advice message below. For RTL languages you'll
     ++				 * probably want to swap the "%s" and leading "  " space around.
     ++				 */
     ++				strbuf_addf(&remotes_advice, _("  %s\n"), item->string);
     ++			}
     ++
      +			advise(_("There are multiple remotes whose fetch refspecs map to the remote\n"
      +				 "tracking ref %s:\n"
      +				 "%s"
     @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
      +				 "different remotes' fetch refspecs map into different\n"
      +				 "tracking namespaces."),
      +			       orig_ref,
     -+			       ftb_cb.remotes_advice.buf
     ++			       remotes_advice.buf
      +			       );
     ++			strbuf_release(&remotes_advice);
     ++		}
      +		exit(status);
      +	}
       
       	if (tracking.srcs->nr < 1)
       		string_list_append(tracking.srcs, orig_ref);
      @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
     - 		exit(-1);
       
       cleanup:
     -+	strbuf_release(&ftb_cb.remotes_advice);
       	string_list_clear(&tracking_srcs, 0);
     ++	string_list_clear(&ftb_cb.ambiguous_remotes, 0);
       }
       
     + int read_branch_desc(struct strbuf *buf, const char *branch_name)

 Documentation/config/advice.txt |  4 +++
 advice.c                        |  1 +
 advice.h                        |  1 +
 branch.c                        | 63 +++++++++++++++++++++++++++++----
 4 files changed, 62 insertions(+), 7 deletions(-)