git mv

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

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.