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

[ZheNing Hu <adlternative@gmail.com>]

Elijah Newren <newren@gmail.com> 于2023年1月15日周日 03:42写道：
>
> 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.
>

Well, you are right. It may be better to be concise here, telling users too
much will make it difficult to read.

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

I think it's fine to do this or not.

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