Getting started with git rm command
Git rm is a command to delete unwanted files or folders. Despite its usefulness in cleaning a repository, it is one of the commands that often confuse users. For instance, is git rm similar to rm? In which situations should you use it? What are its alternatives?
If you seek answers to the above questions, you are in the right place. By the end of this tutorial, you will know how to maximize the full potential of the git rm command. First, here is an overview of what we will go through.
Use git rm to delete a file or folder from a filesystem
normally
git rm <file>
recursively delete a file
git rm -r <file>
or recursively delete a folder
git rm -rf <folder>
where -r stands for recursively.
Use git rm to remove a file or folder from the index
git rm --cached <file>
Git rm's typical alternatives are the git reset, rm, and d options. Before learning how to apply the commands instead of git rm, let us determine their differences.
What you should know before applying git rm
Using the git rm command effortlessly requires understanding the differences between
File System and Repository
The root of confusion between git rm and other commands is the failure to distinguish between a filesystem and a repository. Technically, a filesystem or repository implies the same thing. However, git's conventional naming system slightly contrasts the two terms.
The most straightforward way to distinguish a filesystem and a repository is that, in git, a filesystem is a parent to a repository.
While a filesystem refers to all files and folders, whether they are tracked or not, a repository often implies tracked files and folders. Simply put, think of the filesystem as the data, whereas the git repository is a meta-data, i.e, data about another data.
Untracked and Tracked files
An untracked file often has no relationship with a version control system. For instance, a file is untracked before initializing git.
git init
Running git init tells the version control system to be ready to take snapshots of your files and folders. But git does not track the files until you stage the files.
On staging the files and folders, they enter the index. Then, they become tracked files. And they are part of the repository. Beyond the index, the files become part of the history, upon committing the files' changes.
When managing the files, whether in the untracked or tracked stage, you may make a mistake that requires removing the files.
Since various commands can come into play at this point, you could be stranded on the best option to pick. However, after going through the following comparisons, that should not be a concern.
rm and git rm
The primary reason for git's existence is to have a safe, friendly system to restore your files if they disappear from the local computer. Having that mindset helps in distinguishing the rm command from git rm.
Although both rm and git rm discard files from the filesystem, git rm is a safer path to take. For instance, running
rm <file>
removes the file from the filesystem, and git does not remember anything about the file.
On the other hand, despite running git rm on file,
git rm <file>
you can still trace the files because they are part of the repository. You can check the traces in a branch, tag, or reflog.
So, the rm is a Unix command for discarding files or folders, whereas git rm is a git command for deleting tracked changes.
git rm and the "-d" option
Git rm removes tracked changes from the filesystem. On the other hand, the d option removes branches and tags.
git branch -d <branch name>
git branch -d <tag>
where -d stands for delete.
git rm and git reset
The (mixed) reset command does a similar role at the index as git rm with the cached command. Here, both commands undo changes on a file. For example, running
git rm --cached <file>
works as
git reset HEAD
Git reset can either be a mild or a destructive way to discard committed changes. Do a soft reset if you aim to remove changes from the history to index.
git reset --soft HEAD^
However, use a hard reset if you want to untrack a committed file then discard it from the repository and filesystem.
git reset --hard HEAD~N
It would be best to avoid the reset command on files already pushed to a remote because its disruptive nature causes a conflict error during subsequent pushes.
Those are the basics to get started using git rm. Let us set up a lab and practice the above commands.
Lab setup to practice git rm
I am creating a repository on GitHub called git_rm.
I copy the repository's URL and clone it locally. Navigate into the cloned repository.
cd git_rm
Create a file and folder with a file.
touch file mkdir dir cd dir touch file2 cd ..
Check progress.
ls git status git log
We have two files and a directory with a file. The index has a new untracked folder and a file, whereas the history has a commit.
Example~1: Remove a file or folder from the filesystem
Let us track before removing the above file from the filesystem.
git add . git rm file
You can also remove it recursively by supplying the -r option.
git rm -r file
However, git does not accept either method because we have not committed the new file.
Let us commit the file instead of forcing the removal. Then reattempt the removal.
git commit -m "Commit the new file before applying git rm on it"
The recursive option combined with the -f option removes a folder with file(s).
git rm -rf dir
Recheck the status.
ls git status
Git rm removed the file from the filesystem, but git remembers the files. And can tell us that it just got deleted.
Example~2: Remove a file from the index
Let us create another folder with a file.
mkdir second cd second touch file3 cd ..
Stage it.
git add .
Then unstage it with the --cached option.
git status
What did you notice?
Git thinks the newly staged folder is meant to rename the last deleted because it remembers the deleted files and folders until you make another commit.
Let us proceed and unstage the file.
git rm --cached second/file3
And recheck the status.
git status
Our file got untracked and is back to the working tree.
How to use git rm alternatives
The rm command
The rm command discards a file from the working tree. However, this time around, we cannot trace the file.
Let us discard the untracked folder entirely.
rm -rf second
Checking the status,
git status
we cannot trace the folder.
Git reset and git revert
Let us commit the deleted changes before creating or staging a new file.
git commit -m "Delete file and dir" touch file.txt git add file.txt git commit -m "Reset the file"
Log the history.
git log --oneline
And check the files.
ls git ls-files
We have four commits and two files.
Let us do a hard reset on the last three commits.
git reset --hard HEAD~3
Then recheck the history, status, and filesystem.
git log --oneline git status ls
Our files are unavailable.
Instead of using a hard reset, we can use a mixed reset to undo changes, as we would using the git rm command.
touch file git status git add . git status git reset HEAD git status
It is safe to use the reset on local changes. However, it would be best to avoid it when undoing changes on committed and pushed files. Instead, use the revert command.
git add . git commit -m "Revert the file" git push
Say we no longer need the latest commit and want to undo it. Let us revert it, recommit and push the changes.
git log git revert ae3aef5e1dca118bef2f888e5701d9a9d20ce2ba
Our default text editor prompts us for a new commit message. Let us accept the given message then close the editor. Next, push the changes and check the remote.
Conclusion
Git rm discards files and folders from a repository. It would help to prioritize it over the rm command or git reset hard when removing a file or folder from the filesystem. To achieve a similar effect at the index, use git rm with the cached option or its alternative: git reset mixed on the HEAD.
