[PATCH] doc: fix hex code escapes in git-ls-files

[PATCH] doc: fix hex code escapes in git-ls-files

[Jayson Rhynas]

The --format option on the git-ls-files man page states that `%xx`
interpolates to the character with hex code `xx`. This mirrors the
documentation and behavior of `git for-each-ref --format=...`. However,
in reality it requires the character with code `XX` to be specified as
`%xXX`, mirroring the behaviour of  `git log --format`.

Signed-off-by: Jayson Rhynas <jayrhynas@gmail.com>
---
 Documentation/git-ls-files.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
index d08c7da8f4..58c529afbe 100644
--- a/Documentation/git-ls-files.txt
+++ b/Documentation/git-ls-files.txt
@@ -219,9 +219,9 @@ followed by the  ("attr/<eolattr>").

 --format=<format>::
  A string that interpolates `%(fieldname)` from the result being shown.
- It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits
- interpolates to character with hex code `xx`; for example `%00`
- interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF).
+ It also interpolates `%%` to `%`, and `%xXX` where `XX` are hex digits
+ interpolates to character with hex code `XX`; for example `%x00`
+ interpolates to `\0` (NUL), `%x09` to `\t` (TAB) and %x0a to `\n` (LF).
  --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo`
  and `--eol`.
 \--::

base-commit: c2b3f2b3cdbf5ad9feb978dd367d77561a1271f7
-- 
2.44.0

Re: [PATCH] doc: fix hex code escapes in git-ls-files

[Junio C Hamano]

Jayson Rhynas <jayrhynas@gmail.com> writes:

> The --format option on the git-ls-files man page states that `%xx`
> interpolates to the character with hex code `xx`. This mirrors the
> documentation and behavior of `git for-each-ref --format=...`. However,
> in reality it requires the character with code `XX` to be specified as
> `%xXX`, mirroring the behaviour of  `git log --format`.

Given that no placeholder strings ls-files uses begin with two
characters that are valid hexadecimal, it is tempting to say that we
probably can teach strbuf_expand_literal() to grok %XX the same way
as %xXX for 256 cases where XX is hexadecimal, and do away with this
documentation update, and it would make things consistent.

Doing such a change is also almost trivial (see below).

But "git log --format" shares the code, and over there, %cd is a
placeholder that is committer datestamp, not a byte with value 205,
so that would not quite work.

> Signed-off-by: Jayson Rhynas <jayrhynas@gmail.com>
> ---
>  Documentation/git-ls-files.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index d08c7da8f4..58c529afbe 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -219,9 +219,9 @@ followed by the  ("attr/<eolattr>").
>
>  --format=<format>::
>   A string that interpolates `%(fieldname)` from the result being shown.
> - It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits
> - interpolates to character with hex code `xx`; for example `%00`
> - interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF).
> + It also interpolates `%%` to `%`, and `%xXX` where `XX` are hex digits
> + interpolates to character with hex code `XX`; for example `%x00`
> + interpolates to `\0` (NUL), `%x09` to `\t` (TAB) and %x0a to `\n` (LF).
>   --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo`
>   and `--eol`.

The change looks good.

Thanks.



[DONOTUSE-BROKEN] Allow %XX as a synonym for %xXX

 strbuf.c | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git i/strbuf.c w/strbuf.c
index 3d2189a7f6..3594e10d09 100644
--- i/strbuf.c
+++ w/strbuf.c
@@ -443,13 +443,13 @@ size_t strbuf_expand_literal(struct strbuf *sb, const char *placeholder)
 	case 'n':		/* newline */
 		strbuf_addch(sb, '\n');
 		return 1;
-	case 'x':
-		/* %x00 == NUL, %x0a == LF, etc. */
-		ch = hex2chr(placeholder + 1);
+	default:
+		/* %x00 == NUL, %x0a == LF, etc., with 'x' being optional */
+		ch = hex2chr(placeholder + (placeholder[0] == 'x'));
 		if (ch < 0)
 			return 0;
 		strbuf_addch(sb, ch);
-		return 3;
+		return 2 + (placeholder[0] == 'x');
 	}
 	return 0;
 }

Re: [PATCH] doc: fix hex code escapes in git-ls-files

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

>>  --format=<format>::
>>   A string that interpolates `%(fieldname)` from the result being shown.
>> - It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits
>> - interpolates to character with hex code `xx`; for example `%00`
>> - interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF).
>> + It also interpolates `%%` to `%`, and `%xXX` where `XX` are hex digits
>> + interpolates to character with hex code `XX`; for example `%x00`
>> + interpolates to `\0` (NUL), `%x09` to `\t` (TAB) and %x0a to `\n` (LF).
>>   --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo`
>>   and `--eol`.
>
> The change looks good.

I do not know what your MUA did to it, but this won't apply as a
patch.