{"thread":{"id":"45265","subject":"[PATCH v3] Documentation: Improve description for core.quotePath","startedAt":"2017-03-02T19:06:05Z","lastAt":"2017-03-02T21:21:26Z","messageCount":2,"participants":["Andreas Heiduk","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"313086","messageId":"1488481432-25336-1-git-send-email-asheiduk@gmail.com","threadId":"45265","inReplyTo":null,"subject":"[PATCH v3] Documentation: Improve description for core.quotePath","fromName":"Andreas Heiduk","fromEmail":"asheiduk@gmail.com","sentAt":"2017-03-02T19:03:52Z","receivedAt":"2017-03-02T19:06:05Z","isPatch":true,"sender":{"key":"asheiduk@gmail.com","avatar":"https://avatars.githubusercontent.com/u/9371344?v=4"},"body":"Linking the description for pathname quoting to the configuration\nvariable \"core.quotePath\" removes inconstistent and incomplete\nsections while also giving two hints how to deal with it: Either with\n\"-c core.quotePath=false\" or with \"-z\".\n\nSigned-off-by: Andreas Heiduk <asheiduk@gmail.com>\n---\n Documentation/config.txt              | 23 +++++++++++++----------\n Documentation/diff-format.txt         |  7 ++++---\n Documentation/diff-generate-patch.txt |  7 +++----\n Documentation/diff-options.txt        |  7 +++----\n Documentation/git-apply.txt           |  7 +++----\n Documentation/git-commit.txt          |  9 ++++++---\n Documentation/git-ls-files.txt        | 10 ++++++----\n Documentation/git-ls-tree.txt         | 10 +++++++---\n Documentation/git-status.txt          |  7 +++----\n 9 files changed, 48 insertions(+), 39 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 015346c..23233d8 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -350,16 +350,19 @@ core.checkStat::\n \tall fields, including the sub-second part of mtime and ctime.\n \n core.quotePath::\n-\tThe commands that output paths (e.g. 'ls-files',\n-\t'diff'), when not given the `-z` option, will quote\n-\t\"unusual\" characters in the pathname by enclosing the\n-\tpathname in a double-quote pair and with backslashes the\n-\tsame way strings in C source code are quoted.  If this\n-\tvariable is set to false, the bytes higher than 0x80 are\n-\tnot quoted but output as verbatim.  Note that double\n-\tquote, backslash and control characters are always\n-\tquoted without `-z` regardless of the setting of this\n-\tvariable.\n+\tCommands that output paths (e.g. 'ls-files', 'diff'), will\n+\tquote \"unusual\" characters in the pathname by enclosing the\n+\tpathname in double-quotes and escaping those characters with\n+\tbackslashes in the same way C escapes control characters (e.g.\n+\t`\\t` for TAB, `\\n` for LF, `\\\\` for backslash) or bytes with\n+\tvalues larger than 0x80 (e.g. octal `\\302\\265` for \"micro\" in\n+\tUTF-8).  If this variable is set to false, bytes higher than\n+\t0x80 are not considered \"unusual\" any more. Double-quotes,\n+\tbackslash and control characters are always escaped regardless\n+\tof the setting of this variable.  A simple space character is\n+\tnot considered \"unusual\".  Many commands can output pathnames\n+\tcompletely verbatim using the `-z` option. The default value\n+\tis true.\n \n core.eol::\n \tSets the line ending type to use in the working directory for\ndiff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt\nindex cf52626..706916c 100644\n--- a/Documentation/diff-format.txt\n+++ b/Documentation/diff-format.txt\n@@ -78,9 +78,10 @@ Example:\n :100644 100644 5be4a4...... 000000...... M file.c\n ------------------------------------------------\n \n-When `-z` option is not used, TAB, LF, and backslash characters\n-in pathnames are represented as `\\t`, `\\n`, and `\\\\`,\n-respectively.\n+Without the `-z` option, pathnames with \"unusual\" characters are\n+quoted as explained for the configuration variable `core.quotePath`\n+(see linkgit:git-config[1]).  Using `-z` the filename is output\n+verbatim and the line is terminated by a NUL byte.\n \n diff format for merges\n ----------------------\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex d2a7ff5..231105c 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -53,10 +53,9 @@ The index line includes the SHA-1 checksum before and after the change.\n The <mode> is included if the file mode does not change; otherwise,\n separate lines indicate the old and the new mode.\n \n-3.  TAB, LF, double quote and backslash characters in pathnames\n-    are represented as `\\t`, `\\n`, `\\\"` and `\\\\`, respectively.\n-    If there is need for such substitution then the whole\n-    pathname is put in double quotes.\n+3.  Pathnames with \"unusual\" characters are quoted as explained for\n+    the configuration variable `core.quotePath` (see\n+    linkgit:git-config[1]).\n \n 4.  All the `file1` files in the output refer to files before the\n     commit, and all the `file2` files refer to files after the commit.\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex d91ddbd..89cc0f4 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -192,10 +192,9 @@ ifndef::git-log[]\n \tgiven, do not munge pathnames and use NULs as output field terminators.\n endif::git-log[]\n +\n-Without this option, each pathname output will have TAB, LF, double quotes,\n-and backslash characters replaced with `\\t`, `\\n`, `\\\"`, and `\\\\`,\n-respectively, and the pathname will be enclosed in double quotes if\n-any of those replacements occurred.\n+Without this option, pathnames with \"unusual\" characters are quoted as\n+explained for the configuration variable `core.quotePath` (see\n+linkgit:git-config[1]).\n \n --name-only::\n \tShow only names of changed files.\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex 8ddb207..631cbd8 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -108,10 +108,9 @@ the information is read from the current index instead.\n \tWhen `--numstat` has been given, do not munge pathnames,\n \tbut use a NUL-terminated machine-readable format.\n +\n-Without this option, each pathname output will have TAB, LF, double quotes,\n-and backslash characters replaced with `\\t`, `\\n`, `\\\"`, and `\\\\`,\n-respectively, and the pathname will be enclosed in double quotes if\n-any of those replacements occurred.\n+Without this option, pathnames with \"unusual\" characters are quoted as\n+explained for the configuration variable `core.quotePath` (see\n+linkgit:git-config[1]).\n \n -p<n>::\n \tRemove <n> leading slashes from traditional diff paths. The\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 4f8f20a..25dcdcc 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -117,9 +117,12 @@ OPTIONS\n \n -z::\n --null::\n-\tWhen showing `short` or `porcelain` status output, terminate\n-\tentries in the status output with NUL, instead of LF. If no\n-\tformat is given, implies the `--porcelain` output format.\n+\tWhen showing `short` or `porcelain` status output, print the\n+\tfilename verbatim and terminate the entries with NUL, instead of LF.\n+\tIf no format is given, implies the `--porcelain` output format.\n+\tWithout the `-z` option, filenames with \"unusual\" characters are\n+\tquoted as explained for the configuration variable `core.quotePath`\n+\t(see linkgit:git-config[1]).\n \n -F <file>::\n --file=<file>::\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 446209e..1cab703 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -77,7 +77,8 @@ OPTIONS\n \tsucceed.\n \n -z::\n-\t\\0 line termination on output.\n+\t\\0 line termination on output and do not quote filenames.\n+\tSee OUTPUT below for more information.\n \n -x <pattern>::\n --exclude=<pattern>::\n@@ -196,9 +197,10 @@ the index records up to three such pairs; one from tree O in stage\n the user (or the porcelain) to see what should eventually be recorded at the\n path. (see linkgit:git-read-tree[1] for more information on state)\n \n-When `-z` option is not used, TAB, LF, and backslash characters\n-in pathnames are represented as `\\t`, `\\n`, and `\\\\`,\n-respectively.\n+Without the `-z` option, pathnames with \"unusual\" characters are\n+quoted as explained for the configuration variable `core.quotePath`\n+(see linkgit:git-config[1]).  Using `-z` the filename is output\n+verbatim and the line is terminated by a NUL byte.\n \n \n Exclude Patterns\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex dbc91f9..9dee7be 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -53,7 +53,8 @@ OPTIONS\n \tShow object size of blob (file) entries.\n \n -z::\n-\t\\0 line termination on output.\n+\t\\0 line termination on output and do not quote filenames.\n+\tSee OUTPUT FORMAT below for more information.\n \n --name-only::\n --name-status::\n@@ -82,8 +83,6 @@ Output Format\n -------------\n         <mode> SP <type> SP <object> TAB <file>\n \n-Unless the `-z` option is used, TAB, LF, and backslash characters\n-in pathnames are represented as `\\t`, `\\n`, and `\\\\`, respectively.\n This output format is compatible with what `--index-info --stdin` of\n 'git update-index' expects.\n \n@@ -95,6 +94,11 @@ Object size identified by <object> is given in bytes, and right-justified\n with minimum width of 7 characters.  Object size is given only for blobs\n (file) entries; for other entries `-` character is used in place of size.\n \n+Without the `-z` option, pathnames with \"unusual\" characters are\n+quoted as explained for the configuration variable `core.quotePath`\n+(see linkgit:git-config[1]).  Using `-z` the filename is output\n+verbatim and the line is terminated by a NUL byte.\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 725065e..ba87365 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -322,10 +322,9 @@ When the `-z` option is given, pathnames are printed as is and\n without any quoting and lines are terminated with a NUL (ASCII 0x00)\n byte.\n \n-Otherwise, all pathnames will be \"C-quoted\" if they contain any tab,\n-linefeed, double quote, or backslash characters. In C-quoting, these\n-characters will be replaced with the corresponding C-style escape\n-sequences and the resulting pathname will be double quoted.\n+Without the `-z` option, pathnames with \"unusual\" characters are\n+quoted as explained for the configuration variable `core.quotePath`\n+(see linkgit:git-config[1]).\n \n \n CONFIGURATION\n"},{"id":"313101","messageId":"xmqqo9xjbh4w.fsf@gitster.mtv.corp.google.com","threadId":"45265","inReplyTo":"1488481432-25336-1-git-send-email-asheiduk@gmail.com","subject":"Re: [PATCH v3] Documentation: Improve description for core.quotePath","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-03-02T19:41:51Z","receivedAt":"2017-03-02T21:21:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"This is now a single-patch, which makes sense, too.\n\nLet's merge it to 'next'.\n\nThanks.\n"}]}