@matheusbsbs / matheus-bagliano / commits / 2b02d2df2b

ls-files: clarify descriptions of file selection options

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@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Elijah Newren committed Jan 13, 2023 at 04:41 UTC 2b02d2df2bc38048ca70c82024834995624c2f4d
1 file changed +24 -13
Documentation/git-ls-files.txt
+24 -13
@@ -29,21 +29,26 @@ This merges the file listing in the index with the actual working
29 directory list, and shows different combinations of the two.
30
31 One or more of the options below may be used to determine the files
32 -shown:
32 +shown, and each file may be printed multiple times if there are
33 +multiple entries in the index or multiple statuses are applicable for
34 +the relevant file selection options.
35
36 OPTIONS
37 -------
38 -c::
39 --cached::
38 - Show cached files in the output (default)
40 + Show all files cached in Git's index, i.e. all tracked files.
41 + (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo
42 + options are specified.)
43
44 -d::
45 --deleted::
42 - Show deleted files in the output
46 + Show files with an unstaged deletion
47
48 -m::
49 --modified::
46 - Show modified files in the output
50 + Show files with an unstaged modification (note that an unstaged
51 + deletion also counts as an unstaged modification)
52
53 -o::
54 --others::
@@ -51,11 +56,14 @@ OPTIONS
56
57 -i::
58 --ignored::
54 - Show only ignored files in the output. When showing files in the
55 - index, print only those matched by an exclude pattern. When
56 - showing "other" files, show only those matched by an exclude
57 - pattern. Standard ignore rules are not automatically activated,
58 - therefore at least one of the `--exclude*` options is required.
59 + Show only ignored files in the output. Must be used with
60 + either an explicit '-c' or '-o'. When showing files in the
61 + index (i.e. when used with '-c'), print only those files
62 + matching an exclude pattern. When showing "other" files
63 + (i.e. when used with '-o'), show only those matched by an
64 + exclude pattern. Standard ignore rules are not automatically
65 + activated, therefore at least one of the `--exclude*` options
66 + is required.
67
68 -s::
69 --stage::
@@ -64,19 +72,22 @@ OPTIONS
72 --directory::
73 If a whole directory is classified as "other", show just its
74 name (with a trailing slash) and not its whole contents.
75 + Has no effect without -o/--others.
76
77 --no-empty-directory::
78 Do not list empty directories. Has no effect without --directory.
79
80 -u::
81 --unmerged::
73 - Show unmerged files in the output (forces --stage)
82 + Show information about unmerged files in the output, but do
83 + not show any other tracked files (forces --stage, overrides
84 + --cached).
85
86 -k::
87 --killed::
77 - Show files on the filesystem that need to be removed due
78 - to file/directory conflicts for checkout-index to
79 - succeed.
88 + Show untracked files on the filesystem that need to be removed
89 + due to file/directory conflicts for tracked files to be able to
90 + be written to the filesystem.
91
92 --resolve-undo::
93 Show files having resolve-undo information in the index