Git Course 0%

git mv

Beginner Git CLI Safe ≈ 3 min

Summary: git mv <old> <new> renames or moves a tracked file (or folder) on disk and stages the change, in one command.

Safe — the content is unchanged; a staged rename can be undone before committing.

What it does

Exactly what renaming in the file manager followed by git add of both paths does: the old path is staged as deleted, the new as added, and Git presents the pair as a rename because the content matches.

Why it exists

Convenience and clarity: one step instead of two, and no forgotten half (the classic "deleted, not staged" plus an untracked file).

When to use it

  • Renaming a documentation page, moving a file into a subfolder, renaming a folder.
  • Changing only the letter case of a name on macOS or Windows, where the file system pretends nothing changed.

When not to use it

  • For untracked files: it refuses (not under version control); use the normal file manager and git add.
  • Together with large edits to the same file in one commit: rename first, commit, then edit, or the rename detection may fail.

Syntax

Form Meaning
git mv <old> <new> Rename or move a file
git mv <file> <folder>/ Move into an existing folder
git mv <old-folder> <new-folder> Rename a folder with everything inside

The target folder must exist (mkdir it first).

Examples

Terminal
$ git mv docs/faq.md docs/questions.md
$ git status -s
R  docs/faq.md -> docs/questions.md

The same result, done by hand:

Terminal
$ mv docs/notes.md docs/scratch.md
$ git add docs/
$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	renamed:    docs/notes.md -> docs/scratch.md

Expected result

The file is at its new path on disk; git status shows renamed: (or R in short form) under "Changes to be committed". Commit to record it.

Common mistakes

  • Target folder does not exist. fatal: destination directory does not exist; mkdir first.
  • Editing heavily in the same commit. Git may show a delete and an add instead of a rename. Separate commits.
  • Forgetting links. Other pages that link to the old path break; search for it and update the links in the same merge request.

How to undo or recover

Before committing: git mv <new> <old> to rename back, or git restore --staged <old> <new> followed by a manual rename. After committing: rename back in a new commit, or revert the commit.

In VS Code

Rename in the Explorer (F2) or drag to move, then stage both paths in Source Control; VS Code shows the pair as R once staged.

In IntelliJ IDEA

Refactor → Rename (Shift+F6) or drag in the Project view: IntelliJ runs git mv for tracked files automatically.

git rm removes · git add stages a rename done by hand · git log --follow traces a file's history across renames.

Lessons that use this command

Create, rename, move, delete · File states.

Key terms

Tracked Staged

Related