Re: [PATCH 4/4] Documentation/git-commit.txt: correct a few minor grammatical mistakes

From: Brandon Casey <drafnel@gmail.com>
Date: Feb 19, 2013, 07:18 UTC
Message-ID: <CA+sFfMf8juf0rQh6S2sW=_LmsbhPc=c+erVppsZbAw-+h-4CqQ@mail.gmail.com>
In-Reply-To: <20130219064304.GG19757@elie.Belkin>

On Mon, Feb 18, 2013 at 10:43 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:

Show 20 quoted lines

> Brandon Casey wrote:
>
>> --- a/Documentation/git-commit.txt
>> +++ b/Documentation/git-commit.txt
>> @@ -174,10 +174,10 @@ OPTIONS
>>  --cleanup=<mode>::
>>       This option sets how the commit message is cleaned up.
>>       The  '<mode>' can be one of 'verbatim', 'whitespace', 'strip',
>> -     and 'default'. The 'default' mode will strip leading and
>> +     or 'default'. The 'default' mode will strip leading and
>>       trailing empty lines and #commentary from the commit message
>> -     only if the message is to be edited. Otherwise only whitespace
>> -     removed. The 'verbatim' mode does not change message at all,
>> +     only if the message is to be edited. Otherwise only whitespace is
>> +     removed. The 'verbatim' mode does not change the message at all,
>>       'whitespace' removes just leading/trailing whitespace lines
>>       and 'strip' removes both whitespace and commentary. The default
>>       can be changed by the 'commit.cleanup' configuration variable
>
> Yeah, the current text is a bit choppy.  How about this?

Hmm, I think the original text was more confusing than I realized. I think we should reorder the cleanup modes, placing "default" last, and then describe default in terms of either strip or whitespace depending on whether an editor will be spawned.

Show 33 quoted lines

> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
>
> --- i/Documentation/git-commit.txt
> +++ w/Documentation/git-commit.txt
> @@ -172,16 +172,25 @@ OPTIONS
>         linkgit:git-commit-tree[1].
>
>  --cleanup=<mode>::
> -       This option sets how the commit message is cleaned up.
> -       The  '<mode>' can be one of 'verbatim', 'whitespace', 'strip',
> -       and 'default'. The 'default' mode will strip leading and
> -       trailing empty lines and #commentary from the commit message
> -       only if the message is to be edited. Otherwise only whitespace
> -       removed. The 'verbatim' mode does not change message at all,
> -       'whitespace' removes just leading/trailing whitespace lines
> -       and 'strip' removes both whitespace and commentary. The default
> -       can be changed by the 'commit.cleanup' configuration variable
> -       (see linkgit:git-config[1]).
> +       This option determines how the supplied commit message should be
> +       cleaned up before committing. The '<mode>' can be `verbatim`,
> +       `whitespace`, `strip`, or `default`.
> ++
> +--
> +default::
> +       Strip leading and trailing empty lines and #commentary from
> +       the commit message only if the message is to be edited.
> +       Otherwise only remove whitespace.
> +verbatim::
> +       Do not change the message at all.
> +whitespace::
> +       Remove only leading and trailing whitespace lines.
> +strip::
> +       Remove both whitespace and commentary.

Let's reorder these.  Maybe something like this:

+strip::
+       Strip leading and trailing empty lines, trailing whitespace
and #commentary and
+       collapse consecutive blank lines into one.
+whitespace::
+       Same as "strip" except #commentary is not removed.
+verbatim::
+       Do not change the message at all.
+default::
+       "strip" if the message is to be edited.  Otherwise "whitespace".

Show 7 quoted lines

> +--
> ++
> +The default can be changed using the 'commit.cleanup' configuration
> +variable (see linkgit:git-config[1]).
>
>  -e::
>  --edit::

-Brandon