Why does git ls-files --ignore require exclude patterns?
git
Solution
First of all let me make sure you are not confusing `--ignored` with `--others`.
`--others` is the option you would give to list untracked files. From the manual of `git-ls-files` (emphasis mine):
`-o, --others`
Show other (i.e. untracked) files in the output
That said, let's see what `--ignored` does. Regardless of what you are listing, whether it's tracked files, untracked files, modified files etc, you may exclude some files from the output. Think of it as a free `grep -v` automatically done on the output. For example:
git ls-files --others --exclude=*.o
will list all untracked files that do not match `*.o`. The exclude pattern has nothing to do with `.gitignore`. Indeed, `.gitignore` determines what `--others` would output while `--exclude` filters the output after the listing is done (or at least that's the observed behavior)1.
Now `--ignored` simply reverts the output. So what was excluded by `exclude=` will be printed instead and what was not excluded would be omitted. Therefore, for example:
git ls-files --others --exclude=*.o --ignored
would print all untracked files that do match `*.o`.
1 Not exactly like that, `--exclude` only filters untracked files, so if you are listing tracked files, `--exclude` wouldn't exclude anything. However, with `--ignored` it would list files that should have been excluded. It's a bit weird.
Conclusion: `--ignored` would basically revert the exclude pattern given in the command line. By default, the exclude pattern is empty (you see everything), so `--ignored` without any exclude patterns results in everything being omitted. This is never useful and that's why an exclude pattern is required for `--ignored` to work.
Since `--exclude-standard` was mentioned, I would like to expand on that too. `--exclude-standard` would add ignored patterns (such as written in `.gitignore`) as exclude patterns in the listing too. So think about the following command:
git ls-files --ignored --exclude-standard
At first, this command lists all tracked files. Then given the `--ignored` command, it will only print those files that match the exclude pattern. Given `--exclude-standard`, effectively files that match the patterns in `.gitignore` will be printed. BUT those are the files that you kept untracked. So effectively, you will see nothing. The only case you would see something is if you are tracking files that you have also mentioned to be ignored in `.gitignore`.
In other words, if that command outputs anything, it means you have told git to ignore certain files, but you have violated your own rules and added them to the repository anyway.
Other interesting commands could be:
git ls-files --others --exclude-standard
Shows all untracked files that you did not specify in `.gitignore`. You would also see these files in `git status`.
git ls-files --others --ignored --exclude-standard
Shows all untracked files that you successfully managed to ignore with `.gitignore`. In other words, (assuming the previous query is empty, i.e. there are no unignored untracked files) this shows all files that are in the current directory which don't belong to the repository. This is useful to check for files that shouldn't have been ignored and must be put in repository.
Problem
What is the logic behind the requirement to use an exclude pattern with the command `git ls-files --ignored`? From `git help ls-files`: `-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.