Re: [PATCH v3] submodule: Improve documentation of update subcommand

From: Michal Sojka <sojkam1@fel.cvut.cz>
Date: Feb 23, 2015, 13:31 UTC
Message-ID: <87egpgdaac.fsf@steelpick.2x.cz>
In-Reply-To: <xmqqlhjsxira.fsf@gitster.dls.corp.google.com>

On Sat, Feb 21 2015, Junio C Hamano wrote:

Show 9 quoted lines

> Michal Sojka <sojkam1@fel.cvut.cz> writes:
>>  update::
>> +	Update the registered submodules to match what the superproject
>> +	expects by cloning missing submodules and updating the working
>> +	tree of the submodules. The "updating" can be done in several
>> +	ways depending on command line options and the value of
>> +	`submodule.<name>.update` in .git/config:
>
> No quoting around .git/config?

There is not quoting in the rest of the file as well.

> Actually, it is probably better not to spell out that path. "... and
> the value of the `...` configuration variable" would be better.

Yes, I changed it to this. See the followup mail.

Show 17 quoted lines

>>  	When running add, allow adding an otherwise ignored submodule path.
>>  	When running deinit the submodule work trees will be removed even if
>>  	they contain local changes.
>> -	When running update, throw away local changes in submodules when
>> -	switching to a different commit; and always run a checkout operation
>> -	in the submodule, even if the commit listed in the index of the
>> -	containing repository matches the commit checked out in the submodule.
>> +	When running update and the checkout method is used, throw away
>> +	local changes in submodules when switching to a different
>> +	commit; and always run a checkout operation in the submodule,
>> +	even if the commit listed in the index of the containing
>> +	repository matches the commit checked out in the submodule.
>
> This makes a reader wonder what --force would do when --merge or
> --rebase is given from the command line (or specifiedy in the
> configuration).  The original (unfortunately) did not have that
> problem because it did not single out the --checkout mode.

I changed that to "(only effective with the checkout method)".

> The use of the phrase "the checkout method" is iffy, as nobody
> defines what it is (I just said "--checkout mode" to mean the same
> thing, but I do not think anybody defines it).  See below.

I defined it in gitmodules.txt as you suggest as well as in the description of update command in git-submodule.txt.

Thanks. -Michal