Re: [PATCH] Documentation/submodule: add command references and update options

[Jens Lehmann <Jens.Lehmann@web.de>]

Am 25.07.2011 22:30, schrieb Junio C Hamano:
> Jens Lehmann <Jens.Lehmann@web.de> writes:
> 
>> @@ -131,7 +137,7 @@ update::
>>  +
>>  If the submodule is not yet initialized, and you just want to use the
>>  setting as stored in .gitmodules, you can automatically initialize the
>> -submodule with the --init option.
>> +submodule with the '--init' option.
> 
> Don't we want to use
> 
> 	the `--init` option
> 
> instead for consistency? After all, that is what the users actually type.
> 
> 	$ git grep -e "\`--[a-z]" Documentation/ | wc -l
>         287
>         $ git grep -e "'--[a-z]" Documentation/ | wc -l
>         132

Fine by me, I just followed the style I found there. Will change all
option names (including those who are using '--init' right now) to
`--init` in the next iteration.

>> @@ -140,11 +146,14 @@ summary::
>>  	Show commit summary between the given commit (defaults to HEAD) and
>>  	working tree/index. For a submodule in question, a series of commits
>>  	in the submodule between the given super project commit and the
>> -	index or working tree (switched by --cached) are shown. If the option
>> -	--files is given, show the series of commits in the submodule between
>> +	index or working tree (switched by '--cached') are shown. If the option
>> +	'--files' is given, show the series of commits in the submodule between
>>  	the index of the super project and the working tree of the submodule
>> -	(this option doesn't allow to use the --cached option or to provide an
>> +	(this option doesn't allow to use the '--cached' option or to provide an
>>  	explicit commit).
>> ++
>> +Using the '--submodule=log' option with linkgit:git-diff[1] will provide the
>> +same information.
> 
> I am not a huge fan of these extra paragraphs, especially in reality it is
> not "provide the same" but "the same and a lot of other".
>
> I dunno.

I added them because in a discussion with Marc it became apparent that users
can't learn about what diff and status can do for them by checking the submodule
man-page. But you are right about "the same and a lot of other", I will update
the wording of those paragraphs.

Maybe someone else has a better idea how to inform users that git diff and
status can tell you a lot (and sometimes even more than the submodule script)
about the state submodules are in?