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.
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:
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.
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.
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.
Clone the repo and cd into it.
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
Stage, commit the changes, then check the history.
git add . git commit -m "Second commit" git log
Let us dive into the examples section, so we can practice git rename file or directory.
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
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
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.
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
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
Let us wrap it up by committing and pushing the changes.
git commit -m "Git rename file or directory with git mv" git push
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.
