Restructuring a project
Move a group of source files into a new package directory in one command, so that the commit records the files as moved.
Git · Command
git mv
git mv renames or moves a tracked file, directory or symlink in your working tree. In the same step it records that change in the index (staging area).
Last updated
How it works
The command has two forms. If you give one source and one destination, Git renames the source to the destination path. If the last argument is a directory that already exists, Git moves every listed source into that directory. Each move happens on disk and in the index together, so you don't need a separate git add or git rm. Nothing goes into history until you commit. Options control how it behaves: -f overwrites an existing destination, -k skips moves that would fail, -n only shows what would happen, and -v prints each name as it is moved. For submodules, it also updates the gitfile, core.worktree and the path setting in .gitmodules.
Syntax
git mv [-v] [-f] [-n] [-k] <source> <destination>
git mv [-v] [-f] [-n] [-k] <source>... <destination-directory>Parameters
| Name | Type | Description |
|---|---|---|
<source> | path | The file, directory or symlink to rename or move. It must exist and be tracked by Git. The second form accepts several sources. |
<destination> | path | The new name for a single source (first form). |
<destination-directory> | path | An existing directory that all the listed sources are moved into (second form). |
-f, --force | flag | Rename or move even when the destination already exists, overwriting it. |
-k | flag | Skip any move or rename that would cause an error and carry on with the others. |
-n, --dry-run | flag | Change nothing; only show what would be done. |
-v, --verbose | flag | Print the name of each file as it is moved. |
Key points
- In the single-target form, the source has to exist already, and it can be a regular file, a symlink or a whole directory.
- To move several items at once, the last argument must be a directory that already exists. git mv will not create it for you.
- The change is staged when the command succeeds. You still need to run git commit to record the rename in history.
- By default git mv refuses to overwrite a destination that already exists. Pass -f/--force to overwrite it.
- In a bulk move, -k makes Git skip the moves that would fail (for example, untracked or missing sources) and perform the rest.
- Use -n/--dry-run to preview a move without touching anything, and -v/--verbose to list each file as it is moved.
- If a submodule uses a gitfile (cloned with Git 1.7.8 or newer), git mv fixes up its links so it still works after the move. It also tries to update and stage the path entry in .gitmodules.
Common mistakes
- If you check out commits from before and after a populated submodule was moved, the old checkout is left behind and the new location is just an empty directory.
- After that kind of checkout, the submodule at its new location stays empty until you populate it yourself.
- Don't delete a leftover submodule directory unless it uses a gitfile, because otherwise you lose the submodule's history.
Example: Rename a file and move several files into a folder
#!/usr/bin/env bash
set -euo pipefail
# Rename a single tracked file
git mv README.txt README.md
# Preview a bulk move first
mkdir -p docs
git mv -n -v guide.md faq.md docs/
# Perform it, skipping anything that would error
git mv -k -v guide.md faq.md docs/
# Changes are staged; inspect and commit
git status --short
git commit -m "Rename README and move docs into docs/"The script renames one file, previews a bulk move into an existing directory, runs the move while skipping any failures, and then commits the staged result.
When to use it
Fixing a file name
Rename a misnamed config or documentation file without having to delete it and add it again by hand.
Relocating a submodule
Move a vendored submodule to another path and have Git update its gitfile and the .gitmodules entry for you.
Interview questions
QWhat does git mv do that a plain shell mv doesn't?
A shell mv only changes files on disk. git mv also updates the index, so the old path is removed from staging and the new path is added. Without it, you would have to stage the deletion and the addition yourself before committing.
Follow-up: Is the rename visible to other people right after git mv? No. Only the index has changed, so the rename stays local until you commit it and push.
QHow do you move several files at once, and what does the destination have to be?
Use the second form: list the sources and put the target directory last. That directory must already exist, and every source is moved into it.
Follow-up: What if some of the sources are untracked or missing? Without -k the command reports an error. With -k Git skips those entries and moves the rest.
QWhat happens when the destination path already exists?
git mv treats this as an error and refuses to overwrite the existing file. -f/--force makes it go ahead and replace the destination. Running with -n first lets you see what would happen.
Follow-up: Can -k and -f be combined meaningfully? Yes. -f turns an existing destination into an allowed overwrite rather than an error, so -k then only skips the remaining problems, such as sources that don't exist or aren't tracked.
Related
git rmgit addgit statusgit commitgit submodulegitmodules