Documentation: improve description for core.quotePath
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Andreas Heiduk committed
Mar 2, 2017 at 20:03 UTC
860cd699c285f02937a2edbdb78e8231292339a5
9 files changed
+48
-39
Documentation/config.txt
+13
-10
@@ -350,16 +350,19 @@ core.checkStat::
350
all fields, including the sub-second part of mtime and ctime.
351
352
core.quotePath::
353
- The commands that output paths (e.g. 'ls-files',
354
- 'diff'), when not given the `-z` option, will quote
355
- "unusual" characters in the pathname by enclosing the
356
- pathname in a double-quote pair and with backslashes the
357
- same way strings in C source code are quoted. If this
358
- variable is set to false, the bytes higher than 0x80 are
359
- not quoted but output as verbatim. Note that double
360
- quote, backslash and control characters are always
361
- quoted without `-z` regardless of the setting of this
362
- variable.
353
+ Commands that output paths (e.g. 'ls-files', 'diff'), will
354
+ quote "unusual" characters in the pathname by enclosing the
355
+ pathname in double-quotes and escaping those characters with
356
+ backslashes in the same way C escapes control characters (e.g.
357
+ `\t` for TAB, `\n` for LF, `\\` for backslash) or bytes with
358
+ values larger than 0x80 (e.g. octal `\302\265` for "micro" in
359
+ UTF-8). If this variable is set to false, bytes higher than
360
+ 0x80 are not considered "unusual" any more. Double-quotes,
361
+ backslash and control characters are always escaped regardless
362
+ of the setting of this variable. A simple space character is
363
+ not considered "unusual". Many commands can output pathnames
364
+ completely verbatim using the `-z` option. The default value
365
+ is true.
366
367
core.eol::
368
Sets the line ending type to use in the working directory for
Documentation/diff-format.txt
+4
-3
@@ -78,9 +78,10 @@ Example:
78
:100644 100644 5be4a4...... 000000...... M file.c
79
------------------------------------------------
80
81
-When `-z` option is not used, TAB, LF, and backslash characters
82
-in pathnames are represented as `\t`, `\n`, and `\\`,
83
-respectively.
81
+Without the `-z` option, pathnames with "unusual" characters are
82
+quoted as explained for the configuration variable `core.quotePath`
83
+(see linkgit:git-config[1]). Using `-z` the filename is output
84
+verbatim and the line is terminated by a NUL byte.
85
86
diff format for merges
87
----------------------
Documentation/diff-generate-patch.txt
+3
-4
@@ -53,10 +53,9 @@ The index line includes the SHA-1 checksum before and after the change.
53
The <mode> is included if the file mode does not change; otherwise,
54
separate lines indicate the old and the new mode.
55
56
-3. TAB, LF, double quote and backslash characters in pathnames
57
- are represented as `\t`, `\n`, `\"` and `\\`, respectively.
58
- If there is need for such substitution then the whole
59
- pathname is put in double quotes.
56
+3. Pathnames with "unusual" characters are quoted as explained for
57
+ the configuration variable `core.quotePath` (see
58
+ linkgit:git-config[1]).
59
60
4. All the `file1` files in the output refer to files before the
61
commit, and all the `file2` files refer to files after the commit.
Documentation/diff-options.txt
+3
-4
@@ -192,10 +192,9 @@ ifndef::git-log[]
192
given, do not munge pathnames and use NULs as output field terminators.
193
endif::git-log[]
194
+
195
-Without this option, each pathname output will have TAB, LF, double quotes,
196
-and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`,
197
-respectively, and the pathname will be enclosed in double quotes if
198
-any of those replacements occurred.
195
+Without this option, pathnames with "unusual" characters are quoted as
196
+explained for the configuration variable `core.quotePath` (see
197
+linkgit:git-config[1]).
198
199
--name-only::
200
Show only names of changed files.
Documentation/git-apply.txt
+3
-4
@@ -108,10 +108,9 @@ the information is read from the current index instead.
108
When `--numstat` has been given, do not munge pathnames,
109
but use a NUL-terminated machine-readable format.
110
+
111
-Without this option, each pathname output will have TAB, LF, double quotes,
112
-and backslash characters replaced with `\t`, `\n`, `\"`, and `\\`,
113
-respectively, and the pathname will be enclosed in double quotes if
114
-any of those replacements occurred.
111
+Without this option, pathnames with "unusual" characters are quoted as
112
+explained for the configuration variable `core.quotePath` (see
113
+linkgit:git-config[1]).
114
115
-p<n>::
116
Remove <n> leading slashes from traditional diff paths. The
Documentation/git-commit.txt
+6
-3
@@ -117,9 +117,12 @@ OPTIONS
117
118
-z::
119
--null::
120
- When showing `short` or `porcelain` status output, terminate
121
- entries in the status output with NUL, instead of LF. If no
122
- format is given, implies the `--porcelain` output format.
120
+ When showing `short` or `porcelain` status output, print the
121
+ filename verbatim and terminate the entries with NUL, instead of LF.
122
+ If no format is given, implies the `--porcelain` output format.
123
+ Without the `-z` option, filenames with "unusual" characters are
124
+ quoted as explained for the configuration variable `core.quotePath`
125
+ (see linkgit:git-config[1]).
126
127
-F <file>::
128
--file=<file>::
Documentation/git-ls-files.txt
+6
-4
@@ -77,7 +77,8 @@ OPTIONS
77
succeed.
78
79
-z::
80
- \0 line termination on output.
80
+ \0 line termination on output and do not quote filenames.
81
+ See OUTPUT below for more information.
82
83
-x <pattern>::
84
--exclude=<pattern>::
@@ -196,9 +197,10 @@ the index records up to three such pairs; one from tree O in stage
197
the user (or the porcelain) to see what should eventually be recorded at the
198
path. (see linkgit:git-read-tree[1] for more information on state)
199
199
-When `-z` option is not used, TAB, LF, and backslash characters
200
-in pathnames are represented as `\t`, `\n`, and `\\`,
201
-respectively.
200
+Without the `-z` option, pathnames with "unusual" characters are
201
+quoted as explained for the configuration variable `core.quotePath`
202
+(see linkgit:git-config[1]). Using `-z` the filename is output
203
+verbatim and the line is terminated by a NUL byte.
204
205
206
Exclude Patterns
Documentation/git-ls-tree.txt
+7
-3
@@ -53,7 +53,8 @@ OPTIONS
53
Show object size of blob (file) entries.
54
55
-z::
56
- \0 line termination on output.
56
+ \0 line termination on output and do not quote filenames.
57
+ See OUTPUT FORMAT below for more information.
58
59
--name-only::
60
--name-status::
@@ -82,8 +83,6 @@ Output Format
83
-------------
84
<mode> SP <type> SP <object> TAB <file>
85
85
-Unless the `-z` option is used, TAB, LF, and backslash characters
86
-in pathnames are represented as `\t`, `\n`, and `\\`, respectively.
86
This output format is compatible with what `--index-info --stdin` of
87
'git update-index' expects.
88
@@ -95,6 +94,11 @@ Object size identified by <object> is given in bytes, and right-justified
94
with minimum width of 7 characters. Object size is given only for blobs
95
(file) entries; for other entries `-` character is used in place of size.
96
97
+Without the `-z` option, pathnames with "unusual" characters are
98
+quoted as explained for the configuration variable `core.quotePath`
99
+(see linkgit:git-config[1]). Using `-z` the filename is output
100
+verbatim and the line is terminated by a NUL byte.
101
+
102
GIT
103
---
104
Part of the linkgit:git[1] suite
Documentation/git-status.txt
+3
-4
@@ -322,10 +322,9 @@ When the `-z` option is given, pathnames are printed as is and
322
without any quoting and lines are terminated with a NUL (ASCII 0x00)
323
byte.
324
325
-Otherwise, all pathnames will be "C-quoted" if they contain any tab,
326
-linefeed, double quote, or backslash characters. In C-quoting, these
327
-characters will be replaced with the corresponding C-style escape
328
-sequences and the resulting pathname will be double quoted.
325
+Without the `-z` option, pathnames with "unusual" characters are
326
+quoted as explained for the configuration variable `core.quotePath`
327
+(see linkgit:git-config[1]).
328
329
330
CONFIGURATION