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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 13, 2012, 20:04 UTC
Message-ID: <7vipi8uv12.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1331665251-11147-2-git-send-email-tim.henigan@gmail.com>

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.