Why does `git reset --hard HEAD~X` leave untracked files behind?

Question

From git reset --hard HEAD leaves untracked files behind:

When I run git reset --hard HEAD, it's supposed to reset to a pristine version of what you pulled, as I understand it. Unfortunately, it leaves files lying around, as a git status shows a big list of untracked files.

How do you tell git "Just bring it back to EXACTLY what was in the last pull, nothing more, nothing less"?

To get rid of these files I have to run git clean -df.

Can somebody please explain why it works this way and which files will become untracked?

Answer 1

Updated per notes in the comments.

Last question first:

which files will become untracked?

None. But files that are already untracked should remain untracked and not be affected. This is consistent with behavior of most git commands (except those that explicitly affect untracked files).

I say should remain untracked, though, because there is one case where even that's not true: If the commit to which you're resetting has a file at the same path as your current untracked file, then the work tree version is irreversibly clobbered. This is very un-git behavior and IMO is a bug, but there it is.

Can somebody please explain why it works this way[?]

Because if git were to implicitly remove or modify an untracked file, you would have no way to recover what that file looked like before git messed with it. If you wanted the file under git's control, git assumes you would've added and maybe committed it. Since you haven't (the file is untracked), git usually won't mess with it unless you tell it clearly that it should.

So back to the premise of the original question:

When I run git reset --hard HEAD, it's supposed to reset to a pristine version of what you pulled, as I understand it

Nope. The docs are clear that only the tracked state is reverted.