Why are there two ways to unstage a file in Git?
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
See git docs.
Read more… Read less…
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 :)
git rm --cached <file>makes git stop tracking the file completely (leaving it in the filesystem, unlike plain
git reset HEAD <file>unstages any modifications made to the file since the last commit (but doesn't revert them in the filesystem, contrary to what the command name might suggest**). The file remains under revision control.
If the file wasn't in revision control before (i.e. you're unstaging a file that you had just
git added for the first time), then the two commands have the same effect, hence the appearance of these being "two ways of doing something".
* Keep in mind the caveat @DrewT mentions in his answer, regarding
git rm --cached of a file that was previously committed to the repository. In the context of this question, of a file just added and not committed yet, there's nothing to worry about.
** I was scared for an embarrassingly long time to use the git reset command because of its name -- and still today I often look up the syntax to make sure I don't screw up. (update: I finally took the time to summarize the usage of
git reset in a tldr page, so now I have a better mental model of how it works, and a quick reference for when I forget some detail.)
This thread is a bit old, but I still want to add a little demonstration since it is still not an intuitive problem:
me$ git status # On branch master # Changes to be committed: # (use "git reset HEAD <file>..." to unstage) # # new file: to-be-added # modified: to-be-modified # deleted: to-be-removed # me$ git reset -q HEAD to-be-added # ok me$ git reset -q HEAD to-be-modified # ok me$ git reset -q HEAD to-be-removed # ok # or alternatively: me$ git reset -q HEAD to-be-added to-be-removed to-be-modified # ok me$ git status # On branch master # Changes not staged for commit: # (use "git add/rm <file>..." to update what will be committed) # (use "git checkout -- <file>..." to discard changes in working directory) # # modified: to-be-modified # deleted: to-be-removed # # Untracked files: # (use "git add <file>..." to include in what will be committed) # # to-be-added no changes added to commit (use "git add" and/or "git commit -a")
git reset HEAD (without
-q) gives a warning about the modified file and its exit code is 1 which will be considered as an error in a script.
git checkout HEAD to-be-modified to-be-removed also works for unstaging, but removes the change completely from the workspace
Update git 2.23.0: From time to time, the commands change. Now,
git status says:
(use "git restore --staged <file>..." to unstage)
... which works for all three types of change
if you've accidentally staged files that you would not like to commit, and want to be certain you keep the changes, you can also use:
git stash git stash pop
this performs a reset to HEAD and re-applies your changes, allowing you to re-stage individual files for commit. this is also helpful if you've forgotten to create a feature branch for pull requests (
git stash ; git checkout -b <feature> ; git stash pop).
These 2 commands have several subtle differences if the file in question is already in the repo and under version control (previously committed etc.):
git reset HEAD <file>unstages the file in the current commit.
git rm --cached <file>will unstage the file for future commits also. It's unstaged untill it gets added again with
git add <file>.
And there's one more important difference:
- After running
git rm --cached <file>and push your branch to the remote, anyone pulling your branch from the remote will get the file ACTUALLY deleted from their folder, even though in your local working set the file just becomes untracked (i.e. not physically deleted from the folder).
This last difference is important for projects which include a config file where each developer on the team has a different config (i.e. different base url, ip or port setting) so if you're using
git rm --cached <file> anyone who pulls your branch will have to manually re-create the config, or you can send them yours and they can re-edit it back to their ip settings (etc.), because the delete only effects people pulling your branch from the remote.