Re: [PATCH 2/2] submodule--helper: advise on fatal alternate error

From: Jeff King <peff@peff.net>
Date: Nov 27, 2019, 11:49 UTC
Message-ID: <20191127114908.GD22221@sigill.intra.peff.net>
In-Reply-To: <26c3b388a24eef7f03eb423c10e21430bc3f019e.1574731649.git.jonathantanmy@google.com>

On Mon, Nov 25, 2019 at 05:31:00PM -0800, Jonathan Tan wrote:

Show 20 quoted lines

> When recursively cloning a superproject with some shallow modules
> defined in its .gitmodules, then recloning with "--reference=<path>", an
> error occurs. For example:
> 
>   git clone --recurse-submodules --branch=master -j8 \
>     https://android.googlesource.com/platform/superproject \
>     master
>   git clone --recurse-submodules --branch=master -j8 \
>     https://android.googlesource.com/platform/superproject \
>     --reference master master2
> 
> fails with:
> 
>   fatal: submodule '<snip>' cannot add alternate: reference repository
>   '<snip>' is shallow
> 
> When a alternate computed from the superproject's alternate cannot be
> added, whether in this case or another, advise about configuring the
> "submodule.alternateErrorStrategy" configuration option and using
> "--reference-if-able" instead of "--reference" when cloning.

It sounds like that advice sends people in the right direction, which is a good thing.

I kind of wonder if the default for alternateErrorStrategy should be more lenient, but I don't really know much about the feature in the first place. I'll let people who are more clueful ponder that, but certainly your patch is an improvement in the meantime.

One minor suggestion:

Show 7 quoted lines

> +static void advise_submodule_alternate_error_die(void)
> +{
> +	if (!advice_submodule_alternate_error_strategy_die)
> +		return;
> +	advise(_("An alternate computed from a superproject's alternate is invalid."));
> +	advise(_("To allow Git to clone without an alternate in such a case, set submodule.alternateErrorStrategy to 'info' or, equivalently, clone with '--reference-if-able' instead of '--reference'."));
> +}

The advise() function handles newlines gracefully (putting a "hint:" at the start of each line). So you can put both in a single call, and wrap the second long line, which also lets translators see the whole message as a unit. Many of the existing calls define the message outside of any function (e.g., embedded_advice), which makes it easier to see how long the lines will be when displayed.

So maybe:

  static const alternate_error_advice[] = N_(
  "An alternate computed from a superproject's alternate is invalid.\n"
  "To allow Git to clone without an alternate in such a case, set\n"
  "submodule.alternateErrorStrategy to 'info' or, equivalently, clone with\n"
  "'--reference-if-able' instead of '--reference'."
  );

  ...
	switch (sas->error_mode) {
	case SUBMODULE_ALTERNATE_ERROR_DIE:
		if (advice_submodule_alternate_error_strategy_die)
			advise(_(alternate_error_advice));
		die(...);

-Peff