Re: [PATCH 2/4] ls-files: clarify descriptions of file selection options

[Elijah Newren <newren@gmail.com>]

On Sat, Jan 14, 2023 at 12:21 AM ZheNing Hu <adlternative@gmail.com> wrote:
>
> Elijah Newren via GitGitGadget <gitgitgadget@gmail.com> 于2023年1月13日周五 12:41写道：
[...]
> > diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt
> > index cb071583f8b..f89ab1bfc98 100644
> > --- a/Documentation/git-ls-files.txt
> > +++ b/Documentation/git-ls-files.txt
> > @@ -29,21 +29,26 @@ This merges the file listing in the index with the actual working
> >  directory list, and shows different combinations of the two.
> >
> >  One or more of the options below may be used to determine the files
> > -shown:
> > +shown, and each file may be printed multiple times if there are
> > +multiple entries in the index or multiple statuses are applicable for
> > +the relevant file selection options.
> >
>
> `--deduplicate` option can be used to remove deduped output.

Yes, I'm aware.

If you're suggesting adding this text at this point in the document,
it occurred to me already, but I chose not to put it here.  The reason
is that this is a brief synopsis.  The "relevant file selection
options" of this brief synopsis could also be expanded to mention what
they are or what the default selection is or whatever.  But folks can
read on to learn that `deduplicate` can be used to remove duplicate
options.  Likewise, anyone who reads the text about "relevant file
selections" and wants to learn more is inclined to read on to the
other options to find out.

In contrast, no one will be motivated to read on to find out that
files can be printed multiple times if we don't mention it right here.
And they are likely to get confused when it happens, thinking it is a
bug (in fact, I can point out emails from the archives where that has
happened).  Without mentioning the possibility of multiple files at
this point, we have a discoverability problem.

There is no similar discoverability and negative-surprise problem I
can think of by omitting other details, so there is no need to expand
this brief synopsis any further.

The one place we could potentially change thing that might help, is
moving the text about -c being the default from under the -c option
and putting it here.  That's a toss-up to me, but for now I elected to
keep it where it is.

> >  OPTIONS
> >  -------
> >  -c::
> >  --cached::
> > -       Show cached files in the output (default)
> > +       Show all files cached in Git's index, i.e. all tracked files.
> > +       (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo
> > +       options are specified.)
> >
> >  -d::
> >  --deleted::
> > -       Show deleted files in the output
> > +       Show files with an unstaged deletion
> >
>
> This is a nice fix: make it clear to the user that only files in the
> working tree are deleted, not in the index.
>
> >  -m::
> >  --modified::
> > -       Show modified files in the output
> > +       Show files with an unstaged modification (note that an unstaged
> > +       deletion also counts as an unstaged modification)
> >
>
> Good to mention that deleted files are also modified, otherwise no one
> looking at the documentation would know that.
>
> >  -o::
> >  --others::
[...]

Thanks for taking a look!