Subject: Re: [PATCH] Documentation/log: clarify what --raw means

From: Junio C Hamano <[email-masked]>
Date: Fri, 15 May 2015 10:38:41 -0700

Matthieu Moy <[email-masked]> writes:

> There are several "raw formats", and describing --raw as "Generate the
> raw format" in the documentation for git-log seems to imply that it
> generates the raw *log* format.
>
> Clarify the wording by saying "raw diff format" explicitely, and make a
> special-case for "git log": "git log --raw" does not just change the
> format, it shows something which is not shown by default.

Being a pedant, I find "generate the raw diff format" somewhat a
strange wording.  Aren't we generating a diff in the raw format (as
opposed to in other format like the textual patch format),
generating a diff using the raw format, etc.?

In any case, this is an improvement.  Thanks.  Will queue.

> Signed-off-by: Matthieu Moy <[email-masked]>
> ---
>  Documentation/diff-options.txt | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index ccd4998..163163b 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -41,8 +41,17 @@ endif::git-format-patch[]
>  
>  ifndef::git-format-patch[]
>  --raw::
> -	Generate the raw format.
> +ifndef::git-log[]
> +	Generate the raw diff format.
>  	{git-diff-core? This is the default.}
> +endif::git-log[]
> +ifdef::git-log[]
> +	For each commit, show a summary of changes using the raw diff
> +	format. See the "RAW OUTPUT FORMAT" section of
> +	linkgit:git-diff[1]. This is different from showing the log
> +	itself in raw format, which you can achieve with
> +	`--format=raw`.
> +endif::git-log[]
>  endif::git-format-patch[]
>  
>  ifndef::git-format-patch[]