Git mv: rename or move a file
git mv renames or moves a file while keeping Git tracking. Cleaner than doing mv + git add, it preserves the history.
What is git mv?
git mv is a shortcut to rename or move a file while informing Git of the change. It's equivalent to doing mv + git add in a single command.
The advantage: Git understands it's a rename, not a deletion + creation. The file history is better preserved.
Git mv syntax
git mv old newRename a file
git mv file directory/Move to another directory
git mv -f File.js file.jsForce rename (useful for case changes)
Git mv in practice
Rename or move files cleanly.
Rename a file
Move files
git mv vs mv + git add
git mv
One command: moves and stages in one step. Git immediately detects the rename.
mv + git add
Two commands: move then stage manually. Git still detects the rename.
Common mistakes with git mv
Renaming case on macOS/Windows
These systems are case-insensitive. git mv Header.js header.js may fail. Use -f to force or do a two-step rename via a temporary name.
Moving to a directory that doesn't exist
git mv does not create directories automatically. Create the destination directory first with mkdir -p.
Forgetting to update imports
Renaming a file does not update references in your code (imports, require). Remember to update all files that use the old path.
Part of the Git Advanced guide
GitQuest is created by Anaïs (nouvelle fenêtre), web developer and head of education, specializing in tech training and digital accessibility.
Questions about git mv
Organize your repo with GitQuest
Learn to properly structure your Git projects through interactive investigations.
Start the investigations