git mv

What you will learn

• Understand the core purpose of git mv
• Master the basic usage and common options of git mv
• Rename or move tracked files while keeping the index in sync, which makes large refactors easier to stage consistently.
• Understand key concepts: Common examples
• Know when to use this feature and when to avoid it

git mv renames or moves a tracked file and stages that path change at the same time.

Start with a problem

You're working in a Git repository and need to perform a specific task — but you're not sure which command or option is the right fit, or what this command can and cannot do.

Common examples

git mv old-name.ts new-name.ts
git mv docs/guide.md docs/intro.md

When it helps most

• during rename-heavy refactors
• when you want file movement and staging to happen in one step

How to think about it

Git still reasons primarily about content plus paths. git mv is mainly a convenience command that keeps your working tree and index aligned cleanly.

Useful reminder

Git can often infer renames even if you use your shell mv first. The main value of git mv is clarity and staging convenience.

What problem this command solves in a workflow

git mv renames or moves a tracked file and stages the path change in one step. It keeps the working tree and index aligned, which is especially useful during rename-heavy refactors where you want file movement and staging to happen atomically.

Typical use cases

• Rename tracked files during large refactors so the path change is immediately staged.
• Move files between directories while keeping Git aware of the rename in a single operation.
• Use git mv --cached when you want to update the index path without touching the working tree filesystem.

Diagram view

Input

Tracked file pathNew destination pathIndex state

→git mv

Output

Renamed file on diskStaged rename in indexUpdated working tree

Git can often infer renames even after a plain `mv`, but `git mv` makes the intent explicit and stages immediately.

Special cases and boundaries

• git mv only works on tracked files; untracked files must be moved with the shell mv first.
• Git's rename detection means a shell mv followed by git add often produces the same result, so git mv is mainly a convenience.
• If the destination file already exists, git mv will refuse unless you force it, to avoid accidental overwrites.
• Uncommitted edits in a file being moved are carried along with the rename — the content does not change, only the path.

Try it yourself

1. Practice the git-mv command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Further reading

Keep going on the same topic:

• git-mergetool Tutorial
• git-notes Tutorial
• git-prune Tutorial