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

From: Marc Branchaud <[email-masked]>
Date: Tue, 26 Jul 2011 14:54:03 -0400

On 11-07-26 02:44 PM, Jens Lehmann wrote:
> Am 25.07.2011 22:30, schrieb Junio C Hamano:
>> Jens Lehmann <[email-masked]> writes:
>>
>>> @@ -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?

I thought the brief sentence in the patch was fine, myself.

		M.