[PATCH 1/4] apply: Clarify the description of -z

[PATCH 1/4] apply: Clarify the description of -z

[Björn Gustavsson]

The description of -z says that a machine-readable format will be
used "when showing the index information". From that description,
it is not at all clear which other option it will modify the
behaviour of. Explicitly state that -z modifies the behavior
of --numstat.

Also correct the description of the "munging" that takes places
in the absence of -z, namely that apart from the characters
mentioned, double quotes are also 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>
---
 Documentation/git-apply.txt |   12 +++++++-----
 1 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 5ee8c91..4f791ee 100644
--- 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 flag, 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
-- 
1.6.5.3.298.g39add

Re: [PATCH 1/4] apply: Clarify the description of -z

[Junio C Hamano]

Björn Gustavsson <bgustavsson@gmail.com> writes:

> The description of -z says that a machine-readable format will be
> used "when showing the index information". From that description,
> it is not at all clear which other option it will modify the
> behaviour of. Explicitly state that -z modifies the behavior
> of --numstat.
>
> Also correct the description of the "munging" that takes places
> in the absence of -z, namely that apart from the characters
> mentioned, double quotes are also 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>
> ---
>  Documentation/git-apply.txt |   12 +++++++-----
>  1 files changed, 7 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
> index 5ee8c91..4f791ee 100644
> --- 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.

I think diff-format.txt has the same description; could you please update
that to be in sync?