git mv: Renaming and Moving Files While Keeping History

Renaming or moving a tracked file is a common, everyday task — but doing it with your operating system's file explorer leaves Git seeing two separate, disconnected events: a deletion and a new untracked file. `git mv` handles the rename and its staging together in one clean command, though it's worth understanding that Git's rename detection is smart enough to figure out most renames either way.

Learning Objectives

Rename or move a tracked file using git mv in a single step.
Understand what git mv actually does internally (a staged delete + add).
Recognize that Git can detect renames automatically even without using git mv.
Verify a rename was staged correctly using git status.

Key Terms to Know Before Learning git mv

git mv: A command that renames or moves a tracked file and automatically stages that change in one step.
Rename detection: Git's ability to recognize, when viewing diffs or logs, that a file was renamed rather than deleted and separately re-added, based on content similarity.
Similarity index: A percentage Git calculates and displays in diff output, indicating how similar a renamed file's new content is to its old content.

How git mv Actually Works

Renaming a tracked file with `git mv` is straightforward:

```
git mv old-name.js new-name.js
```

This performs the file system rename and automatically stages the change — running `git status` immediately afterward shows it as a staged 'renamed' entry, ready for your next commit, with no separate `git add` step needed. `git mv` can also be used to move a file into a different directory:

```
git mv utils.js src/helpers/utils.js
```

Under the hood, `git mv` is technically just a convenient shortcut for two separate operations Git performs together: deleting the old path and adding the new one. This matters for understanding a subtlety that surprises many beginners: **Git doesn't actually store an explicit 'this file was renamed' record in its history at the object level.** Instead, Git compares content between commits and *detects* renames after the fact, based on how similar the old and new file content are. This is why manually renaming a file — using your OS's file explorer or a plain `mv` command — followed by `git add` for both the old (now-deleted) and new paths, produces essentially the same end result as using `git mv` directly: Git's diff and log tools will still recognize and display it as a rename, as long as the content is similar enough (there's an internal similarity threshold, commonly around 50%, that Git uses to decide whether to report something as a rename versus a plain delete-and-add).

This means `git mv` is mostly a matter of convenience — it combines what would otherwise be a manual `mv` (or file explorer drag) plus two separate `git add` commands into one single, tidy step. The practical benefit is simplicity and reduced room for error, not some unique tracking capability unavailable any other way. When you view history afterward with `git log --follow <new-path>`, Git will trace the file's history back through its renames, showing commits made even before the rename occurred — provided rename detection succeeded.

A quick way to confirm a rename was staged correctly is `git status`, which explicitly labels the change:

```
renamed: old-name.js -> new-name.js
```

git mv: Visual Walkthrough

Show a before/after file tree. BEFORE: 'src/utils.js'. Arrow labeled 'git mv src/utils.js src/helpers/utils.js' pointing to AFTER: 'src/helpers/utils.js'. Below, add a small annotated box showing what happens internally: 'Git stages: (1) delete src/utils.js, (2) add src/helpers/utils.js — later detected by Git's diff/log tools as a rename based on content similarity.'

git mv: Quick Reference Table

Action	Command	Staging Required Afterward?
Rename a file	git mv old.js new.js	No — staged automatically
Move a file to a new folder	git mv utils.js src/helpers/utils.js	No — staged automatically
Manual rename (OS/plain mv)	mv old.js new.js (outside Git)	Yes — requires git add old.js new.js
Trace history through a rename	git log --follow new.js	N/A — a log/inspection command

git mv: Command Syntax and Examples

# Rename a file and stage the change in one step
git mv old-name.js new-name.js
git status
# renamed:    old-name.js -> new-name.js

# Move a file into a subdirectory
git mv utils.js src/helpers/utils.js

# Equivalent manual approach (also works, Git detects the rename)
mv old-name.js new-name.js
git add old-name.js new-name.js

# View a file's full history, including commits from before it was renamed
git log --follow new-name.js

Breaking Down the git mv Example

`git mv old-name.js new-name.js` renames the file and immediately shows up in `git status` as a staged rename, ready to commit. Moving a file into a subdirectory works the same way, just with a new path as the destination. The manual equivalent — using a plain `mv` command followed by staging both the old and new paths — produces an effectively identical result, since Git's rename detection recognizes the change based on content similarity rather than the specific command used. `git log --follow new-name.js` demonstrates viewing a file's complete history, correctly tracing back through the rename to show commits made under its old name as well.

How git mv Is Used on Real Engineering Teams

Large refactoring efforts — such as reorganizing a project's folder structure — commonly use git mv extensively to relocate many files at once while keeping each change cleanly staged and reviewable.
Code review tools like GitHub automatically detect and specially display renamed files (often showing 'renamed from X to Y' with a similarity percentage) rather than a confusing full delete-and-add diff, directly relying on the same rename detection concept.
Engineers investigating the history of a file that has been renamed multiple times over a project's lifetime rely on git log --follow to trace its complete history back through each rename.
Teams renaming a project's primary branch or restructuring module folders as part of a migration often script git mv operations to ensure history remains traceable rather than appearing as unrelated deletions and additions.

git mv Interview Questions and Answers

Q1. What does git mv do, and is it strictly necessary to use it instead of a manual rename?

git mv renames or moves a tracked file and automatically stages the change in one step. It's a convenience, not a strict requirement — Git's rename detection can recognize a manual rename (using the operating system or a plain mv command, followed by staging both the old and new paths) just as well, based on how similar the file's content is before and after.

Q2. Does Git store an explicit record that a file was renamed?

No. Git's underlying model doesn't store an explicit 'rename' event. Instead, tools like git diff and git log detect renames after the fact by comparing content similarity between a deleted path and a newly added path, reporting it as a rename when that similarity exceeds an internal threshold.

Q3. How would you view a file's complete commit history, including changes made before it was renamed?

Use git log --follow <current-path>, which traces the file's history through detected renames, showing commits made under its previous name(s) as well, provided Git's rename detection succeeds based on content similarity.

git mv Quiz: Test Your Understanding

1. What does git mv old.js new.js do?

Only renames the file on disk, without staging anything
Renames the file and automatically stages the change
Creates a copy of the file under a new name
Permanently deletes old.js

Answer: B. Renames the file and automatically stages the change

Explanation: git mv performs the rename and stages it in a single step, so a follow-up git status immediately shows it as a staged 'renamed' entry.

2. How does Git actually detect that a file was renamed, at a technical level?

It stores an explicit 'renamed' flag in the commit object
It compares content similarity between a deleted path and a newly added path
It only detects renames performed with git mv, not manual renames
It relies on the file's original creation timestamp

Answer: B. It compares content similarity between a deleted path and a newly added path

Explanation: Git doesn't store rename events explicitly; tools like diff and log detect renames after the fact by comparing how similar the content of a deleted file is to a newly added one.

3. Which command shows a file's full history, including commits made before it was renamed?

git log --follow <path>
git show --renamed <path>
git blame --history <path>
git mv --log <path>

Answer: A. git log --follow <path>

Explanation: --follow tells git log to trace a file's history through Git's rename detection, continuing to show relevant commits made under the file's previous name(s).

git mv: Common Mistakes Beginners Make

Assuming a manual rename (outside git mv) won't be tracked properly by Git — rename detection works based on content similarity regardless of which method was used.
Forgetting that after a manual rename, both the old (deleted) and new (added) paths need to be staged with git add before committing.
Not using --follow with git log when investigating a renamed file's full history, and incorrectly concluding the file has no earlier history.
Believing Git permanently 'remembers' a rename as a distinct type of event — it's actually inferred fresh each time based on similarity, not stored explicitly.

git mv: Exam-Ready Quick Notes

git mv <old> <new>: renames/moves a file and stages the change automatically.
Git detects renames via content similarity, not an explicit stored event — manual renames work too if properly staged.
git log --follow <path>: traces a file's history through detected renames.

git mv: Key Takeaways

git mv is a convenient shortcut that renames a file and stages the change in one step, avoiding a separate manual staging process.
Git's rename detection works based on content similarity, meaning manual renames are recognized just as well as those made with git mv.
git log --follow is essential for viewing a renamed file's complete history, including commits from before the rename.

Frequently Asked Questions About git mv

Q1. What does git mv do?

It renames or moves a tracked file and automatically stages that change in one step, so it's immediately ready to be committed without needing a separate git add command.

Q2. Do I have to use git mv to rename a file, or can I just rename it manually?

You can rename it manually using your operating system or a plain mv command — Git will still detect it as a rename based on content similarity, as long as you stage both the old (deleted) and new (added) paths with git add afterward. git mv is simply a more convenient shortcut.

Q3. Does Git store an explicit record that a file was renamed?

No. Git compares content between a deleted path and a newly added path and infers a rename based on how similar they are — it doesn't keep a permanent, explicit 'renamed' marker in its underlying data model.

Q4. How do I see a file's history from before it was renamed?

Use git log --follow <current-file-path>, which traces the file's history through Git's rename detection, continuing to show commits made under its earlier name(s).

Q5. Can git mv move a file into a different folder, not just rename it?

Yes. git mv old-path new-path works for both simple renames and moving a file into a completely different directory — for example, git mv utils.js src/helpers/utils.js.

Summary

`git mv` renames or moves a tracked file and automatically stages the change in a single step, appearing in `git status` as a clearly labeled 'renamed' entry. Technically, this is a convenience — Git doesn't store an explicit 'rename' event internally; instead, tools like `git diff` and `git log` detect renames after the fact by comparing content similarity between a deleted path and a newly added one, which means a manual rename (followed by staging both paths) is recognized just as well. To view a file's complete history across renames, use `git log --follow <path>`, which traces commits made under the file's previous name(s) as well.