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

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

[Jens Lehmann]

Reference the "git diff" and "git status" commands where they learned
functionality that in earlier git versions was only available through the
'summary' and 'status' subcommands of "git submodule".

The short option '-n' for '--summary-limit' was missing from the synopsis
and the --init option was missing from the "options" section, add those
there. And while at it, quote all options so they are decorated properly
in the output formats which support that.

Signed-off-by: Jens Lehmann <Jens.Lehmann@web.de>
---

This patch addresses some issues with the current documentation which were
brought up on the list.

 Documentation/git-submodule.txt |   30 ++++++++++++++++++++++--------
 1 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 0ec8574..e749aa5 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -15,7 +15,8 @@ SYNOPSIS
 'git submodule' [--quiet] init [--] [<path>...]
 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase]
 	      [--reference <repository>] [--merge] [--recursive] [--] [<path>...]
-'git submodule' [--quiet] summary [--cached|--files] [--summary-limit <n>] [commit] [--] [<path>...]
+'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>]
+	      [commit] [--] [<path>...]
 'git submodule' [--quiet] foreach [--recursive] <command>
 'git submodule' [--quiet] sync [--] [<path>...]

@@ -110,6 +111,11 @@ status::
 +
 If '--recursive' is specified, this command will recurse into nested
 submodules, and show their status as well.
++
+If you are only interested in changes of the currently initialized
+submodules with respect to the commit recorded in the index or the HEAD,
+linkgit:git-status[1] and linkgit:git-diff[1] will provide that information
+too (and can also report changes to a submodule's work tree).

 init::
 	Initialize the submodules, i.e. register each submodule name
@@ -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.
 +
 If '--recursive' is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
@@ -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.

 foreach::
 	Evaluates an arbitrary shell command in each checked out submodule.
@@ -155,9 +164,9 @@ foreach::
 	superproject, $sha1 is the commit as recorded in the superproject,
 	and $toplevel is the absolute path to the top-level of the superproject.
 	Any submodules defined in the superproject but not checked out are
-	ignored by this command. Unless given --quiet, foreach prints the name
+	ignored by this command. Unless given '--quiet', foreach prints the name
 	of each submodule before evaluating the command.
-	If --recursive is given, submodules are traversed recursively (i.e.
+	If '--recursive' is given, submodules are traversed recursively (i.e.
 	the given shell command is evaluated in nested submodules as well).
 	A non-zero return from the command in any submodule causes
 	the processing to terminate. This can be overridden by adding '|| :'
@@ -237,13 +246,18 @@ OPTIONS
 	If the key `submodule.$name.update` is set to `rebase`, this option is
 	implicit.

+--init::
+	This option is only valid for the update command.
+	Initialize all submodules for which "git submodule init" has not been
+	called so far before updating.
+
 --reference <repository>::
 	This option is only valid for add and update commands.  These
 	commands sometimes need to clone a remote repository. In this case,
 	this option will be passed to the linkgit:git-clone[1] command.
 +
 *NOTE*: Do *not* use this option unless you have read the note
-for linkgit:git-clone[1]'s --reference and --shared options carefully.
+for linkgit:git-clone[1]'s '--reference' and '--shared' options carefully.

 --recursive::
 	This option is only valid for foreach, update and status commands.
-- 
1.7.6.356.g65c4e

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

[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

> @@ -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.

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

[Jens Lehmann]

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?

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

[Marc Branchaud]

On 11-07-26 02:44 PM, Jens Lehmann wrote:
> Am 25.07.2011 22:30, schrieb Junio C Hamano:
>> Jens Lehmann <Jens.Lehmann@web.de> 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.