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

Jens Lehmann [off-list ref] writes:

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

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.

Am 25.07.2011 22:30, schrieb Junio C Hamano:

Jens Lehmann [off-list ref] writes:

quoted

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

quoted

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

On 11-07-26 02:44 PM, Jens Lehmann wrote:

Am 25.07.2011 22:30, schrieb Junio C Hamano:

quoted

Jens Lehmann [off-list ref] writes:

quoted

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