Elijah Newren <newren@xxxxxxxxx> 于2023年1月15日周日 03:42写道： > > On Sat, Jan 14, 2023 at 12:21 AM ZheNing Hu <adlternative@xxxxxxxxx> wrote: > > > > Elijah Newren via GitGitGadget <gitgitgadget@xxxxxxxxx> 于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!
