[PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Andreas Heiduk]

Add a hint for script writers where additional quoting can be configured.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-ls-files.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 446209e..19e0636 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -198,7 +198,8 @@ path. (see linkgit:git-read-tree[1] for more information on state)
 
 When `-z` option is not used, TAB, LF, and backslash characters
 in pathnames are represented as `\t`, `\n`, and `\\`,
-respectively.
+respectively. The path is also quoted according to the
+configuration variable `core.quotePath` (see linkgit:git-config[1]).
 
 
 Exclude Patterns
-- 
2.7.4

Re: [PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> Add a hint for script writers where additional quoting can be configured.
>
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/git-ls-files.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index 446209e..19e0636 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -198,7 +198,8 @@ path. (see linkgit:git-read-tree[1] for more information on state)
>  
>  When `-z` option is not used, TAB, LF, and backslash characters
>  in pathnames are represented as `\t`, `\n`, and `\\`,
> -respectively.
> +respectively. The path is also quoted according to the
> +configuration variable `core.quotePath` (see linkgit:git-config[1]).

I was waiting for others to comment on this patch but nobody seems
to be interested.  Which is a bit sad, as this may not be a bad
idea.

If we refer to core.quotePath, the mention of control characters
being quoted can also be omitted, I think, as that is part of what
appears in the description of core.quotePath variable.

Alternatively, instead of referring to another page, we can spend
the additional lines to say what is more interesting to most of the
readers from that page, e.g.

    When `-z` option is not used, a pathname with "unusual" characters
    in it is quoted by enclosing it in a double-quote pair and with
    backslashes the same way strings in C source code are quoted.  By
    setting core.quotePath configuration to false, the bytes whose
    values are higher than 0x80 are output verbatim.

Re: [PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Andreas Heiduk]

Am 21.02.2017 um 21:48 schrieb Junio C Hamano:
> 
> I was waiting for others to comment on this patch but nobody seems
> to be interested.  Which is a bit sad, as this may not be a bad
> idea.
> 
> If we refer to core.quotePath, the mention of control characters
> being quoted can also be omitted, I think, as that is part of what
> appears in the description of core.quotePath variable.
> 
> Alternatively, instead of referring to another page, we can spend
> the additional lines to say what is more interesting to most of the
> readers from that page, e.g.
> 
>     When `-z` option is not used, a pathname with "unusual" characters
>     in it is quoted by enclosing it in a double-quote pair and with
>     backslashes the same way strings in C source code are quoted.  By
>     setting core.quotePath configuration to false, the bytes whose
>     values are higher than 0x80 are output verbatim.
>

Without `-z` but with core.quotePath=false the path may still be
surrounded with double-quotes if it contains control characters (and
some more). The documentation in `core.quotePath` mentions this, your
"inline" alternative does not.

I will send second patch. :-)

Re: [PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Andreas Heiduk]

[PATCH] Documentation: Clarify core.quotePath, remove cruft in
 git-ls-files.

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---

I have merged the best parts about quoting into the core.quotePath
description and cleaned up the text in git-ls-files.txt regarding the
control characters.


 Documentation/config.txt       | 22 ++++++++++++----------
 Documentation/git-ls-files.txt | 11 ++++++-----
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index f4721a0..25e65ae 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -340,16 +340,18 @@ core.checkStat::
 	all fields, including the sub-second part of mtime and ctime.

 core.quotePath::
-	The commands that output paths (e.g. 'ls-files',
-	'diff'), when not given the `-z` option, will quote
-	"unusual" characters in the pathname by enclosing the
-	pathname in a double-quote pair and with backslashes the
-	same way strings in C source code are quoted.  If this
-	variable is set to false, the bytes higher than 0x80 are
-	not quoted but output as verbatim.  Note that double
-	quote, backslash and control characters are always
-	quoted without `-z` regardless of the setting of this
-	variable.
+	Commands that output paths (e.g. 'ls-files', 'diff'), will
+	quote "unusual" characters in the pathname by enclosing the
+	pathname in double-quotes and escaping those characters with
+	backslashes in the same way C escapes control characters (e.g.
+	`\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
+	values larger than 0x80 (e.g. octal `\265` for "micro").  If
+	this variable is set to false, bytes higher than 0x80 are not
+	considered "unusual" any more.  Double-quotes, backslash and
+	control characters are always escaped regardless of the
+	setting of this variable.  Many commands can output pathnames
+	completely verbatim using the `-z` option. The default value is
+	true.

 core.eol::
 	Sets the line ending type to use in the working directory for
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index d2b17f2..88df561 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -76,7 +76,8 @@ OPTIONS
 	succeed.

 -z::
-	\0 line termination on output.
+	\0 line termination on output and do not quote filenames.
+	See OUTPUT below for more information.

 -x <pattern>::
 --exclude=<pattern>::
@@ -192,10 +193,10 @@ the index records up to three such pairs; one from
tree O in stage
 the user (or the porcelain) to see what should eventually be recorded
at the
 path. (see linkgit:git-read-tree[1] for more information on state)

-When `-z` option is not used, TAB, LF, and backslash characters
-in pathnames are represented as `\t`, `\n`, and `\\`,
-respectively. The path is also quoted according to the
-configuration variable `core.quotePath` (see linkgit:git-config[1]).
+Without the `-z` option pathnamens with "unusual" characters are
+quoted as explained for the configuration variable `core.quotePath`
+(see linkgit:git-config[1]).  Using `-z` the filename is output
+verbatim and the line is terminated by a NUL byte.


 Exclude Patterns
-- 
2.7.4

Re: [PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Philip Oakley]

From: "Andreas Heiduk" <asheiduk@gmail.com>
> [PATCH] Documentation: Clarify core.quotePath, remove cruft in
> git-ls-files.
>
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>
> I have merged the best parts about quoting into the core.quotePath
> description and cleaned up the text in git-ls-files.txt regarding the
> control characters.
>
>
> Documentation/config.txt       | 22 ++++++++++++----------
> Documentation/git-ls-files.txt | 11 ++++++-----
> 2 files changed, 18 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index f4721a0..25e65ae 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -340,16 +340,18 @@ core.checkStat::
>  all fields, including the sub-second part of mtime and ctime.
>
> core.quotePath::
> - The commands that output paths (e.g. 'ls-files',
> - 'diff'), when not given the `-z` option, will quote
> - "unusual" characters in the pathname by enclosing the
> - pathname in a double-quote pair and with backslashes the
> - same way strings in C source code are quoted.  If this
> - variable is set to false, the bytes higher than 0x80 are
> - not quoted but output as verbatim.  Note that double
> - quote, backslash and control characters are always
> - quoted without `-z` regardless of the setting of this
> - variable.
> + Commands that output paths (e.g. 'ls-files', 'diff'), will
> + quote "unusual" characters in the pathname by enclosing the
> + pathname in double-quotes and escaping those characters with
> + backslashes in the same way C escapes control characters (e.g.
> + `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
> + values larger than 0x80 (e.g. octal `\265` for "micro").  If
> + this variable is set to false, bytes higher than 0x80 are not
> + considered "unusual" any more.  Double-quotes, backslash and
> + control characters are always escaped regardless of the
> + setting of this variable.  Many commands can output pathnames
> + completely verbatim using the `-z` option. The default value is
> + true.
>
> core.eol::
>  Sets the line ending type to use in the working directory for
> diff --git a/Documentation/git-ls-files.txt 
> b/Documentation/git-ls-files.txt
> index d2b17f2..88df561 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -76,7 +76,8 @@ OPTIONS
>  succeed.
>
> -z::
> - \0 line termination on output.
> + \0 line termination on output and do not quote filenames.
> + See OUTPUT below for more information.
>
> -x <pattern>::
> --exclude=<pattern>::
> @@ -192,10 +193,10 @@ the index records up to three such pairs; one from
> tree O in stage
> the user (or the porcelain) to see what should eventually be recorded
> at the
> path. (see linkgit:git-read-tree[1] for more information on state)
>
> -When `-z` option is not used, TAB, LF, and backslash characters
> -in pathnames are represented as `\t`, `\n`, and `\\`,
> -respectively. The path is also quoted according to the
> -configuration variable `core.quotePath` (see linkgit:git-config[1]).
> +Without the `-z` option pathnamens with "unusual" characters are

s/option pathnamens/option, pathnames/    # comma and spelling.

> +quoted as explained for the configuration variable `core.quotePath`
> +(see linkgit:git-config[1]).  Using `-z` the filename is output
> +verbatim and the line is terminated by a NUL byte.
>
--
Philip 

Re: [PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

>> -When `-z` option is not used, TAB, LF, and backslash characters
>> -in pathnames are represented as `\t`, `\n`, and `\\`,
>> -respectively. The path is also quoted according to the
>> -configuration variable `core.quotePath` (see linkgit:git-config[1]).
>> +Without the `-z` option pathnamens with "unusual" characters are
>
> s/option pathnamens/option, pathnames/    # comma and spelling.

Thanks.  Will squash it in while queuing (I need to discard the new
text added in the previous attempt in the preimage to make it apply,
too).

-- >8 --
From: Andreas Heiduk <asheiduk@gmail.com>
Date: Wed, 22 Feb 2017 02:38:21 +0100
Subject: [PATCH] Documentation: clarify core.quotePath and update git-ls-files doc

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/config.txt       | 22 ++++++++++++----------
 Documentation/git-ls-files.txt | 10 ++++++----
 2 files changed, 18 insertions(+), 14 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index f4721a048b..25e65aeb01 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -340,16 +340,18 @@ core.checkStat::
 	all fields, including the sub-second part of mtime and ctime.
 
 core.quotePath::
-	The commands that output paths (e.g. 'ls-files',
-	'diff'), when not given the `-z` option, will quote
-	"unusual" characters in the pathname by enclosing the
-	pathname in a double-quote pair and with backslashes the
-	same way strings in C source code are quoted.  If this
-	variable is set to false, the bytes higher than 0x80 are
-	not quoted but output as verbatim.  Note that double
-	quote, backslash and control characters are always
-	quoted without `-z` regardless of the setting of this
-	variable.
+	Commands that output paths (e.g. 'ls-files', 'diff'), will
+	quote "unusual" characters in the pathname by enclosing the
+	pathname in double-quotes and escaping those characters with
+	backslashes in the same way C escapes control characters (e.g.
+	`\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
+	values larger than 0x80 (e.g. octal `\265` for "micro").  If
+	this variable is set to false, bytes higher than 0x80 are not
+	considered "unusual" any more.  Double-quotes, backslash and
+	control characters are always escaped regardless of the
+	setting of this variable.  Many commands can output pathnames
+	completely verbatim using the `-z` option. The default value is
+	true.
 
 core.eol::
 	Sets the line ending type to use in the working directory for
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 078b556665..a415223b45 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -76,7 +76,8 @@ OPTIONS
 	succeed.
 
 -z::
-	\0 line termination on output.
+	\0 line termination on output and do not quote filenames.
+	See OUTPUT below for more information.
 
 -x <pattern>::
 --exclude=<pattern>::
@@ -192,9 +193,10 @@ the index records up to three such pairs; one from tree O in stage
 the user (or the porcelain) to see what should eventually be recorded at the
 path. (see linkgit:git-read-tree[1] for more information on state)
 
-When `-z` option is not used, TAB, LF, and backslash characters
-in pathnames are represented as `\t`, `\n`, and `\\`,
-respectively.
+Without the `-z` option, pathnames with "unusual" characters are
+quoted as explained for the configuration variable `core.quotePath`
+(see linkgit:git-config[1]).  Using `-z` the filename is output
+verbatim and the line is terminated by a NUL byte.
 
 
 Exclude Patterns
-- 
2.12.0-rc2-250-gd33575c7f2

Re: [PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Andreas Heiduk]

@Phillip: Thanks.

@Junio: Don't bother, I'm about to fix other man-pages with the text
from ls-files. I will include that typo-fix and prepare a new patch
based on maint.


Am 22.02.2017 um 22:02 schrieb Junio C Hamano:
> "Philip Oakley" <philipoakley@iee.org> writes:
>> s/option pathnamens/option, pathnames/    # comma and spelling.
> 
> Thanks.  Will squash it in while queuing (I need to discard the new
> text added in the previous attempt in the preimage to make it apply,
> too).
>

[PATCH v2 0/2] Documentation: Link git-ls-files to core.quotePath variable.

[Andreas Heiduk]

These two patches replace and extend the precious patches with the
same subject. Suggestions from Philip Oakley and Junio C Hamano are
included.

I tried to find and adjust all places where pathname quoting and "-z"
were described. I omitted these places:

* Here "-z" is for input only. Quoting is unclear to me.

-- git-mktree.txt
-- git-update-index.txt
-- git-checkout-index.txt

* Here pathname quoting is not mentioned:

-- git-check-ignore.txt
-- git-check-attr.txt

And last but not least: 

- git-grep.txt: The paths are always unquoted, `-z` toggles only the
delimiter. Perhaps some CAVEAT should be added.


Andreas Heiduk (2):
  Documentation: Improve description for core.quotePath
  Documentation: Link descriptions of -z to core.quotePath

 Documentation/config.txt              | 24 ++++++++++++++----------
 Documentation/diff-format.txt         |  7 ++++---
 Documentation/diff-generate-patch.txt |  7 +++----
 Documentation/diff-options.txt        |  7 +++----
 Documentation/git-apply.txt           |  7 +++----
 Documentation/git-commit.txt          |  9 ++++++---
 Documentation/git-ls-files.txt        | 10 ++++++----
 Documentation/git-ls-tree.txt         | 10 +++++++---
 Documentation/git-status.txt          |  7 +++----
 9 files changed, 49 insertions(+), 39 deletions(-)

[PATCH v2 1/2] Documentation: Improve description for core.quotePath

[Andreas Heiduk]

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/config.txt | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 1fee83c..fa06c2a 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -347,16 +347,20 @@ core.checkStat::
 	all fields, including the sub-second part of mtime and ctime.
 
 core.quotePath::
-	The commands that output paths (e.g. 'ls-files',
-	'diff'), when not given the `-z` option, will quote
-	"unusual" characters in the pathname by enclosing the
-	pathname in a double-quote pair and with backslashes the
-	same way strings in C source code are quoted.  If this
-	variable is set to false, the bytes higher than 0x80 are
-	not quoted but output as verbatim.  Note that double
-	quote, backslash and control characters are always
-	quoted without `-z` regardless of the setting of this
-	variable.
+
+	Commands that output paths (e.g. 'ls-files', 'diff'), will
+	quote "unusual" characters in the pathname by enclosing the
+	pathname in double-quotes and escaping those characters with
+	backslashes in the same way C escapes control characters (e.g.
+	`\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
+	values larger than 0x80 (e.g. octal `\302\265` for "micro" in
+	UTF-8).  If this variable is set to false, bytes higher than
+	0x80 are not considered "unusual" any more. Double-quotes,
+	backslash and control characters are always escaped regardless
+	of the setting of this variable.  A simple space character is
+	not considered "unusual".  Many commands can output pathnames
+	completely verbatim using the `-z` option. The default value
+	is true.
 
 core.eol::
 	Sets the line ending type to use in the working directory for

Re: [PATCH v2 1/2] Documentation: Improve description for core.quotePath

[Jakub Narębski]

W dniu 24.02.2017 o 21:37, Andreas Heiduk pisze:
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>

Thanks.  This is good work.

> ---
>  Documentation/config.txt | 24 ++++++++++++++----------
>  1 file changed, 14 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 1fee83c..fa06c2a 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -347,16 +347,20 @@ core.checkStat::
>  	all fields, including the sub-second part of mtime and ctime.
>  
>  core.quotePath::
> -	The commands that output paths (e.g. 'ls-files',
> -	'diff'), when not given the `-z` option, will quote
> -	"unusual" characters in the pathname by enclosing the
> -	pathname in a double-quote pair and with backslashes the
> -	same way strings in C source code are quoted.  If this
> -	variable is set to false, the bytes higher than 0x80 are
> -	not quoted but output as verbatim.  Note that double
> -	quote, backslash and control characters are always
> -	quoted without `-z` regardless of the setting of this
> -	variable.
> +

This empty line should not be here, I think.

> +	Commands that output paths (e.g. 'ls-files', 'diff'), will
> +	quote "unusual" characters in the pathname by enclosing the
> +	pathname in double-quotes and escaping those characters with
> +	backslashes in the same way C escapes control characters (e.g.
> +	`\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
> +	values larger than 0x80 (e.g. octal `\302\265` for "micro" in

I wonder if we can put UTF-8 in AsciiDoc, that is write "μ"
instead of spelling it "micro" (or: Greek letter "mu").

Or "&micro;" / "&#181;", though I wonder how well it is supported
in manpage, info and PDF outputs...

> +	UTF-8).  If this variable is set to false, bytes higher than
> +	0x80 are not considered "unusual" any more. Double-quotes,
> +	backslash and control characters are always escaped regardless
> +	of the setting of this variable.  A simple space character is
> +	not considered "unusual".  Many commands can output pathnames
> +	completely verbatim using the `-z` option. The default value
> +	is true.
>  
>  core.eol::
>  	Sets the line ending type to use in the working directory for
> 

Re: [PATCH v2 1/2] Documentation: Improve description for core.quotePath

[Andreas Heiduk]

Am 24.02.2017 um 22:43 schrieb Jakub Narębski:
> W dniu 24.02.2017 o 21:37, Andreas Heiduk pisze:
>> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> 
> Thanks.  This is good work.

:-)

> 
>> ---
>>  Documentation/config.txt | 24 ++++++++++++++----------
>>  1 file changed, 14 insertions(+), 10 deletions(-)
>>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
[...]
>> +
> 
> This empty line should not be here, I think.

Missed that bugger...

[...]
>> +	values larger than 0x80 (e.g. octal `\302\265` for "micro" in
> 
> I wonder if we can put UTF-8 in AsciiDoc, that is write "μ"
> instead of spelling it "micro" (or: Greek letter "mu").
> 
> Or "&micro;" / "&#181;", though I wonder how well it is supported
> in manpage, info and PDF outputs...

... and fonts installed on client machines!

Since I started with a two-line diff for just git-ls-files I decided to
play safe with this,

[PATCH v2 2/2] Documentation: Link descriptions of -z to core.quotePath

[Andreas Heiduk]

Linking the description for pathname quoting to the configuration
variable "core.quotePath" removes inconstistent and incomplete
sections while also giving two hints how to deal with it: Either with
"-c core.quotePath=false" or with "-z".

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/diff-format.txt         |  7 ++++---
 Documentation/diff-generate-patch.txt |  7 +++----
 Documentation/diff-options.txt        |  7 +++----
 Documentation/git-apply.txt           |  7 +++----
 Documentation/git-commit.txt          |  9 ++++++---
 Documentation/git-ls-files.txt        | 10 ++++++----
 Documentation/git-ls-tree.txt         | 10 +++++++---
 Documentation/git-status.txt          |  7 +++----
 8 files changed, 35 insertions(+), 29 deletions(-)

diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
index cf52626..706916c 100644
--- a/Documentation/diff-format.txt
+++ b/Documentation/diff-format.txt
@@ -78,9 +78,10 @@ Example:
 :100644 100644 5be4a4...... 000000...... M file.c
 ------------------------------------------------
 
-When `-z` option is not used, TAB, LF, and backslash characters
-in pathnames are represented as `\t`, `\n`, and `\\`,
-respectively.
+Without the `-z` option, pathnames with "unusual" characters are
+quoted as explained for the configuration variable `core.quotePath`
+(see linkgit:git-config[1]).  Using `-z` the filename is output
+verbatim and the line is terminated by a NUL byte.
 
 diff format for merges
 ----------------------
diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
index d2a7ff5..231105c 100644
--- a/Documentation/diff-generate-patch.txt
+++ b/Documentation/diff-generate-patch.txt
@@ -53,10 +53,9 @@ 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.
+3.  Pathnames with "unusual" characters are quoted as explained for
+    the configuration variable `core.quotePath` (see
+    linkgit:git-config[1]).
 
 4.  All the `file1` files in the output refer to files before the
     commit, and all the `file2` files refer to files after the commit.
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index e6215c3..7c28e73 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -192,10 +192,9 @@ ifndef::git-log[]
 	given, do not munge pathnames and use NULs as output field terminators.
 endif::git-log[]
 +
-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.
+Without this option, pathnames with "unusual" characters are munged as
+explained for the configuration variable `core.quotePath` (see
+linkgit:git-config[1]).
 
 --name-only::
 	Show only names of changed files.
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index 8ddb207..a7a001b 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -108,10 +108,9 @@ the information is read from the current index instead.
 	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.
+Without this option, pathnames with "unusual" characters are munged as
+explained for the configuration variable `core.quotePath` (see
+linkgit:git-config[1]).
 
 -p<n>::
 	Remove <n> leading slashes from traditional diff paths. The
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 4f8f20a..25dcdcc 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -117,9 +117,12 @@ OPTIONS
 
 -z::
 --null::
-	When showing `short` or `porcelain` status output, terminate
-	entries in the status output with NUL, instead of LF. If no
-	format is given, implies the `--porcelain` output format.
+	When showing `short` or `porcelain` status output, print the
+	filename verbatim and terminate the entries with NUL, instead of LF.
+	If no format is given, implies the `--porcelain` output format.
+	Without the `-z` option, filenames with "unusual" characters are
+	quoted as explained for the configuration variable `core.quotePath`
+	(see linkgit:git-config[1]).
 
 -F <file>::
 --file=<file>::
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index 446209e..1cab703 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -77,7 +77,8 @@ OPTIONS
 	succeed.
 
 -z::
-	\0 line termination on output.
+	\0 line termination on output and do not quote filenames.
+	See OUTPUT below for more information.
 
 -x <pattern>::
 --exclude=<pattern>::
@@ -196,9 +197,10 @@ the index records up to three such pairs; one from tree O in stage
 the user (or the porcelain) to see what should eventually be recorded at the
 path. (see linkgit:git-read-tree[1] for more information on state)
 
-When `-z` option is not used, TAB, LF, and backslash characters
-in pathnames are represented as `\t`, `\n`, and `\\`,
-respectively.
+Without the `-z` option, pathnames with "unusual" characters are
+quoted as explained for the configuration variable `core.quotePath`
+(see linkgit:git-config[1]).  Using `-z` the filename is output
+verbatim and the line is terminated by a NUL byte.
 
 
 Exclude Patterns
diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
index dbc91f9..9dee7be 100644
--- a/Documentation/git-ls-tree.txt
+++ b/Documentation/git-ls-tree.txt
@@ -53,7 +53,8 @@ OPTIONS
 	Show object size of blob (file) entries.
 
 -z::
-	\0 line termination on output.
+	\0 line termination on output and do not quote filenames.
+	See OUTPUT FORMAT below for more information.
 
 --name-only::
 --name-status::
@@ -82,8 +83,6 @@ Output Format
 -------------
         <mode> SP <type> SP <object> TAB <file>
 
-Unless the `-z` option is used, TAB, LF, and backslash characters
-in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
 This output format is compatible with what `--index-info --stdin` of
 'git update-index' expects.
 
@@ -95,6 +94,11 @@ Object size identified by <object> is given in bytes, and right-justified
 with minimum width of 7 characters.  Object size is given only for blobs
 (file) entries; for other entries `-` character is used in place of size.
 
+Without the `-z` option, pathnames with "unusual" characters are
+quoted as explained for the configuration variable `core.quotePath`
+(see linkgit:git-config[1]).  Using `-z` the filename is output
+verbatim and the line is terminated by a NUL byte.
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 725065e..ba87365 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -322,10 +322,9 @@ When the `-z` option is given, pathnames are printed as is and
 without any quoting and lines are terminated with a NUL (ASCII 0x00)
 byte.
 
-Otherwise, all pathnames will be "C-quoted" if they contain any tab,
-linefeed, double quote, or backslash characters. In C-quoting, these
-characters will be replaced with the corresponding C-style escape
-sequences and the resulting pathname will be double quoted.
+Without the `-z` option, pathnames with "unusual" characters are
+quoted as explained for the configuration variable `core.quotePath`
+(see linkgit:git-config[1]).
 
 
 CONFIGURATION

Re: [PATCH v2 2/2] Documentation: Link descriptions of -z to core.quotePath

[Jakub Narębski]

W dniu 24.02.2017 o 21:37, Andreas Heiduk pisze:
> Linking the description for pathname quoting to the configuration
> variable "core.quotePath" removes inconstistent and incomplete
> sections while also giving two hints how to deal with it: Either with
> "-c core.quotePath=false" or with "-z".

This patch I am not sure about.  On one hand it improves consistency
(and makes information more complete), on the other hand it removes
information at hand and instead refers to other manpage.

Perhaps a better solution would be to craft a short description that
is both sufficiently complete, and refers to "core.quotePath" for
more details, and then transclude it with "include::quotepath.txt[]".

> 
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>  Documentation/diff-format.txt         |  7 ++++---
>  Documentation/diff-generate-patch.txt |  7 +++----
>  Documentation/diff-options.txt        |  7 +++----
>  Documentation/git-apply.txt           |  7 +++----
>  Documentation/git-commit.txt          |  9 ++++++---
>  Documentation/git-ls-files.txt        | 10 ++++++----
>  Documentation/git-ls-tree.txt         | 10 +++++++---
>  Documentation/git-status.txt          |  7 +++----
>  8 files changed, 35 insertions(+), 29 deletions(-)
> 
> diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
> index cf52626..706916c 100644
> --- a/Documentation/diff-format.txt
> +++ b/Documentation/diff-format.txt
> @@ -78,9 +78,10 @@ Example:
>  :100644 100644 5be4a4...... 000000...... M file.c
>  ------------------------------------------------
>  
> -When `-z` option is not used, TAB, LF, and backslash characters
> -in pathnames are represented as `\t`, `\n`, and `\\`,
> -respectively.
> +Without the `-z` option, pathnames with "unusual" characters are
> +quoted as explained for the configuration variable `core.quotePath`
> +(see linkgit:git-config[1]).  Using `-z` the filename is output
> +verbatim and the line is terminated by a NUL byte.
>  
>  diff format for merges
>  ----------------------
> diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
> index d2a7ff5..231105c 100644
> --- a/Documentation/diff-generate-patch.txt
> +++ b/Documentation/diff-generate-patch.txt
> @@ -53,10 +53,9 @@ 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.
> +3.  Pathnames with "unusual" characters are quoted as explained for
> +    the configuration variable `core.quotePath` (see
> +    linkgit:git-config[1]).
>  
>  4.  All the `file1` files in the output refer to files before the
>      commit, and all the `file2` files refer to files after the commit.
> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index e6215c3..7c28e73 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -192,10 +192,9 @@ ifndef::git-log[]
>  	given, do not munge pathnames and use NULs as output field terminators.
>  endif::git-log[]
>  +
> -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.
> +Without this option, pathnames with "unusual" characters are munged as
> +explained for the configuration variable `core.quotePath` (see
> +linkgit:git-config[1]).
>  
>  --name-only::
>  	Show only names of changed files.
> diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
> index 8ddb207..a7a001b 100644
> --- a/Documentation/git-apply.txt
> +++ b/Documentation/git-apply.txt
> @@ -108,10 +108,9 @@ the information is read from the current index instead.
>  	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.
> +Without this option, pathnames with "unusual" characters are munged as
> +explained for the configuration variable `core.quotePath` (see
> +linkgit:git-config[1]).
>  
>  -p<n>::
>  	Remove <n> leading slashes from traditional diff paths. The
> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 4f8f20a..25dcdcc 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -117,9 +117,12 @@ OPTIONS
>  
>  -z::
>  --null::
> -	When showing `short` or `porcelain` status output, terminate
> -	entries in the status output with NUL, instead of LF. If no
> -	format is given, implies the `--porcelain` output format.
> +	When showing `short` or `porcelain` status output, print the
> +	filename verbatim and terminate the entries with NUL, instead of LF.
> +	If no format is given, implies the `--porcelain` output format.
> +	Without the `-z` option, filenames with "unusual" characters are
> +	quoted as explained for the configuration variable `core.quotePath`
> +	(see linkgit:git-config[1]).
>  
>  -F <file>::
>  --file=<file>::
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index 446209e..1cab703 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -77,7 +77,8 @@ OPTIONS
>  	succeed.
>  
>  -z::
> -	\0 line termination on output.
> +	\0 line termination on output and do not quote filenames.
> +	See OUTPUT below for more information.
>  
>  -x <pattern>::
>  --exclude=<pattern>::
> @@ -196,9 +197,10 @@ the index records up to three such pairs; one from tree O in stage
>  the user (or the porcelain) to see what should eventually be recorded at the
>  path. (see linkgit:git-read-tree[1] for more information on state)
>  
> -When `-z` option is not used, TAB, LF, and backslash characters
> -in pathnames are represented as `\t`, `\n`, and `\\`,
> -respectively.
> +Without the `-z` option, pathnames with "unusual" characters are
> +quoted as explained for the configuration variable `core.quotePath`
> +(see linkgit:git-config[1]).  Using `-z` the filename is output
> +verbatim and the line is terminated by a NUL byte.
>  
>  
>  Exclude Patterns
> diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
> index dbc91f9..9dee7be 100644
> --- a/Documentation/git-ls-tree.txt
> +++ b/Documentation/git-ls-tree.txt
> @@ -53,7 +53,8 @@ OPTIONS
>  	Show object size of blob (file) entries.
>  
>  -z::
> -	\0 line termination on output.
> +	\0 line termination on output and do not quote filenames.
> +	See OUTPUT FORMAT below for more information.
>  
>  --name-only::
>  --name-status::
> @@ -82,8 +83,6 @@ Output Format
>  -------------
>          <mode> SP <type> SP <object> TAB <file>
>  
> -Unless the `-z` option is used, TAB, LF, and backslash characters
> -in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
>  This output format is compatible with what `--index-info --stdin` of
>  'git update-index' expects.
>  
> @@ -95,6 +94,11 @@ Object size identified by <object> is given in bytes, and right-justified
>  with minimum width of 7 characters.  Object size is given only for blobs
>  (file) entries; for other entries `-` character is used in place of size.
>  
> +Without the `-z` option, pathnames with "unusual" characters are
> +quoted as explained for the configuration variable `core.quotePath`
> +(see linkgit:git-config[1]).  Using `-z` the filename is output
> +verbatim and the line is terminated by a NUL byte.
> +
>  GIT
>  ---
>  Part of the linkgit:git[1] suite
> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
> index 725065e..ba87365 100644
> --- a/Documentation/git-status.txt
> +++ b/Documentation/git-status.txt
> @@ -322,10 +322,9 @@ When the `-z` option is given, pathnames are printed as is and
>  without any quoting and lines are terminated with a NUL (ASCII 0x00)
>  byte.
>  
> -Otherwise, all pathnames will be "C-quoted" if they contain any tab,
> -linefeed, double quote, or backslash characters. In C-quoting, these
> -characters will be replaced with the corresponding C-style escape
> -sequences and the resulting pathname will be double quoted.
> +Without the `-z` option, pathnames with "unusual" characters are
> +quoted as explained for the configuration variable `core.quotePath`
> +(see linkgit:git-config[1]).
>  
>  
>  CONFIGURATION
> 

Re: [PATCH v2 2/2] Documentation: Link descriptions of -z to core.quotePath

[Andreas Heiduk]

Am 24.02.2017 um 22:54 schrieb Jakub Narębski:
> W dniu 24.02.2017 o 21:37, Andreas Heiduk pisze:
>> Linking the description for pathname quoting to the configuration
>> variable "core.quotePath" removes inconstistent and incomplete
>> sections while also giving two hints how to deal with it: Either with
>> "-c core.quotePath=false" or with "-z".
> 
> This patch I am not sure about.  On one hand it improves consistency
> (and makes information more complete), on the other hand it removes
> information at hand and instead refers to other manpage.

Indeed this is a trade-off. My intention was to establish some kind of
well-known term by citing "core.quotePath" everywhere. So after a while
"quoting" and "core.quotePath" should be known by everyone interested.

> Perhaps a better solution would be to craft a short description that
> is both sufficiently complete, and refers to "core.quotePath" for
> more details, and then transclude it with "include::quotepath.txt[]".

On the other hand this makes every section quite long. Personally, I
find long and repetitive documentation harder to comprehend.

>>
>> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
>> ---
>>  Documentation/diff-format.txt         |  7 ++++---
>>  Documentation/diff-generate-patch.txt |  7 +++----
>>  Documentation/diff-options.txt        |  7 +++----
>>  Documentation/git-apply.txt           |  7 +++----
>>  Documentation/git-commit.txt          |  9 ++++++---
>>  Documentation/git-ls-files.txt        | 10 ++++++----
>>  Documentation/git-ls-tree.txt         | 10 +++++++---
>>  Documentation/git-status.txt          |  7 +++----
>>  8 files changed, 35 insertions(+), 29 deletions(-)
>>
>> diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
>> index cf52626..706916c 100644
>> --- a/Documentation/diff-format.txt
>> +++ b/Documentation/diff-format.txt
>> @@ -78,9 +78,10 @@ Example:
>>  :100644 100644 5be4a4...... 000000...... M file.c
>>  ------------------------------------------------
>>  
>> -When `-z` option is not used, TAB, LF, and backslash characters
>> -in pathnames are represented as `\t`, `\n`, and `\\`,
>> -respectively.
>> +Without the `-z` option, pathnames with "unusual" characters are
>> +quoted as explained for the configuration variable `core.quotePath`
>> +(see linkgit:git-config[1]).  Using `-z` the filename is output
>> +verbatim and the line is terminated by a NUL byte.
>>  
>>  diff format for merges
>>  ----------------------
>> diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt
>> index d2a7ff5..231105c 100644
>> --- a/Documentation/diff-generate-patch.txt
>> +++ b/Documentation/diff-generate-patch.txt
>> @@ -53,10 +53,9 @@ 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.
>> +3.  Pathnames with "unusual" characters are quoted as explained for
>> +    the configuration variable `core.quotePath` (see
>> +    linkgit:git-config[1]).
>>  
>>  4.  All the `file1` files in the output refer to files before the
>>      commit, and all the `file2` files refer to files after the commit.
>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
>> index e6215c3..7c28e73 100644
>> --- a/Documentation/diff-options.txt
>> +++ b/Documentation/diff-options.txt
>> @@ -192,10 +192,9 @@ ifndef::git-log[]
>>  	given, do not munge pathnames and use NULs as output field terminators.
>>  endif::git-log[]
>>  +
>> -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.
>> +Without this option, pathnames with "unusual" characters are munged as
>> +explained for the configuration variable `core.quotePath` (see
>> +linkgit:git-config[1]).
>>  
>>  --name-only::
>>  	Show only names of changed files.
>> diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
>> index 8ddb207..a7a001b 100644
>> --- a/Documentation/git-apply.txt
>> +++ b/Documentation/git-apply.txt
>> @@ -108,10 +108,9 @@ the information is read from the current index instead.
>>  	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.
>> +Without this option, pathnames with "unusual" characters are munged as
>> +explained for the configuration variable `core.quotePath` (see
>> +linkgit:git-config[1]).
>>  
>>  -p<n>::
>>  	Remove <n> leading slashes from traditional diff paths. The
>> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
>> index 4f8f20a..25dcdcc 100644
>> --- a/Documentation/git-commit.txt
>> +++ b/Documentation/git-commit.txt
>> @@ -117,9 +117,12 @@ OPTIONS
>>  
>>  -z::
>>  --null::
>> -	When showing `short` or `porcelain` status output, terminate
>> -	entries in the status output with NUL, instead of LF. If no
>> -	format is given, implies the `--porcelain` output format.
>> +	When showing `short` or `porcelain` status output, print the
>> +	filename verbatim and terminate the entries with NUL, instead of LF.
>> +	If no format is given, implies the `--porcelain` output format.
>> +	Without the `-z` option, filenames with "unusual" characters are
>> +	quoted as explained for the configuration variable `core.quotePath`
>> +	(see linkgit:git-config[1]).
>>  
>>  -F <file>::
>>  --file=<file>::
>> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
>> index 446209e..1cab703 100644
>> --- a/Documentation/git-ls-files.txt
>> +++ b/Documentation/git-ls-files.txt
>> @@ -77,7 +77,8 @@ OPTIONS
>>  	succeed.
>>  
>>  -z::
>> -	\0 line termination on output.
>> +	\0 line termination on output and do not quote filenames.
>> +	See OUTPUT below for more information.
>>  
>>  -x <pattern>::
>>  --exclude=<pattern>::
>> @@ -196,9 +197,10 @@ the index records up to three such pairs; one from tree O in stage
>>  the user (or the porcelain) to see what should eventually be recorded at the
>>  path. (see linkgit:git-read-tree[1] for more information on state)
>>  
>> -When `-z` option is not used, TAB, LF, and backslash characters
>> -in pathnames are represented as `\t`, `\n`, and `\\`,
>> -respectively.
>> +Without the `-z` option, pathnames with "unusual" characters are
>> +quoted as explained for the configuration variable `core.quotePath`
>> +(see linkgit:git-config[1]).  Using `-z` the filename is output
>> +verbatim and the line is terminated by a NUL byte.
>>  
>>  
>>  Exclude Patterns
>> diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt
>> index dbc91f9..9dee7be 100644
>> --- a/Documentation/git-ls-tree.txt
>> +++ b/Documentation/git-ls-tree.txt
>> @@ -53,7 +53,8 @@ OPTIONS
>>  	Show object size of blob (file) entries.
>>  
>>  -z::
>> -	\0 line termination on output.
>> +	\0 line termination on output and do not quote filenames.
>> +	See OUTPUT FORMAT below for more information.
>>  
>>  --name-only::
>>  --name-status::
>> @@ -82,8 +83,6 @@ Output Format
>>  -------------
>>          <mode> SP <type> SP <object> TAB <file>
>>  
>> -Unless the `-z` option is used, TAB, LF, and backslash characters
>> -in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
>>  This output format is compatible with what `--index-info --stdin` of
>>  'git update-index' expects.
>>  
>> @@ -95,6 +94,11 @@ Object size identified by <object> is given in bytes, and right-justified
>>  with minimum width of 7 characters.  Object size is given only for blobs
>>  (file) entries; for other entries `-` character is used in place of size.
>>  
>> +Without the `-z` option, pathnames with "unusual" characters are
>> +quoted as explained for the configuration variable `core.quotePath`
>> +(see linkgit:git-config[1]).  Using `-z` the filename is output
>> +verbatim and the line is terminated by a NUL byte.
>> +
>>  GIT
>>  ---
>>  Part of the linkgit:git[1] suite
>> diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
>> index 725065e..ba87365 100644
>> --- a/Documentation/git-status.txt
>> +++ b/Documentation/git-status.txt
>> @@ -322,10 +322,9 @@ When the `-z` option is given, pathnames are printed as is and
>>  without any quoting and lines are terminated with a NUL (ASCII 0x00)
>>  byte.
>>  
>> -Otherwise, all pathnames will be "C-quoted" if they contain any tab,
>> -linefeed, double quote, or backslash characters. In C-quoting, these
>> -characters will be replaced with the corresponding C-style escape
>> -sequences and the resulting pathname will be double quoted.
>> +Without the `-z` option, pathnames with "unusual" characters are
>> +quoted as explained for the configuration variable `core.quotePath`
>> +(see linkgit:git-config[1]).
>>  
>>  
>>  CONFIGURATION
>>
> 

Re: [PATCH v2 2/2] Documentation: Link descriptions of -z to core.quotePath

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index e6215c3..7c28e73 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -192,10 +192,9 @@ ifndef::git-log[]
>  	given, do not munge pathnames and use NULs as output field terminators.
>  endif::git-log[]
>  +
> -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.
> +Without this option, pathnames with "unusual" characters are munged as
> +explained for the configuration variable `core.quotePath` (see
> +linkgit:git-config[1]).

Seeing that many other instances call this "quoted", we may want to
be consistent.  I can see "munge" in the pre-context, but that one
can stay as is. Under -z, no modification/munging happens.  With -z,
a specific kind of modification (called "quote" described in the
documentation for core.quotepath variable) happens.  The same
comment applies to the change to Documentation/git-apply.txt

Otherwise the patch looks good.

Thanks.

Re: [PATCH v2 2/2] Documentation: Link descriptions of -z to core.quotePath

[Andreas Heiduk]

Am 28.02.2017 um 21:51 schrieb Junio C Hamano:
> Andreas Heiduk <asheiduk@gmail.com> writes:
> 
>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
>> index e6215c3..7c28e73 100644
>> --- a/Documentation/diff-options.txt
>> +++ b/Documentation/diff-options.txt
>> @@ -192,10 +192,9 @@ ifndef::git-log[]
>>  	given, do not munge pathnames and use NULs as output field terminators.
>>  endif::git-log[]
>>  +
>> -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.
>> +Without this option, pathnames with "unusual" characters are munged as
>> +explained for the configuration variable `core.quotePath` (see
>> +linkgit:git-config[1]).
> 
> Seeing that many other instances call this "quoted", we may want to
> be consistent.  I can see "munge" in the pre-context, but that one
> can stay as is. Under -z, no modification/munging happens.  With -z,
> a specific kind of modification (called "quote" described in the
> documentation for core.quotepath variable) happens.  The same
> comment applies to the change to Documentation/git-apply.txt
> 
> Otherwise the patch looks good.
> 
> Thanks.
>

I'll fix the "munged" and, unless there are objections, I will also
replace the remaining ones in the vicinity. These are the last
occurrences of "munged".

You are OK with the references to another man page? My idea was to
establish a well-known term.

Re: [PATCH v2 2/2] Documentation: Link descriptions of -z to core.quotePath

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> I'll fix the "munged" and, unless there are objections, I will also
> replace the remaining ones in the vicinity. These are the last
> occurrences of "munged".

I'd rather see the "we do not munge" to stay the same.  "we do not
quote" still allows us to do modifications that are different from
quoting.

> You are OK with the references to another man page? My idea was to
> establish a well-known term.

The "well-known term" cannot just be "quote", because it is too
generic.  "git rev-parse --sq-quote" does a different kind of
quoting from the quoting done here for paths with unusual
characters, for example.

We certainly *could* (1) add to glossary-content.txt the definition
of "c-quote" and describe it there, (2) change the "see the quoting
explained for core.quotePath" to "unless -z is given, paths are
c-quoted", and (3) change the core.quotePath description to refer to
"c-quote" in the glossary.

But I am not sure it that makes the resulting document easier to use
by the end users.  I personally find the result of applying the
patch you posted easier.

Re: [PATCH] Documentation: Link git-ls-files to core.quotePath variable.

[Junio C Hamano]

Andreas Heiduk <asheiduk@gmail.com> writes:

> [PATCH] Documentation: Clarify core.quotePath, remove cruft in
>  git-ls-files.
>
> Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
> ---
>
> I have merged the best parts about quoting into the core.quotePath
> description and cleaned up the text in git-ls-files.txt regarding the
> control characters.
>
>
>  Documentation/config.txt       | 22 ++++++++++++----------
>  Documentation/git-ls-files.txt | 11 ++++++-----
>  2 files changed, 18 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index f4721a0..25e65ae 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -340,16 +340,18 @@ core.checkStat::
>  	all fields, including the sub-second part of mtime and ctime.
>
>  core.quotePath::
> -	The commands that output paths (e.g. 'ls-files',
> -	'diff'), when not given the `-z` option, will quote
> -	"unusual" characters in the pathname by enclosing the
> -	pathname in a double-quote pair and with backslashes the
> -	same way strings in C source code are quoted.  If this
> -	variable is set to false, the bytes higher than 0x80 are
> -	not quoted but output as verbatim.  Note that double
> -	quote, backslash and control characters are always
> -	quoted without `-z` regardless of the setting of this
> -	variable.
> +	Commands that output paths (e.g. 'ls-files', 'diff'), will
> +	quote "unusual" characters in the pathname by enclosing the
> +	pathname in double-quotes and escaping those characters with
> +	backslashes in the same way C escapes control characters (e.g.
> +	`\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
> +	values larger than 0x80 (e.g. octal `\265` for "micro").  If
> +	this variable is set to false, bytes higher than 0x80 are not
> +	considered "unusual" any more.  Double-quotes, backslash and
> +	control characters are always escaped regardless of the
> +	setting of this variable.  Many commands can output pathnames
> +	completely verbatim using the `-z` option. The default value is
> +	true.

Even though I am not sure "\265 is micro" is a good example these
days, as "high-bit set" is primarily meant to catch UTF-8
multi-bytes, I find the above much easier to read than the original.

> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index d2b17f2..88df561 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -76,7 +76,8 @@ OPTIONS
>  	succeed.
>
>  -z::
> -	\0 line termination on output.
> +	\0 line termination on output and do not quote filenames.
> +	See OUTPUT below for more information.
>
>  -x <pattern>::
>  --exclude=<pattern>::
> @@ -192,10 +193,10 @@ the index records up to three such pairs; one from
> tree O in stage
>  the user (or the porcelain) to see what should eventually be recorded
> at the
>  path. (see linkgit:git-read-tree[1] for more information on state)
>
> -When `-z` option is not used, TAB, LF, and backslash characters
> -in pathnames are represented as `\t`, `\n`, and `\\`,
> -respectively. The path is also quoted according to the
> -configuration variable `core.quotePath` (see linkgit:git-config[1]).
> +Without the `-z` option pathnamens with "unusual" characters are
> +quoted as explained for the configuration variable `core.quotePath`
> +(see linkgit:git-config[1]).  Using `-z` the filename is output
> +verbatim and the line is terminated by a NUL byte.

Yup, this looks much nicer than the original.

Thanks.