git mv
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>Examples
Rename a file
git mv app.js cart.jsRenames the file and stages the rename.
Move into a folder
git mv cart.js src/cart.jsMoves the file into an existing folder.
History after a rename
git log --follow cart.jsFollows the history back through the rename.
Workflow Examples
git mv app.js cart.jsRename and stage
git statusShows "renamed: app.js -> cart.js"
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
Not directly: it compares content between commits and detects the rename.
Yes: git mv src lib renames the folder and every file in it.