SOLVED: How to rename file or directory in Git

git cheat sheet to rename file or directory

Renaming a file or directory in git preserves its history. There are two main ways to git rename file or directory. You can use the mv or git rm commands.

 

1. Rename file or directory using git mv command

Replace the old file or directory with the new one.

Advertisement
git mv <old file or directory> <new file or directory>

OR

override the existing file with the -f option.

git mv -f <old file or directory> <new file or directory>

OR

use the && separate when renaming files or folders on sensitive systems.

git mv <old file or folder> <new file or folder> && git mv <new file or folder> <old file or folder>

Before renaming the file, you can dry-run the mv command to peek into what would happen on successful command execution.

git mv -n <old file or directory> <new file or directory>

 

2. Rename file or directory git using git rm command

The three typical steps to undertake when renaming a file using the git rm are:

Advertisement

step~1: remove a file

git rm <tracked file>

step~2: create a new file

touch <file>

step~3: stage the new file

git add <file>

Those are the primary ways to git rename file or directory. What if you want to understand more about git file renaming? That is why you should dive into the following sections of this tutorial.

 

Three objects that play a massive role in git rename file or directory

On notifying git to monitor file modifications, the versions get tracked in three primary levels: tree, blob, and commit.

The tree is a parent to directories and files. A blob is a binary string of data containing file contents. In contrast, a commit is a unique class of information that determines how the contents of a file change at a particular timestamp.

Advertisement

Each of the three levels reference changes with a SHA1. A tree hash changes on adding directories. The hash of a blob changes when you modify the number of files. The files in the blob know when they were created and who created them.

Lastly, a commit hash changes on modifying file contents. For instance, the time of change, author, and reason for modifying the file.

For that reason, how you remove or move a file along the tree plays a massive role in git rename file or directory.

 

Using “git rm” and “git mv” vs “rm” and “mv” commands in git

Think of using Unix commands as chopping off blob contents without telling git the file's destination. Then, git cannot trace the whereabouts of the initial file. That breaks the link between the tree and history.

However, if you git remove or move a tracked file, the tree and the blob objects get updated of the change. However, history does not know what you just did until you make a commit.

 

How exactly does removing or moving a file leads to its renaming in git?

At the working directory

Git tracks changes at the working directory by the file's or directory's name. Moving or removing a file appears to git as a new file with a new name has been introduced while the old one has been deleted.

Advertisement

 

At the index

Removing an old file creates a space in the blob, and it will fill the gap with the new file unless you have updated history or the new file has content while the old one was empty.

That is why git status informs you that you have renamed a file when you have actually removed a file, created and staged another before committing the deletion change. The old file disappears with its content because the new file occupies the blob with new metadata.

On the other hand, moving a file implies relocating the blob while the file's metadata persists. That is why doing a cat on a new file reveals similar data to the old one.

 

In history

A commit hash is modified under both (file removing and moving) circumstances because the timestamp changes.

Let us set up a lab and practically see the above git rename file or directory magic.

 

Lab setup to practice git rename file or directory

I am creating a GitHub repository, git_rename.

Advertisement

SOLVED: How to rename file or directory in Git

Clone the repo and cd into it.

SOLVED: How to rename file or directory in Git

Make a file and directory with two files.

touch file1
​
mkdir old_directory
​
cd old_directory
​
touch f1 f2

Add contents to f1 then return to the root directory.

cat >> f1
​
A new line In f1
​
cd ..

Check the contents.

ls
​
ls old_directory
​
cat old_directory/f1

SOLVED: How to rename file or directory in Git

Stage, commit the changes, then check the history.

git add .
​
git commit -m "Second commit"
​
git log

SOLVED: How to rename file or directory in Git

Let us dive into the examples section, so we can practice git rename file or directory.

Advertisement

 

Example~1: Rename file or directory using git rm command

Git rm deletes a file from the repository using three key options.

Option~1: Using git rm command without any flag

git rm <file>

 

Option~2: Using git rm command recursively

git rm -r <file or directory>

OR

git rm -rf <file or directory>

Where -r stands for recursively, while -f represents force. Using --force instead of -f works too.

 

Option~3: Using git rm command with cached option

git rm --cached <file>

Let us apply the first option to remove file1. Check the status, delete the file then recheck the status.

git status
​
git rm file1
​
git status

SOLVED: How to rename file or directory in Git

 

Git recognizes the update and notifies the index to record the change as a delete operation. Let us create a new file and stage it to see what the index registers.

touch new_file
​
git add new_file
​
git status

SOLVED: How to rename file or directory in Git

 

Git notifies us that file1 got renamed to new_file. At this point, history has not accommodated the update until we commit the change. Let us commit the file to complete the transaction.

Advertisement
git commit -m "Git rename file or directory using git rm"

Would git rename the old file with the new file if the old (deleted) file had some contents? Give it a shot and drop a comment below this tutorial.

 

Example~2: Rename file or directory using git mv command

Since git rm may fail to rename a file or folder due to the change in metadata, use git mv as the alternative to renaming the file or folder.

Git mv works like Unix's mv command; the only difference is that the mv command works across the filesystem, whereas git mv is specific to the repository.

Let us use git mv to relocate the old_directory.

git status
​
git mv old_directory new_directory
​
git status

git rename file or directory

 

If new_directory exists in the repository, git may refuse the rename operation. Supply the -f option in that case.

git mv -f old_directory new_directory

OR

git mv old_directory new_directory && git mv new_directory old_directory

on sensitive systems such as macOS. Before that, you can dry-run the operation using the -n option.

git mv -n old_directory new_directory

SOLVED: How to rename file or directory in Git

 

Let us wrap it up by committing and pushing the changes.

git commit -m "Git rename file or directory with git mv"
​
git push

SOLVED: How to rename file or directory in Git

 

Conclusion

Rename file or directory is easy with git rm or git mv. It would be best to understand what happens at the tree, blob, and commit objects to determine why the outcome could be the unexpected one.

 

Didn't find what you were looking for? Perform a quick search across GoLinuxCloud

If my articles on GoLinuxCloud has helped you, kindly consider buying me a coffee as a token of appreciation.

Buy GoLinuxCloud a Coffee

For any other feedbacks or questions you can either use the comments section or contact me form.

Thank You for your support!!

Leave a Comment

X