git mv

The git mv command moves or renames a file or directory that Git already tracks, and stages the change in a single step. This chapter covers how to rename a file, move a file into a directory, the options you will actually use (-f, -n, -k), and the gotchas — chiefly that git mv only works on files Git already knows about, and that Git does not store renames as records.

Definition

git mv is a convenience wrapper. Running it is equivalent to moving the file yourself, telling Git the old path is gone with git rm, and adding the new path with git add — all at once. The benefit is that the working tree and the staging area never fall out of sync, even for a moment.

Renaming a file

To rename a tracked file, give the old name and the new name:

git mv old-name.txt new-name.txt

The file is renamed on disk and the change is already staged, ready to commit. A following git status shows a clean rename entry. The short form makes this obvious — the R flag marks a staged rename:

git status --short

R  old-name.txt -> new-name.txt

All that is left is to commit the change with git commit.

Moving a file into a directory

Give a directory as the destination to move a file without renaming it:

git mv styles.css assets/

You can move several files into a directory in one command, as long as the destination is an existing folder:

git mv main.css reset.css print.css assets/

When the last argument is an existing directory, every preceding path is moved into it. If the directory does not yet exist, Git treats the last argument as a new filename instead — so create the folder first (with mkdir) when you mean to move files into it.

Renaming a directory

Pass a tracked directory as the source to move or rename it together with everything inside:

git mv src/ lib/

Git stages a rename for each tracked file under the directory, so a single git mv can produce many renamed: entries in git status.

What git mv saves you

Without git mv, the same rename takes three manual steps:

mv old-name.txt new-name.txt
git rm old-name.txt
git add new-name.txt

git mv collapses these into one and guarantees the staging area stays consistent. Note that Git does not actually store renames — it detects them by comparing file contents when you run git log or git diff. git mv simply makes the working-tree change tidy and pre-staged.

git mv only works on tracked files

git mv operates on files Git already tracks. Pointing it at an untracked file fails:

git mv note.txt moved.txt

fatal: not under version control, source=note.txt, destination=moved.txt

For a file Git has never seen, just rename it with the plain shell mv and then stage the new name with git add. Use git mv once the file is committed.

Common options

When the destination exists

By default Git refuses to overwrite an existing file. If you intend to replace it, add the force flag:

git mv -f draft.md final.md

Use this carefully, since it discards whatever was at the destination.

Previewing with a dry run

Before a large move, use -n (or --dry-run) to see exactly what Git would do — nothing is renamed and nothing is staged:

git mv -n old-name.txt new-name.txt

Checking rename of 'old-name.txt' to 'new-name.txt'
Renaming old-name.txt to new-name.txt

Combine it with -v (verbose) to print each rename as it happens during a real move.

Related commands

• git rm — remove tracked files; git mv performs an rm of the old path under the hood.
• git add — stage changes; git mv runs the equivalent add of the new path for you.
• git status — confirm the staged rename before committing.
• git commit — record the move in history.
• git log — view renames with git log --follow <file> to keep a file's history across moves.

Practice