What does git add -n --ignore-missing actually do?

This seems simple enough, but I'm having a difficult time understanding the difference between the following commands:

git add -n 
and
git add -n --ignore-missing

I believe I understand what "git add -n" does in the sense that it is a dry run of "git add", meaning that it will tell the user what file changes would be added to the staging area (index) without actually adding anything to the staging area. I read the following description of the "git add -n" command in the online git documentation:

-n
--dry-run

Don’t actually add the file(s), just show if they exist and/or will be ignored.

By "will be ignored" I assumed that if "git add -n" does not show what it will do to a file that exists, then that file is being "ignored". I haven't come up with a circumstance where the command will literally display that a file will be ignored... yet. Mind you, I've only been working with Git for the past couple weeks.

Now, my confusion begins with the following description of "--ignore-missing":

--ignore-missing

This option can only be used together with --dry-run. By using this option the user can check if any of the given files would be ignored, no matter if they are already present in the work tree or not.

"...the user can check if any of the given files would be ignored"... But, I thought that's what "git add -n" does all by itself. I set up a repository where all files that match *.log are to be ignored. Yet, I don't see "git add -n" making any mention of any files with that extension unless it is already part of the repository. The same goes for "git add -n --ignore-missing".

I have been desperately searching for a way where this option provides any difference from the regular usage of "git add -n". I have a feeling that my understanding of "git add -n" is partially or fully incorrect, which worries me. So I'm hoping someone could elaborate and emphasize where I'm going wrong. Thanks to all those who can help!

Solution

You can git add -n --ignore-missing some.filename, and if some.filename is ignored by a gitignore policy, you will get the "The following paths are ignored by one of your .gitignore files" message and a non-zero exit status. This works even if there isn't actually a file named some.filename. Without --ignore-missing, you would instead get an error message about some.filename not existing.