Re: [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines

[Stefan Beller <sbeller@google.com>]

>>>  The submodule's `$GIT_DIR/config` file would come into play when running
>>>  `git push --recurse-submodules=check` in the superproject, as this would
>>> @@ -107,13 +108,13 @@ If the submodule is not yet initialized, then the configuration
>>>  inside the submodule does not exist yet, so configuration where to
>>>  obtain the submodule from is configured here for example.
>>>
>
> I caught this in the context while replying. "so configuration where to
> obtain the submodule from is configured here for example." doesn't seem
> to read well. Maybe removing configuration from the sentence will make
> it sound better?
>
>
>>> - * the `.gitmodules` file inside the superproject. Additionally to the
>>> -   required mapping between submodule's name and path, a project usually
>>> + * The `.gitmodules` file inside the superproject. Additionally, if mapping
>>> +   is required between a submodule's name and its path, a project usually
>>
>> This changes meaning, originally it tries to say:
>>
>> * it requires mapping path <-> names.
>
> I get this ...
>
>> * but there can be more.
>
> ... but not this. Did the previous version really try to say this?
> Anyways how does this sound?

Well that was me being very sloppy trying to say that there might be
submodule.<name>.{url, ignored, shallow} settings which just happen to
be there.

>   * The `.gitmodules` file inside the superproject. A project usually
>     uses this file to suggest defaults for the upstream collection
>     of repositories for the mapping that is required between a
>     submodule's name and its path.
>
> I think it conveys the "it requires mapping path <-> names." correctly
> but doesn't convey the "but there can be more." part. I'm not sure how
> to get that into the sentence, correctly.

I did not consider that part the important part, hence my sloppiness.
Sorry for the confusion.

My main point was to say that the mapping is the important part and
must be found in the .gitmodules file, otherwise we do not consider
it a submodule (for whatever "it" is, maybe a gitlink at a path=name).

Stefan