How to Rename File or Directory in Git (git mv Explained)

Renaming a file or directory in Git is a common task, but many users are unsure whether to use git mv or manual commands. When done correctly, Git can preserve file history and track changes accurately.

In this guide, you will learn all the ways to rename files and folders in Git, along with practical scenarios, common mistakes, and best practices.

Git Rename Cheat Sheet

Rename File or Directory in Git

Rename a file in Git

To rename a file in Git, use the git mv command which updates both the working directory and staging area.

git mv old_file.txt new_file.txt

Check the status to confirm:

git status

Commit the change:

git commit -m "Rename file old_file.txt to new_file.txt"

You can verify the rename using git diff and check history using git blame.

Rename a folder in Git

Renaming a folder works the same way:

git mv old_folder new_folder

Commit the change:

git commit -m "Rename folder old_folder to new_folder"

Rename a directory in Git

Folder and directory are treated the same in Git:

git mv old_directory new_directory

Verify the change:

git status

Preview before execution:

git mv -n old_directory new_directory

Rename multiple files in Git

To rename multiple files:

for file in *.txt; do
  git mv "$file" "new_$file"
done

Commit all changes:

git commit -m "Rename multiple files"

Use git commit message to write better commit messages.

Common Scenarios (Real-World Use Cases)

Rename file and commit in one step

You can rename and commit in one command:

git mv old.txt new.txt && git commit -m "Rename file old.txt to new.txt"

Push changes:

git push

Refer to git push for push scenarios.

Rename files in Git Bash

On Windows using Git Bash:

git mv file.txt renamed_file.txt

If case change is not detected:

git mv file.txt temp.txt
git mv temp.txt File.txt

Rename file in GitHub repository

To rename a file in GitHub UI:

1. Open the file in your repository
2. Click the edit icon
3. Change the filename
4. Commit the changes

Refer to Getting started with GitHub for repository basics.

Rename file in GitLab repository

To rename a file in GitLab UI:

1. Open the file in your project
2. Click Edit
3. Change the filename
4. Commit the changes

Refer to Getting started with GitLab for more details.

Rename File Without Losing History

Does Git track rename automatically

Git does not explicitly store rename operations. Instead, it detects renames based on file similarity during operations like git diff or git log. When you use git mv, Git stages the rename directly, making it easier to track.

Even if you rename a file manually using mv, Git can still detect the rename as long as the file content remains mostly unchanged. However, using git mv is recommended because it avoids ambiguity and ensures consistent tracking.

To understand how Git detects changes, refer to git diff command.

How to verify file history after rename

After renaming a file, you can verify that history is preserved using:

git log --follow new_file.txt

This command ensures you can trace changes made to the file even before it was renamed.

You can also inspect who modified specific lines using git blame command, which helps confirm that file history is intact after renaming.

Advanced Rename Cases

Rename case-sensitive files (Linux vs Windows issue)

On case-insensitive file systems such as Windows, renaming file.txt to File.txt may not be detected properly. Git may ignore the change because the filesystem treats both names as identical.

To handle this, use an intermediate rename:

git mv file.txt temp.txt
git mv temp.txt File.txt

This ensures Git registers the change correctly across all environments.

Rename when file already exists (force overwrite)

If the target filename already exists, Git will block the rename operation to prevent accidental overwrites.

You can force the rename using:

git mv -f old.txt existing.txt

Be cautious when using this option, as it will overwrite the destination file. Always verify changes using git status before committing.

Rename folder using git mv

Renaming a folder updates all files within that directory in a single operation:

git mv old_folder new_folder

Git stages all file movements automatically, which simplifies tracking and avoids multiple manual operations.

For removing or restructuring directories, refer to delete files or directories using git.

Rename after pushing to remote repository

If you rename a file after it has already been pushed, the process remains the same locally. Once committed, you need to push the changes:

git push

The remote repository will reflect the rename as a delete and add, but history is still preserved locally.

To understand how remote updates work, refer to git push examples.

Common Mistakes and Fixes

Git shows delete and new file instead of rename

This happens when Git cannot detect enough similarity between the old and new files. It treats the operation as a deletion and a new file creation.

To fix this:

• Use git mv instead of manual rename
• Avoid modifying file content during rename
• Stage changes properly before committing

Rename not detected in git diff

Git uses similarity detection to identify renames. If the file content changes significantly, rename detection may fail.

You can improve detection using:

git diff -M

This forces Git to detect renames based on similarity thresholds.

Case rename not working in Git

On Windows and macOS (default setups), case-only renames may not be recognized.

Solution:

• Use a temporary filename during rename
• Commit the intermediate change if required

This ensures compatibility across different operating systems.

Git add renamed file issue

If you rename a file manually using mv, Git may show it as deleted and untracked instead of renamed.

To fix this:

git add -A

This stages both the deletion and the new file, allowing Git to detect the rename correctly.

If staging issues persist, you can reset and retry using git unstage files.

Summary

Renaming a file or directory in Git is straightforward when using the git mv command, which ensures proper tracking and preserves file history. While manual renaming using standard shell commands is possible, it requires additional staging steps and may lead to confusion if not handled correctly.

Understanding how Git detects renames, handles case sensitivity, and manages changes across local and remote repositories helps avoid common issues. By following best practices and using the right commands, you can safely rename files and folders without breaking history or workflow.

Further Reading

• git mv Documentation
• git log Documentation
• git diff Documentation
• git rm Documentation
• git add Documentation
• git commit Documentation