Re: [PATCH v2] ls-files: introduce "--format" option

From: Phillip Wood <phillip.wood123@gmail.com>
Date: Jun 19, 2022, 13:50 UTC
Message-ID: <44f572b8-6cef-fad4-04c0-3cbb79db5bf9@gmail.com>
In-Reply-To: <pull.1262.v2.git.1655629990185.gitgitgadget@gmail.com>

Hi ZheNing

On 19/06/2022 10:13, ZheNing Hu via GitGitGadget wrote:

Show 9 quoted lines

> From: ZheNing Hu <adlternative@gmail.com>
> 
> Add a new option --format that output index enties
> informations with custom format, taking inspiration
> from the option with the same name in the `git ls-tree`
> command.
> 
> --format cannot used with -s, -o, -k, --resolve-undo,
> --deduplicate and --debug.

I think this is an interesting feature that provides functionality that is not available by feeding index entries into cat-file.

Show 54 quoted lines

> Signed-off-by: ZheNing Hu <adlternative@gmail.com>
>   Documentation/git-ls-files.txt |  51 ++++++++++++-
>   builtin/ls-files.c             | 130 ++++++++++++++++++++++++++++++++-
>   t/t3013-ls-files-format.sh     | 130 +++++++++++++++++++++++++++++++++
>   3 files changed, 307 insertions(+), 4 deletions(-)
>   create mode 100755 t/t3013-ls-files-format.sh
> 
> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> index 0dabf3f0ddc..9a88c92f1ad 100644
> --- a/Documentation/git-ls-files.txt
> +++ b/Documentation/git-ls-files.txt
> @@ -20,7 +20,7 @@ SYNOPSIS
>   		[--exclude-standard]
>   		[--error-unmatch] [--with-tree=<tree-ish>]
>   		[--full-name] [--recurse-submodules]
> -		[--abbrev[=<n>]] [--] [<file>...]
> +		[--abbrev[=<n>]] [--format=<format>] [--] [<file>...]
>   
>   DESCRIPTION
>   -----------
> @@ -192,6 +192,13 @@ followed by the  ("attr/<eolattr>").
>   	to the contained files. Sparse directories will be shown with a
>   	trailing slash, such as "x/" for a sparse directory "x".
>   
> +--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).
> +	--format cannot be combined with `-s`, `-o`, `-k`, `--resolve-undo` and
> +	`--debug`.
>   \--::
>   	Do not interpret any more arguments as options.
>   
> @@ -223,6 +230,48 @@ 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.
>   
> +It is possible to print in a custom format by using the `--format`
> +option, which is able to interpolate different fields using
> +a `%(fieldname)` notation. For example, if you only care about the
> +"objectname" and "path" fields, you can execute with a specific
> +"--format" like
> +
> +	git ls-files --format='%(objectname) %(path)'
> +
> +FIELD NAMES
> +-----------
> +Various values from structured fields can be used to interpolate
> +into the resulting output. For each outputting line, the following
> +names can be used:
> +
> +tag::
> +	The tag of file status.

The documentation for -t strong discourages its use, so I wonder if we really want to expose it here.

Show 8 quoted lines

> +objectmode::
> +	The mode of the object.
> +objectname::
> +	The name of the object.
> +stage::
> +	The stage of the file.
> +eol::
> +	The line endings of files.

Every other option refers to either a "file" or "object" but here we have "files". Looking at the implementation below this will print the line ending from both the index and the worktree, it would be useful to clarify that here.

> +path::
> +	The pathname of the object.
> +ctime::
> +	The create time of file.

It is not clear from this whether this (and all the file attributes below) are coming from the worktree or the index or both like eol?

Show 14 quoted lines

> +mtime::
> +	The modify time of file.
> +dev::
> +	The ID of device containing file.
> +ino::
> +	The inode number of file.
> +uid::
> +	The user id of file owner.
> +gid::
> +	The group id of file owner.
> +size::
> +	The size of the file.
> +flags::
> +	The flags of the file.

What are the flags?

Show 8 quoted lines

> [...]  
> +static size_t expand_show_index(struct strbuf *sb, const char *start,
> +			       void *context)
> +{
> +	struct show_index_data *data = context;
> +	const char *end;
> +	const char *p;
> +	unsigned int errlen;

 > [...]

Show 5 quoted lines

> +	else if (skip_prefix(start, "(flags)", &p))
> +		strbuf_addf(sb, "flags: %x", data->ce->ce_flags);
> +	else {
> +		errlen = (unsigned long)len;
> +		die(_("bad ls-files format: %%%.*s"), errlen, start);

errlen is declared as an unsigned int, but you cast len which is a size_t to unsigned long when assigning to errlen. Then errlen is used where a signed int is required by die. There is also a style violation as if any branch of an if needs braces then they should all be braced. I think that the best solution would be to drop errlen and just write

	else
		die(_("bad ls-files format: %%%.*s"), (int)len, start);

It would be interesting to check the performance of this implementation on a large repository as it is doing a lot of branching inside a loop. I don't think we should change it unless it turns out to be a problem. Then we could try switching on the first character of the format specifier or some other optimization.

Best Wishes

Phillip