Re: [PATCH] Improve the "diff --git" format documentation

[Junio C Hamano <gitster@pobox.com>]

Andreas Gruenbacher <agruen@suse.de> writes:

>  The `a/` and `b/` filenames are the same unless rename/copy is
>  involved.  Especially, even for a creation or a deletion,
> -`/dev/null` is _not_ used in place of `a/` or `b/` filenames.
> +`/dev/null` is _not_ used in place of the `a/` or `b/` filenames
> +for nonexisting files (unlike in the unified diff headers).

The description in the parentheses is wrong, unless you qualify whose
"unified diff headers" you are talking about.  For example:

 http://www.opengroup.org/onlinepubs/9699919799/utilities/diff.html#tag_20_34_10_07

does not mention anything about file creation/deletion events.  Perhaps
you are referring to cvs or svn output, but I think we can safely drop the
parenthesized part without losing clarity.

> @@ -37,18 +37,42 @@ the file that rename/copy produces, respectively.
>         similarity index <number>
>         dissimilarity index <number>
>         index <hash>..<hash> <mode>
> -
> -3.  TAB, LF, double quote and backslash characters in pathnames
> -    are represented as `\t`, `\n`, `\"` and `\\`, respectively.
> -    If there is need for such substitution then the whole
> -    pathname is put in double quotes.
> -
> ++
> +File modes are printed as 6-digit octal numbers including the file type
> +and file permission bits.
> ++
> +Path names in extended headers do not include the `a/` and `b/` prefixes.
> ++
>  The similarity index is the percentage of unchanged lines, and
>  the dissimilarity index is the percentage of changed lines.  It
>  is a rounded down integer, followed by a percent sign.  The
>  similarity index value of 100% is thus reserved for two equal
>  files, while 100% dissimilarity means that no line from the old
>  file made it into the new one.
> ++
> +The index line includes the SHA-1 checksum before and after the change.
> +The <mode> is included if the file mode does not change; otherwise,
> +separate lines indicate the old and the new mode.
> +
> +3.  TAB, LF, double quote and backslash characters in pathnames
> +    are represented as `\t`, `\n`, `\"` and `\\`, respectively.
> +    If there is need for such substitution then the whole
> +    pathname is put in double quotes.
> ++
> +Space characters in pathnames are _not_ quoted, neither in the "git
> +diff" header nor in extended header lines.

I am not sure if there is a particular need to spend an extra paragraph to
special case the SP [*1*].  On the other hand, we quote bytes with
high-bit set in \octal [*2*], unless core.quotepath is set to false, too,
which should probably be described here.


[References]

*1* 28fba29 (Do not quote SP., 2005-10-17)
*2* http://marc.info/?l=git&m=112927316408690&w=2