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 rest

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)