Why are there two ways to unstage a file in Git?

Question

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

EDIT:

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 # 

Answer 1

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.

Answer 2

git rm --cached is used to remove a file from the index. In the case where the file is already in the repo, git rm --cached will remove the file from the index, leaving it in the working directory and a commit will now remove it from the repo as well. Basically, after the commit, you would have unversioned the file and kept a local copy.

git reset HEAD file ( which by default is using the --mixed flag) is different in that in the case where the file is already in the repo, it replaces the index version of the file with the one from repo (HEAD), effectively unstaging the modifications to it.

In the case of unversioned file, it is going to unstage the entire file as the file was not there in the HEAD. In this aspect git reset HEAD file and git rm --cached are same, but they are not same ( as explained in the case of files already in the repo)

To the question of Why are there 2 ways to unstage a file in git? - there is never really only one way to do anything in git. that is the beauty of it :)