Re: [PATCH] submodule: Fix documentation of update subcommand

From: Jens Lehmann <jens.lehmann@web.de>
Date: Nov 4, 2014, 20:22 UTC
Message-ID: <54593572.3080805@web.de>
In-Reply-To: <xmqq7fzbriew.fsf@gitster.dls.corp.google.com>

Am 04.11.2014 um 00:08 schrieb Junio C Hamano:

Show 13 quoted lines

> Michal Sojka <sojkam1@fel.cvut.cz> writes:
>>> Or something perhaps?  Or the detailed description of
>>> submodule.$name.update should be dropped from here and refer the
>>> reader to config.txt instead?
>>
>> I guess you mean gitmodules.txt.
>
> Actually, I do mean the configuration.  .gitmodules is just a
> template to help the user populate .git/config, and the latter of
> which should be the sole source of truth.  This is an important
> principle, and it becomes even more important once we start talking
> about security sensitive possiblity like allowing !command as the
> value.

Not quite. You're definitely right about the !command value for the 'update' setting; this should never be taken from .gitmodules but only from .git/config. But apart from that following this principle would hurt submodule users a lot. The only thing that should be set in stone in .git/config is the 'url' setting, because an older url might not even exist anmore. But e.g. the 'branch' setting must be taken from .gitmodules. Otherwise we could not change it on a per-superproject-branch basis. And if the 'path' setting would only be taken from .git/config instead of .gitmodules, we wouldn't even be able to rename submodules (which is exactly what this setting was added for in the first place). The same applies to 'ignore' and 'fetch'.

So I believe that gitmodules.txt should describe all ćonfig options that can be provided by upstream (and e.g. mention that the 'url' and 'update' values are copied into .git/config on init), while all settings that can be overridden locally should be documented in config.txt (which will be a subset of those documented in gitmodules.txt).

Show 10 quoted lines

>> The `!command` form is not documented in gitmodules.txt. Maybe it would
>> be best to fully document .update in gitmodules.txt and just refer to
>> there. Having documentation at two places seems to be confusing not only
>> for users, but also for those who send patches :)
>>
>> I'm no longer able to formulate my proposal properly as a patch tonight,
>> but if needed I'll try it later.
>
> That is fine.  People have lived with the current text for more than
> two years without problems, so we are obviously not in a hurry.

Yup.