git mv

Basic Snapshotting

Move or rename a file


The 'git mv' command renames or moves a tracked file and stages the change in one step. It is the same as renaming the file yourself and running git add on the old and new names. Git does not store renames: it detects them by comparing content, so git log --follow can still show the file's history across the rename.

Synopsis

git mv [-v] [-f] [-n] [-k] <source> <destination>
[ ] optional| or<arg> placeholder... repeatable--flag option

Examples

Rename a file

git mv app.js cart.js

Renames the file and stages the rename.


Move into a folder

git mv cart.js src/cart.js

Moves the file into an existing folder.


History after a rename

git log --follow cart.js

Follows the history back through the rename.

Workflow Examples

1
git mv app.js cart.js

Rename and stage

2
git status

Shows "renamed: app.js -> cart.js"

3
git commit -m "Rename app.js to cart.js"

Commit

Troubleshooting

fatal: destination exists

Cause: A file with the new name already exists

Pick another name, or use -f to overwrite it

fatal: not under version control

Cause: The source file is untracked

Rename it normally, or git add it first

Tips & Pitfalls

Best Practices

  • ✓Commit a rename separately from big edits, so Git recognises it as a rename.
  • ✓Use git log --follow <file> to see history across renames.

Common Mistakes

  • ✗Renaming in the file explorer and committing only the new file — the old one is still tracked.
  • ✗Changing only the letter case on Windows or macOS without git mv, which Git may not notice.
  • ✗Renaming and heavily editing a file in the same commit, so Git no longer detects the rename.

FAQ

A:

Not directly: it compares content between commits and detects the rename.

A:

Yes: git mv src lib renames the folder and every file in it.