Elijah Newren via GitGitGadget <gitgitgadget@xxxxxxxxx> 于2023年1月13日周五 12:41写道： > > From: Elijah Newren <newren@xxxxxxxxx> > > The previous descriptions of the file selection options were very easy > to misunderstand. For example: > > * "Show cached files in the output" > This could be interpreted as meaning "show files which have been > modified and git-add'ed, i.e. files which have cached changes > relative to HEAD". > > * "Show deleted files" > This could be interpreted as meaning "for each `git rm $FILE` we > ran, show me $FILE" > > * "Show modified files" > This could be interpreted as meaning "show files which have been > modified and git-add'ed" or as "show me files that differ from HEAD" > or as "show me undeleted files different from HEAD" (given that > --deleted is a separate option), none of which are correct. > > Further, it's not very clear when some options only modify and/or > override other options, as was the case with --ignored, --directory, and > --unmerged (I've seen folks confused by each of them on the mailing > list, sometimes even fellow git developers.) > > Tweak these definitions, and the one for --killed, to try to make them > all a bit more clear. Finally, also clarify early on that duplicate > reports for paths are often expected (both when (a) there are multiple > entries for the file in the index -- i.e. when there are conflicts, and > also (b) when the user specifies options that might pick the same file > multiple times, such as `git ls-files --cached --deleted --modified` > when there is a file with an unstaged deletion). > > Signed-off-by: Elijah Newren <newren@xxxxxxxxx> > --- > Documentation/git-ls-files.txt | 37 ++++++++++++++++++++++------------ > 1 file changed, 24 insertions(+), 13 deletions(-) > > 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. > 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:: > @@ -51,11 +56,14 @@ OPTIONS > > -i:: > --ignored:: > - Show only ignored files in the output. When showing files in the > - index, print only those matched by an exclude pattern. When > - showing "other" files, show only those matched by an exclude > - pattern. Standard ignore rules are not automatically activated, > - therefore at least one of the `--exclude*` options is required. > + Show only ignored files in the output. Must be used with > + either an explicit '-c' or '-o'. When showing files in the > + index (i.e. when used with '-c'), print only those files > + matching an exclude pattern. When showing "other" files > + (i.e. when used with '-o'), show only those matched by an > + exclude pattern. Standard ignore rules are not automatically > + activated, therefore at least one of the `--exclude*` options > + is required. > > -s:: > --stage:: > @@ -64,19 +72,22 @@ OPTIONS > --directory:: > If a whole directory is classified as "other", show just its > name (with a trailing slash) and not its whole contents. > + Has no effect without -o/--others. > > --no-empty-directory:: > Do not list empty directories. Has no effect without --directory. > > -u:: > --unmerged:: > - Show unmerged files in the output (forces --stage) > + Show information about unmerged files in the output, but do > + not show any other tracked files (forces --stage, overrides > + --cached). > > -k:: > --killed:: > - Show files on the filesystem that need to be removed due > - to file/directory conflicts for checkout-index to > - succeed. > + Show untracked files on the filesystem that need to be removed > + due to file/directory conflicts for tracked files to be able to > + be written to the filesystem. > > --resolve-undo:: > Show files having resolve-undo information in the index > -- > gitgitgadget >
