Introduction

Git can track a file rename cleanly, but it does not store renames as a permanent first-class object in the way many people expect. Instead, Git primarily stores snapshots and later detects renames heuristically by comparing deleted content to added content.

That means renames usually work well, but history tools and diff output depend on similarity detection rather than on a magical “rename record.”

Use git mv or a Normal Filesystem Rename

From Git’s perspective, these two approaches are usually equivalent:

git mv old_name.txt new_name.txt

or:

mv old_name.txt new_name.txt
git add -A

git mv is mostly a convenience command. It stages the rename immediately, but Git can often detect the same rename later even if you moved the file with normal filesystem tools. So the command is helpful, but it is not the source of rename tracking correctness by itself.

How Git Detects Renames

Git rename detection is based on content similarity. If one file disappears and another appears with sufficiently similar content, Git reports that as a rename in commands like git diff or git log --follow.

That is why a rename plus a huge rewrite may stop looking like a rename. If the file changed too much, Git may see it as a delete and an add instead.

Inspect Renames in Diffs

Git can show rename detection in diff output.

git diff --find-renames

You can also adjust the similarity threshold:

git diff -M90%

A higher threshold means Git requires the old and new files to be more similar before calling it a rename.

Follow History Across a Rename

To view history for a file across renames, use:

git log --follow -- path/to/file

This is one of the most important commands for real-world rename handling because otherwise file history can appear to “start over” at the new name.

Rename Commits Are Easier to Read When Kept Clean

If possible, separate a rename from a large content rewrite.

A cleaner sequence is:

1. rename the file
2. commit the rename
3. make large edits in a later commit

That makes history, blame, and review tooling more likely to preserve the rename relationship. It also makes code review easier because reviewers can first verify the move, then inspect the behavioral changes separately.

Case-Only Renames Need Extra Care

On case-insensitive filesystems, renaming File.txt to file.txt can be awkward because the OS may treat them as the same path. In those cases, an intermediate temporary name is often safer.

git mv File.txt temp_name.txt
git mv temp_name.txt file.txt

This avoids confusing the working tree on platforms such as default Windows or macOS setups.

Common Pitfalls

• Assuming git mv is required for rename detection when Git can often infer the rename later.
• Renaming and heavily rewriting a file in one commit, which can reduce Git’s ability to detect the rename.
• Forgetting git log --follow and concluding that the old history was lost.
• Ignoring similarity thresholds when a rename is not detected as expected.
• Doing case-only renames naively on a case-insensitive filesystem.

Summary

• Git usually detects renames heuristically based on content similarity.
• 'git mv is convenient, but normal filesystem renames plus git add -A also work.'
• Large rewrites during the same commit can make rename detection less reliable.
• Use git log --follow to inspect history across a renamed path.
• Keep rename commits clean when you want history and review tools to behave well.