Re: [PATCHv4 2/2] push: change submodule default to check when submodules exist

From: Stefan Beller <sbeller@google.com>
Date: Oct 6, 2016, 21:29 UTC
Message-ID: <CAGZ79kYij=7kfQa8cc1btRowBXbia01QgYTKTgz93ZBdx249Jw@mail.gmail.com>
In-Reply-To: <xmqqoa2xi5rd.fsf@gitster.mtv.corp.google.com>

On Thu, Oct 6, 2016 at 1:25 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 16 quoted lines

> Stefan Beller <sbeller@google.com> writes:
>
>> When working with submodules, it is easy to forget to push the submodules.
>> The setting 'check', which checks if any existing submodule is present on
>> at least one remote of the submodule remotes, is designed to prevent this
>> mistake.
>>
>> Flipping the default to check for submodules is safer than the current
>> default of ignoring submodules while pushing.
>>
>> However checking for submodules requires additional work[1], which annoys
>> users that do not use submodules, so we turn on the check for submodules
>> based on a cheap heuristic, the existence of the .git/modules directory.
>
> ... and other things like .gitmodules, submodule stuff in
> .git/config, etc.?

Oh right, I need to update this commit message to mention this, too

Show 6 quoted lines

>
>> +     } else if (starts_with(k, "submodule.") && ends_with(k, ".url"))
>> +             has_submodules_configured = 1;
>
> An in-code comment to explain why ".url" is so special would be
> helpful.  Documentation/config.txt says .path and .url are both

       submodule.<name>.path, submodule.<name>.url
           The path within this project and URL for a submodule. These
           variables are initially populated by git submodule init. See git-
           submodule(1) and gitmodules(5) for details.

The correct version is:

submodule.<name>.path::
    This is a config variable only found in .gitmodules files that
indicate at which
    path relative to the repository root the submodule is found.
    It is used to resolve the mapping (submodule name)<->path throughout all
    time, i.e. also later when a submodule is initialized and checked out, any
    subsequent operation that needs a submodule name/repsoitory uses it for
    lookup.

submodule.<name>.url::
    This is a config variable found both in .gitmodules files as well
as .git/config.
    In the .gitmodules files it serves as a hint where to obtain a
repository from
    to populate the gitlinks within the repository.
    On submodule-init the value will be copied over to the .git/config
file and there
    it serves as a holder of the value only until the first
submodule-update is run,
    as the initial submodule-update is using that url to clone the submodule.
    From then on it is only used as a boolean flag in the .git/config
to indicate
    whether the submodule is considered interesting for further submodule
    commands. (See the similar competing thing with submodule.<name>.ignore)

Given that it is obvious to my current me, that .url is the only sensible thing as .path is not found in the .git/config which we are searching in here. So for the purpose of this patch I'd just add a line like this to remind my future self:

    /* See if any submodule is considered interesting: */

I would like to avoid references to .path as that is not helping here. (Why does that comment point to a variable name that is not supposed to exist in the file?) So I think we really need to think how to reduce confusion in the future by readers that have more or less overview of the submodules concept.

A future version of the man page may read:

submodule.<name>.path::
    <same as before>, we may want to consider if we copy it over to
.git/config, so the
    repository may trash the .gitmodules file and the submodules keep working.

submodule.<name>.url::
    indication in .gitmodules where the submodule is cloned from. It
will be copied over
    to .git/config on submodule-init. The user may adapt the
configured urls there before
    proceeding to submodule-update, which will delete the url setting
again, as the
    cloned submodule repository will hold the authoritative setting
where the remote
    of the submodule is.
    So it only exists in .git/config for submodules that are
initialized but have never
    been cloned. Even when the submodule is deinit'd and reinited we
don't even need
    to copy the url, as we still have the old submodule repository in
.git/module/<name>

submodule.<name>.exists::
    This setting is per working tree (unlike the previous 2) that
indicates if submodule
    related commands pay attention to the given submodule. It is still
unclear how this
    works together with the .ignore setting.

Note for this future to come true, we'd have to have only 2 big series
One that Duy started to introduce per working tree configs, see
    https://public-inbox.org/git/20160720172419.25473-1-pclouds@gmail.com/
The other one is a series that hasn't seen the mailing list yet, that
I started to
separate the 2 modes of the url both as a value holder (to point at a URL) as
well as just a boolean flag for commands to acknowledge the existence of the
submodule.

> initially populated by 'git submodule init', which might be outdated
> information that confuses readers of the above code.

A lot of text but I guess we can use some ideas from here to update the .path and .url documentation. (The wording in this email is not of man page quality).

Thanks, Stefan