`git checkout my_branch` does something else that is quite different: it changes the current branch!
Also, `git checkout my_branch` is very different from `git checkout my_branch -- .`
I strongly dislike the double duty of `checkout`. It's made worse by the fact that `git checkout my_branch` will never lose uncommitted changes, while as `git checkout files` will.
It changes the current branch as it brings in clean files from that branch. Bringing in specific clean files from another branch is a special case of bringing in all clean files from another branch. I look at the current HEAD pointer being changed as a side effect when used without file arguments as it simply changing another file: the HEAD symlink. Think of the HEAD symlink as existing above your target commit (and it kind of does) and it makes a lot of sense.
But regardless: the goal of git checkout without file arguments is something you have to have, and if you then ask yourself what tool should implement just the tiny bit of functionality of reverting changes adding a separate command for that seems awkward when that is 99% of what git checkout is doing.
I feel you are over defending git. There is effectively two commands here, why not just give them different names?
The man page starts "switch branches or restore working tree files", which sounds like ramming two things together. Then the manual has to have a special section on how to disambiguate the two uses (files and branches). It would be less work to have an unambiguous command.
Perhaps, at least, make the -- separating files and branches mandatory (so you have to start -- always with files)
Also, `git checkout my_branch` is very different from `git checkout my_branch -- .`
I strongly dislike the double duty of `checkout`. It's made worse by the fact that `git checkout my_branch` will never lose uncommitted changes, while as `git checkout files` will.