How to rename a file in Git

This guide will explain how to rename a file in Git, including how to ensure the file's history is preserved and what to consider when renaming files in a shared repository.

Understanding Git's handling of renamed files

Git does not explicitly track file renaming as a unique action; instead, it detects renaming through file deletions and additions that occur in the same commit. When you rename a file, Git will typically recognize the rename if the file retains a significant portion of its original content.

Step-by-step process to rename a file in Git

Here’s how you can rename a file in Git using the command line:

1. Open your terminal.

   • Ensure you are in the root of your Git repository.

2. Rename the file using the git mv command.

   • This command takes two arguments: the current file name and the new file name.
   Terminal

   git mv oldfilename.txt newfilename.txt
   
   

   • This command performs two operations: it renames the file in your working directory and stages the change for commit.

3. Check the status.

   • After renaming the file, you can use git status to see the change reflected in the staging area.
   Terminal

   git status
   
   

   • The output will show that the file has been renamed.

4. Commit the change.

   • Commit the rename to your repository.
   Terminal

   git commit -m "Rename oldfilename.txt to newfilename.txt"
   
   

Other options

There are a few situations where git mv will not work, such as if the file is already tracked under a new name in your IDE, or you're scripting renames in bulk. In such cases, you can manually rename the file and then inform Git about the change:

1. Rename the file manually in your file system or IDE.

2. Use git add to stage the old and new filenames.

   • Add both the deleted (old) file and the new file to the staging area:
   Terminal

   git add oldfilename.txt newfilename.txt
   
   

3. Commit the changes.

   • Similar to using git mv, commit the change to ensure the history is maintained.
   Terminal

   git commit -m "Manually rename oldfilename.txt to newfilename.txt"
   
   

For more information, see the official Git documentation.