Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Staging and Committing

git mv command

Reference for git mv: rename or move files and directories, update the index in one step, use -f, -k and -n, and see how Git detects renames afterwards.

git mv moves or renames a tracked file, directory or symbolic link and stages the change. It is shorthand for three steps: move the file in the working tree, remove the old path from the index, and add the new path.

Git does not store renames explicitly. A commit records the new tree, and tools such as git log --follow, git diff -M and git blame -M detect the rename afterwards by finding that the content is the same or very similar. So git mv is a convenience, not a requirement: renaming with your file manager and running git add -A leads to the same history.

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

Try it

Bash Rename, move into a directory and detect the rename

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Dry run, case-only rename and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
git mv <source> <destination>
git mv <source>... <directory>/
Name Description
<source> One or more tracked files, directories or symlinks.
<destination> The new name for a single source, or an existing directory that receives all the sources.
-f, --force Overwrite the destination if it exists.
-k Skip move or rename actions that would lead to an error (untracked or missing sources, a destination that exists) instead of aborting.
-n, --dry-run Show what would happen without moving anything.
-v, --verbose Print each Renaming a to b line.
--sparse Allow moving entries outside the sparse-checkout area.

Errors: fatal: bad source means the source is missing; not under version control means it is untracked; destination exists stops a rename onto an existing file unless you pass -f; destination directory does not exist happens when moving several files to a path that is not an existing directory. A failure leaves nothing partially moved.

Usage notes

  • Rename detection is heuristic. In git diff and git log, a rename is reported when the new file is at least about 50% similar to the old one (-M<n> changes the threshold). If you rename and rewrite a file in the same commit, Git may show a deletion and an addition. Rename in one commit and edit in the next to keep history readable.
  • Case-only renames (b.txt to B.txt) work with git mv even on case-insensitive file systems (Windows, macOS default), where a plain rename in the shell followed by git add may not register. Set core.ignorecase correctly for your platform and prefer git mv for this job.
  • Directories move with everything inside; only tracked files are recorded at the new path. Untracked or ignored files inside stay behind in the old folder or move physically with it, depending on the file system, so check git status afterwards.
  • Moving across repositories (submodules and subtrees) is not supported; use copy, git add and git rm, or tooling such as git filter-branch to keep history.
  • Staged immediately. The rename appears under "Changes to be committed"; no extra git add is needed. Undo with git mv new old, or git restore --staged --worktree for each path.
  • Links to the file elsewhere (imports, build scripts, documentation) are not updated; search with git grep for the old name.
  • Hooks and tools that watch the working tree (IDEs, git blame -C) work with either approach.