Clarify and correct -z

The description for -z is too vague and general for the
apply, diff*, and log commands.

Change the description of -z for 'git log' to note that
commits will be separated by NULs.

Change the description of -z for 'git diff*' and 'git apply'
to note that it applies to the --numstat option, and for
'git diff*' also for --raw option.

Also correct the description of the "munging" of pathanmes that
takes place in the absence of -z for the 'git diff*' and
'git apply' commands, namely that apart from the characters mentioned,
double quotes will also be escaped and that the pathname will be
enclosed in double quotes if any characters are escaped.

Signed-off-by: Björn Gustavsson <bgustavsson@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 2b37193a37da9715b0ae4b8aa47c85064694ef8e..18366b1be60a61beed16dd67fcab6151b4ecd55e 100644 (file)
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -85,10 +85,21 @@ ifndef::git-format-patch[]
 endif::git-format-patch[]
 
 ifndef::git-format-patch[]
+
 -z::
-       NUL-line termination on output.  This affects the `--raw`
-       output field terminator.  Also output from commands such
-       as `git-log` will be delimited with NUL between commits.
+ifndef::git-log[]
+       When `--raw` or `--numstat` has been given, do not munge
+       pathnames and use NULs as output field terminators.
++
+Without this option, each pathname output will have TAB, LF, double quotes,
+and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`,
+respectively, and the pathname will be enclosed in double quotes if
+any of those replacements occurred.
+endif::git-log[]
+
+ifdef::git-log[]
+       Separate the commits with NULs instead of with new newlines.
+endif::git-log[]
 
 --name-only::
        Show only names of changed files.

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 5ee8c91f2d0a376bf755f0802825ae184cea2a28..0156ca9112255d50f94680f6b72b1e8395f37b3e 100644 (file)
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -87,11 +87,13 @@ the information is read from the current index instead.
        rejected hunks in corresponding *.rej files.
 
 -z::
-       When showing the index information, do not munge paths,
-       but use NUL terminated machine readable format.  Without
-       this flag, the pathnames output will have TAB, LF, and
-       backslash characters replaced with `\t`, `\n`, and `\\`,
-       respectively.
+       When `--numstat` has been given, do not munge pathnames,
+       but use a NUL-terminated machine-readable format.
++
+Without this option, each pathname output will have TAB, LF, double quotes,
+and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`,
+respectively, and the pathname will be enclosed in double quotes if
+any of those replacements occurred.
 
 -p<n>::
        Remove <n> leading slashes from traditional diff paths. The