Renaming files in Git: the right way

Have you ever tried to rename a file in your projects and had a hard time adding the adjustment to a commit? This doesn’t just happen to you. In this pro-tip you will learn how to rename your files in git projects correctly to avoid headaches.

The problem with renaming a file without using git

Let’s say you decided to rename a file and, for simplicity’s sake, you decide to do it in the folder interface itself (or using the mv command in the terminal). After that you want to commit the name change and when you run the command git status you come across this situation:

Git status showing the file was deleted and another created

If you rename the file without using Git, Git “gets lost” and thinks that the original file was deleted and a new file was created as shown in the image above. Because of this behavior, you end up having to do two steps to commit the name change:

Add the deleted file;
Add the new file.

To make matters worse, it is not possible to add a “deleted” file without explicitly using the name of that file, which makes this whole process even more tedious, not to mention the weirdness of the phrase “add a deleted file”.

Let’s say you persevered, added the deleted file and added the new file and once again you run git status, and then git finally understands that it was a change in the file name, like so:

Git status showing the file was actually renamed

This is a relatively painless solution if you don’t need to do this often, but there is a better way.

Renaming files the right way in git

To begin, you need to resist the urge of renaming the file using the interface or the mv command alone and start using the command git mv. Using the same example as the case above, in which the file books.md was renamed to book.md, the command looks like this: