Difference between "git checkout <filename>" and "git checkout -​- <filename>"

Question

The special "option" -- means "treat every argument after this point as a file name, no matter what it looks like." This is not Git-specific, it's a general Unix command line convention. Normally you use it to clarify that an argument is a file name rather than an option, e.g.

rm -f      # does nothing
rm -- -f   # deletes a file named "-f"

git checkout¹ also takes -- to mean that subsequent arguments are not its optional "treeish" parameter specifying which commit you want.

So in this context it's safe to use -- always, but you need it when the file you want to revert has a name that begins with -, or is the same as the name of a branch. Some examples for branch/file disambiguation:

git checkout README     # would normally discard uncommitted changes
                        # to the _file_ "README"

git checkout master     # would normally switch the working copy to
                        # the _branch_ "master"

git checkout -- master  # discard uncommitted changes to the _file_ "master"

and option/file disambiguation:

git checkout -p -- README  # interactively discard uncommitted changes
                           # to the file "README"

git checkout -- -p README  # unconditionally discard all uncommitted
                           # changes to the files "-p" and "README"

I'm not sure what you do if you have a branch whose name begins with -. Perhaps don't do that in the first place.

---

¹ in this mode; "checkout" can do several other things as well. I have never understood why git chose to implement "discard uncommitted changes" as a mode of the "checkout" subcommand, rather than "revert" like most other VCSes, or "reset" which I think might make more sense in git's own terms.

Anything following the -- is treated as a filename (not as a program argument). This is important if, for example, you have filenames which start with dashes.