git mv

Convenience wrapper for mv + add + rm of the old name.

🎯 What & why

Rename or move a tracked file in one step. Equivalent to mv old new && git rm old && git add new, but recorded as a move in the index so rename detection is automatic.

🧠 Mental model

Git doesn't actually track renames. git mv updates the index — adds an entry for the new path with the old blob's SHA, removes the old path. At log/diff time, Git looks for adds and removes with matching content and infers a rename. git mv makes that inference reliable.

🛠️ Synopsis

git mv [-v] [-f] [-n] [-k] <source> <destination>
git mv [-v] [-f] [-n] [-k] <source>... <destination directory>

🎚️ Switches & options

Flag	What it does
`-f, --force`	Overwrite destination if it exists.
`-n, --dry-run`	Show what would happen, do nothing.
`-k`	Skip moves that would fail (e.g. source missing). Useful in scripts.

💡 Use cases

Restructuring directory layouts without losing blame history.
Renaming a file as part of a larger refactor.

🧪 Examples

Rename a file.

$ git mv old_name.txt new_name.txt

Move into a directory.

$ git mv parser.c lib/

Dry-run before doing it for real.

$ git mv -n src/old/ src/new/

🎓 Recommendations

git mv is just shell convenience. mv + git add -A works identically as far as Git is concerned. Pick whichever fits your muscle memory.
For content changes that happen alongside a rename, commit the move in one commit and the content change in the next. Keeps blame readable.

🪤 Common pitfalls

Renaming a file and changing it heavily in the same commit can defeat rename detection. git log --follow becomes flaky.
Case-only renames on case-insensitive filesystems (macOS default, Windows) require core.ignorecase=false to behave.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.