Andreas Heiduk <ashei...@gmail.com> writes: > [PATCH] Documentation: Clarify core.quotePath, remove cruft in > git-ls-files. > > Signed-off-by: Andreas Heiduk <ashei...@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.
