Sometimes git suggests git rm --cached to unstage a file, sometimes git reset HEAD file. When should I use which?

D:\code\gt2>git init
Initialized empty Git repository in D:/code/gt2/.git/
D:\code\gt2>touch a
D:\code\gt2>git status
On branch master

Initial commit

Untracked files:
(use “git add <file>…” to include in what will be committed)

a
nothing added to commit but untracked files present (use “git add” to track)
D:\code\gt2>git add a
D:\code\gt2>git status
On branch master

Initial commit

Changes to be committed:
(use “git rm –cached <file>…” to unstage)

new file:   a

D:\code\gt2>git commit -m a
[master (root-commit) c271e05] a
0 files changed, 0 insertions(+), 0 deletions(-)
create mode 100644 a
D:\code\gt2>touch b
D:\code\gt2>git status
On branch master
Untracked files:
(use “git add <file>…” to include in what will be committed)

b
nothing added to commit but untracked files present (use “git add” to track)
D:\code\gt2>git add b
D:\code\gt2>git status
On branch master
Changes to be committed:
(use “git reset HEAD <file>…” to unstage)

new file:   b

git rm --cached <filePath> does not unstage a file, it actually stages the removal of the file(s) from the repo (assuming it was already committed before) but leaves the file in your working tree (leaving you with an untracked file).

git reset -- <filePath> will unstage any staged changes for the given file(s).

That said, if you used git rm --cached on a new file that is staged, it would basically look like you had just unstaged it since it had never been committed before.

Update git 2.24
In this newer version of git you can use git restore --staged instead of git reset. See git docs.