threads / patch / 29943

patch, 2 partsDocumentation/diff-options: fix typo in --submodule text

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

## tl;dr

5 messages between Mar 13, 2012 and Mar 14, 2012. Diffs are folded; open one to read it.

replies: 4people: 3as markdown or json

Tim Henigan· Mar 13, 2012, 19:00 UTC · lore
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(-)
Show changes to Documentation/diff-options.txt +1 −1
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
Tim Henigan· Mar 13, 2012, 19:00 UTC · re: Tim Henigan · lore

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

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(-)
Show changes to Documentation/diff-options.txt +4 −5
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
Junio C Hamano· Mar 13, 2012, 20:04 UTC · re: Tim Henigan · lore

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

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.
Show 17 quoted lines
> 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.
Tim Henigan· Mar 13, 2012, 20:36 UTC · re: Junio C Hamano · lore

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

Show 13 quoted lines
>>  --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.

Show 9 quoted lines
> 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.
Jens Lehmann· Mar 14, 2012, 18:47 UTC · re: Tim Henigan · lore

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

Am 13.03.2012 21:36, schrieb Tim Henigan:
Show 5 quoted lines
> 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.

← back to recent threads