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

[ZheNing Hu <adlternative@gmail.com>]

Phillip Wood <phillip.wood123@gmail.com> 于2022年6月19日周日 21:50写道：
>
> Hi ZheNing
>
> On 19/06/2022 10:13, ZheNing Hu via GitGitGadget wrote:
> > 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.
>

Yeah, it cares about index state. Having this feature, maybe we can
easier check index/work-tree state.

> > 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.
>

I think it's ok to remove it.

> > +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.
>

Sure...

> > +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?
>

...I think they are basically index cache_entry attributes, except eol
cares about both
worktree and index. I will fix them.

> > +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?
>

It is cache entry flags which include In-memory only flags and some
extended on-disk flags.

> > [...]
> > +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;
>  > [...]
> > +     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);
>

This piece of code is copying from ls-tree. Maybe we should fix it too.

> 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.
>

Just like ref-filter or something else does, it parses atoms
and then fills buffers with information. Maybe we need such performance
optimization later, but for now, it's just easier to implement this patch :)

> Best Wishes
>
> Phillip

Thanks

ZheNing Hu