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.
git mv [-f] [-k] [-n] [-v] <source>... <destination>
Try it
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.
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
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 diffandgit 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.txttoB.txt) work withgit mveven on case-insensitive file systems (Windows, macOS default), where a plain rename in the shell followed bygit addmay not register. Setcore.ignorecasecorrectly for your platform and prefergit mvfor 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 statusafterwards. - Moving across repositories (submodules and subtrees) is not supported; use copy,
git addandgit rm, or tooling such as git filter-branch to keep history. - Staged immediately. The rename appears under "Changes to be committed"; no extra
git addis needed. Undo withgit mv new old, orgit restore --staged --worktreefor 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.