Re: [PATCH] Documentation: consolidate submodule.<name>.update

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Sep 25, 2017, 23:44 UTC
Message-ID: <20170925234428.GJ27425@aiede.mtv.corp.google.com>
In-Reply-To: <CAGZ79kY4tAfYERj1V2AL+piqWe6nw0qA+AHqm5w6ch9WiL86pw@mail.gmail.com>

Stefan Beller wrote:

> By as-is I refer to origin/pu.

Ah, okay. I'm not in that habit because pu frequently loses topics --- it's mostly useful as a tool to (1) distribute topic branches and (2) check whether they are compatible with each other.

[...]

> On Mon, Sep 25, 2017 at 3:22 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:

Show 9 quoted lines

>> Maybe we should work on first wordsmithing the doc and then figuring
>> out where it goes?  The current state of the doc with (?) three
>> different texts,
>
> such that each different text highlights each locations purpose.
>
>> all wrong,
>
> Care to spell out this bold claim?

In the state of "master", "man git-config" tells me that

	[submodule "<name>"]
		update = ...

sets the "default update procedure for a submodule". It suggests that I read about "git submodule update" in git-submodule(1) for more details. This is problematic because

 1. It doesn't tell me when I should and should not set it.
 2. I would expect "git checkout --recurse-submodules" to respect the
    default update procedure.
 3. It doesn't tell me what commands like "git fetch
    --recurse-submodules" will do.
 4. It doesn't point me to better alternatives, when this
    configuration doesn't fit my use case.

"man git-submodule" doesn't have a section on submodule.<name>.update. It has references scattered throughout the manpage. It only tells me how the setting affects the "git submodule update" command and doesn't address the problems (1)-(4).

"man gitmodules" also refers to this setting as the "default update procedure for the named submodule". It doesn't answer the questions (1)-(4) either.

Thanks and hope that helps, Jonathan