Why does git ls-files --ignore require exclude patterns?

Question

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.

Answer 1

First of all let me make sure you are not confusing --ignored with --other.

--other 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 --other --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 --other would output while --exclude filters the output after the listing is done (or at least that's the observed behavior)¹.

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 --other --exclude=*.o --ignored

would print all untracked files that do match *.o.

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