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

From: Elijah Newren <newren@gmail.com>
Date: Jan 14, 2023, 19:42 UTC
Message-ID: <CABPp-BFuZK2yap_VXWPo8qHvJ+E9V7v2UAZ9tAaQcX8zc-daDA@mail.gmail.com>
In-Reply-To: <CAOLTT8Qx6chcA7MEY9Hzeq9U5pfR-fC8aOxhZMvYvi8ZtQeVdA@mail.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写道：

[...]

Show 15 quoted lines

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

Show 30 quoted lines

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