Re: [PATCH 5/6] fast-import: document C-style escapes for paths
On Fri, Mar 22, 2024 at 12:03:47AM +0000, Thalia Archibald wrote:
Show 22 quoted lines
> Simply saying “C-style” string quoting is imprecise, as only a subset of
> C escapes are supported. Document the exact escapes.
>
> 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.
Paths also mustn't start with a space in many cases, right?
Patrick
Show 26 quoted lines
> 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
>
>
>
Patrick Steinhardt <ps@pks.im>