[PATCH 5/6] fast-import: document C-style escapes for paths

From

Thalia Archibald <thalia@archibald.dev>

Date

Mar 22, 2024, 00:03 UTC

Message-ID

<20240322000304.76810-6-thalia@archibald.dev>

In-Reply-To

<20240322000304.76810-1-thalia@archibald.dev>

Signed-off-by: Thalia Archibald <thalia@archibald.dev>
---
 Documentation/git-fast-import.txt | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 271bd63a10..4aa8ccbefd 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -630,18 +630,23 @@ in octal.  Git only supports the following modes:
 In both formats `<path>` is the complete path of the file to be added
 (if not already existing) or modified (if already existing).
 
-A `<path>` string must use UNIX-style directory separators (forward
-slash `/`), may contain any byte other than `LF`, and must not
-start with double quote (`"`).
+A `<path>` string may contain any byte other than `LF`, and must not
+start with double quote (`"`). It is interpreted as literal bytes
+without escaping.
 
 A path can use C-style string quoting; this is accepted in all cases
 and mandatory if the filename starts with double quote or contains
-`LF`. In C-style quoting, the complete name should be surrounded with
-double quotes, and any `LF`, backslash, or double quote characters
-must be escaped by preceding them with a backslash (e.g.,
-`"path/with\n, \\ and \" in it"`).
+`LF`. In C-style quoting, the complete name is surrounded with
+double quotes (`"`) and certain characters must be escaped by preceding
+them with a backslash: `LF` is written as `\n`, backslash as `\\`, and
+double quote as `\"`. Additionally, some characters may may optionally
+be written with escape sequences: `\a` for bell, `\b` for backspace,
+`\f` for form feed, `\n` for line feed, `\r` for carriage return, `\t`
+for horizontal tab, and `\v` for vertical tab. Any byte can be written
+with 3-digit octal codes (e.g., `\033`).
 
-The value of `<path>` must be in canonical form. That is it must not:
+A `<path>` must use UNIX-style directory separators (forward slash `/`)
+and must be in canonical form. That is it must not:
 
 * contain an empty directory component (e.g. `foo//bar` is invalid),
 * end with a directory separator (e.g. `foo/` is invalid),

-- 
2.44.0