[PATCH 1/2] Documentation/diff-options: fix typo in --submodule text

[PATCH 1/2] Documentation/diff-options: fix typo in --submodule text

[Tim Henigan]

Signed-off-by: Tim Henigan <tim.henigan@gmail.com>
---

Resent due to typo in developer list email address.

 Documentation/diff-options.txt |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 7d4566f..f44f3fc 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -165,7 +165,7 @@ any of those replacements occurred.
 	of the `--diff-filter` option on what the status letters mean.
 
 --submodule[=<format>]::
-	Chose the output format for submodule differences. <format> can be one of
+	Choose the output format for submodule differences. <format> can be one of
 	'short' and 'log'. 'short' just shows pairs of commit names, this format
 	is used when this option is not given. 'log' is the default value for this
 	option and lists the commits in that commit range like the 'summary'
-- 
1.7.10.rc0

[PATCH 2/2] Documentation/diff-options: reword description of --submodule option

[Tim Henigan]

The previous description was a bit confusing.  This rewrite makes it
easier to understand.

It should be noted that even though 'log' is listed as the default
format, it is not used when the '--submodule' option is missing. This
means that the output of:
   'git diff'             matches 'git diff --submodule=short'
   'git diff --submodule' matches 'git diff --submodule=log'

Signed-off-by: Tim Henigan <tim.henigan@gmail.com>
---

Resent due to a typo in the developer list email address.

I will understand if this change is rejected, but I found the current
description difficult to follow the first couple times I read it.

 Documentation/diff-options.txt |    9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index f44f3fc..0e1c753 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -165,11 +165,10 @@ any of those replacements occurred.
 	of the `--diff-filter` option on what the status letters mean.
 
 --submodule[=<format>]::
-	Choose the output format for submodule differences. <format> can be one of
-	'short' and 'log'. 'short' just shows pairs of commit names, this format
-	is used when this option is not given. 'log' is the default value for this
-	option and lists the commits in that commit range like the 'summary'
-	option of linkgit:git-submodule[1] does.
+	Choose the output format for submodule differences. <format> can be one
+	of 'short' or 'log'. The default value is 'log'.
+	'log' lists commits in the commit range like linkgit:git-submodule[1] `--summary`.
+	'short' shows only the SHA1 of the source and destination.
 
 --color[=<when>]::
 	Show colored diff.
-- 
1.7.10.rc0

Re: [PATCH 2/2] Documentation/diff-options: reword description of --submodule option

[Junio C Hamano]

Tim Henigan <tim.henigan@gmail.com> writes:

> The previous description was a bit confusing.  This rewrite makes it
> easier to understand.

I can understand the confusion.  We are trying to say too many things at
the same time:

 * There are two formats, log and short.

 * The log format is like "git submodule --summary A..B" for the range.

 * The short format just shows A and B for the range.

 * The log format is obtained by giving --submodule or --submodule=log.

 * The short format is obtained by not giving this option at all, or
   giving --submodule=short.

> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index f44f3fc..0e1c753 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -165,11 +165,10 @@ any of those replacements occurred.
>  	of the `--diff-filter` option on what the status letters mean.
>  
>  --submodule[=<format>]::
> -	Choose the output format for submodule differences. <format> can be one of
> -	'short' and 'log'. 'short' just shows pairs of commit names, this format
> -	is used when this option is not given. 'log' is the default value for this
> -	option and lists the commits in that commit range like the 'summary'
> -	option of linkgit:git-submodule[1] does.
> +	Choose the output format for submodule differences. <format> can be one
> +	of 'short' or 'log'. The default value is 'log'.
> +	'log' lists commits in the commit range like linkgit:git-submodule[1] `--summary`.
> +	'short' shows only the SHA1 of the source and destination.

Does it risk being unclear to say src/dst here without defining, or is it
sufficiently clear from the context (the previous line says "range")?

You lost "not giving this option at all is the same as --submodule=short".

Here is my attempt, but I do not think I particularly did a good job at
this.

        Specify how differences in submodules are shown.  A `--submodule`
        or `--submodule=log` option uses the long format, which lists the
        commits in the range like linkgit:git-submodule[1] `--summary` does.
	Omitting the `--submodule` option, or a `--submodule=short` option,
	uses the short format, which just shows the names of the commits
	at the beginning and the end of the range.

Re: [PATCH 2/2] Documentation/diff-options: reword description of --submodule option

[Tim Henigan]

>>  --submodule[=<format>]::
>> -     Choose the output format for submodule differences. <format> can be one of
>> -     'short' and 'log'. 'short' just shows pairs of commit names, this format
>> -     is used when this option is not given. 'log' is the default value for this
>> -     option and lists the commits in that commit range like the 'summary'
>> -     option of linkgit:git-submodule[1] does.
>> +     Choose the output format for submodule differences. <format> can be one
>> +     of 'short' or 'log'. The default value is 'log'.
>> +     'log' lists commits in the commit range like linkgit:git-submodule[1] `--summary`.
>> +     'short' shows only the SHA1 of the source and destination.
>
> Does it risk being unclear to say src/dst here without defining, or is it
> sufficiently clear from the context (the previous line says "range")?

I chose those words based on descriptions in some of the other diff
options (see `changes` and --src-prefix in the same file.  That being
said, the description you gave is more clear.


> You lost "not giving this option at all is the same as --submodule=short".

I removed that part on purpose.  I wasn't sure that it needs to be
documented here since it is about how the 'diff' command normally
behaves rather than about the '--submodule' option itself.


> Here is my attempt, but I do not think I particularly did a good job at
> this.
>
>        Specify how differences in submodules are shown.  A `--submodule`
>        or `--submodule=log` option uses the long format, which lists the
>        commits in the range like linkgit:git-submodule[1] `--summary` does.
>        Omitting the `--submodule` option, or a `--submodule=short` option,
>        uses the short format, which just shows the names of the commits
>        at the beginning and the end of the range.

Some further minor changes to your version:

    Specify how differences in submodules are shown.  When `--submodule`
    or `--submodule=log` is given, the 'log' format is used.  This format lists
    the commits in the range like linkgit:git-submodule[1] `--summary` does.
    Omitting the `--submodule` option or specifying `--submodule=short`,
    uses the 'short' format. This format just shows the names of the commits
    at the beginning and end of the range.

Re: [PATCH 2/2] Documentation/diff-options: reword description of --submodule option

[Jens Lehmann]

Am 13.03.2012 21:36, schrieb Tim Henigan:
> Some further minor changes to your version:
> 
>     Specify how differences in submodules are shown.  When `--submodule`
>     or `--submodule=log` is given, the 'log' format is used.  This format lists
>     the commits in the range like linkgit:git-submodule[1] `--summary` does.

Nit:
      the commits in the range like linkgit:git-submodule[1] `summary` does.

(`summary` is a command of "git submodule", not an option)

>     Omitting the `--submodule` option or specifying `--submodule=short`,
>     uses the 'short' format. This format just shows the names of the commits
>     at the beginning and end of the range.

But apart from that I really like it.