Re: [PATCH v6 00/10] Add submodulePathConfig extension and gitdir encoding

[Junio C Hamano <gitster@pobox.com>]

Adrian Ratiu <adrian.ratiu@collabora.com> writes:

> 1. Encounter errors like the following in submodule.c:
>    die(_("refusing to create/use '%s' in another submodule's "...)
>
>    These errors can happen due to a number of factors, like
>    case-insensitive filesystems or submodule layouts.
>
> 2. Need to specify non-standard gitdir repository paths, different from
>    the currently hardcoded .git/modules/<plain-name> location.

Unlike 1. that hints where the need might come from (e.g., the
mention of case insensitivity), 2. has no hint on why one may want
to use "non-standard gitdir", which is better than nothing but
probably still not helpful enough.

Perhaps giving a concrete example or two in the documentation may
help?  "Imagine you have submodule X at path P on the master branch,
and then you want to add another submodule Y at path Q on a separate
branch that does not have the submodule X yet.  If path P and path Q
overlaps THIS WAY, then THIS AND THAT BAD THINGS HAPPEN.  This feature
lets users work this around by DOING THIS AND THAT".

> If you are not in one of the two above cases, then there is no reason to
> enable this and it won't affect you.
>
> Hope this is clear, maybe we could spell it out better in the
> documentation (suggestions welcome btw) or even tell users in the error
> messages to enable this extension.

Absolutlely.  Developers answering questions only here will waste
the brain cycles spent while coming up with the answer, so please do
document what audiences the feature is meant to help.