[PATCH v3] 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
    
    I believe this third version incorporates all Ævar's suggestions, and
    might be usable. Removed "RFC" prefix.

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

Range-diff vs v2:

 1:  6c1cd885dda ! 1:  22ffe81ac26 RFC: tracking branches: add advice to ambiguous refspec error
     @@ Metadata
      Author: Tao Klerks <tao@klerks.biz>
      
       ## Commit message ##
     -    RFC: tracking branches: add advice to ambiguous refspec error
     +    tracking branches: add advice to ambiguous refspec error
      
          The error "not tracking: ambiguous information for ref" is raised
          when we are evaluating what tracking information to set on a branch,
     @@ Commit message
      
       ## Documentation/config/advice.txt ##
      @@ Documentation/config/advice.txt: advice.*::
     - 		Advice shown when either linkgit:git-add[1] or linkgit:git-rm[1]
     - 		is asked to update index entries outside the current sparse
     - 		checkout.
     + 	can tell Git that you do not need help by setting these to 'false':
     + +
     + --
      +	ambiguousFetchRefspec::
      +		Advice shown when branch tracking relationship setup fails due
      +		to multiple remotes' refspecs mapping to the same remote
      +		tracking namespace in the repo.
     - --
     + 	fetchShowForcedUpdates::
     + 		Advice shown when linkgit:git-fetch[1] takes a long time
     + 		to calculate forced updates after ref updates, or to warn
      
       ## advice.c ##
      @@ advice.c: static struct {
     @@ branch.c: static int find_tracked_branch(struct remote *remote, void *priv)
       			free(tracking->spec.src);
       			string_list_clear(tracking->srcs, 0);
       		}
     -+		strbuf_addf(&ftb->remotes_advice, "  %s\n", remote->name);
     ++		/*
     ++		 * 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 *ori
       	return 0;
       }
       
     -+
     -+static const char ambiguous_refspec_advice_pre[] =
     -+N_("\n"
     -+"There are multiple remotes whose fetch refspecs map to the remote\n"
     -+"tracking ref";)
     -+static const char ambiguous_refspec_advice_post[] =
     -+N_("This is typically a configuration error.\n"
     -+"\n"
     -+"To support setting up tracking branches, ensure that\n"
     -+"different remotes' fetch refspecs map into different\n"
     -+"tracking namespaces.\n");
      +
       /*
     -  * This is called when new_ref is branched off of orig_ref, and tries
     -  * to infer the settings for branch.<new_ref>.{remote,merge} from the
     +  * Used internally to set the branch.<new_ref>.{remote,merge} config
     +  * settings so that branch 'new_ref' tracks 'orig_ref'. Unlike
      @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
       	struct tracking tracking;
       	struct string_list tracking_srcs = STRING_LIST_INIT_DUP;
     @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
      -		for_each_remote(find_tracked_branch, &tracking);
      +		for_each_remote(find_tracked_branch, &ftb_cb);
       	else if (inherit_tracking(&tracking, orig_ref))
     - 		return;
     + 		goto cleanup;
       
      @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
     - 			return;
     + 			goto cleanup;
       		}
       
      -	if (tracking.matches > 1)
     @@ branch.c: static void setup_tracking(const char *new_ref, const char *orig_ref,
      +		int status = die_message(_("not tracking: ambiguous information for ref %s"),
      +					    orig_ref);
      +		if (advice_enabled(ADVICE_AMBIGUOUS_FETCH_REFSPEC))
     -+			advise("%s %s:\n%s\n%s",
     -+			       _(ambiguous_refspec_advice_pre),
     ++			advise(_("There are multiple remotes whose fetch refspecs map to the remote\n"
     ++				 "tracking ref %s:\n"
     ++				 "%s"
     ++				 "\n"
     ++				 "This is typically a configuration error.\n"
     ++				 "\n"
     ++				 "To support setting up tracking branches, ensure that\n"
     ++				 "different remotes' fetch refspecs map into different\n"
     ++				 "tracking namespaces."),
      +			       orig_ref,
     -+			       ftb_cb.remotes_advice.buf,
     -+			       _(ambiguous_refspec_advice_post)
     ++			       ftb_cb.remotes_advice.buf
      +			       );
      +		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);
     + }
     + 

 Documentation/config/advice.txt |  4 +++
 advice.c                        |  1 +
 advice.h                        |  1 +
 branch.c                        | 44 +++++++++++++++++++++++++++++----
 4 files changed, 45 insertions(+), 5 deletions(-)