Move files (git mv)

Author：Chuan Chen 阅读数：28220人阅读分类：开发工具

Moving Files (git mv)

Git provides the git mv command specifically for moving or renaming files. Unlike using the operating system's mv command directly, git mv ensures that Git can correctly track the file's movement history. When you use the mv command directly, Git interprets it as deleting the old file and adding a new one, whereas git mv preserves the file's history.

Basic Usage

The basic syntax of the git mv command is as follows:

git mv <source> <destination>

For example, to move the file old.txt to a new location new.txt:

git mv old.txt new.txt

This is equivalent to performing the following steps:

Renaming old.txt to new.txt
Staging this move in Git's staging area

Moving Directories

git mv can also be used to move entire directories. For example, to move the src/ directory to lib/:

git mv src/ lib/

If the target directory does not exist, Git will create it automatically. After the move, all files under src/ will be moved to the lib/ directory while preserving Git's history.

Moving Files Across Directories

You can move files from one directory to another. For example, to move src/utils.js to lib/helpers.js:

git mv src/utils.js lib/helpers.js

This operation performs both the file move and rename.

Difference from the Regular mv Command

When you use the operating system's mv command directly, Git will show two changes:

Deletion of the original file
Addition of the new file

Using git mv, however, Git recognizes it as a file move/rename operation, better preserving the history. For example:

# Using the system mv command
mv file.txt newfile.txt
git add .
git status
# Shows deleted: file.txt and newfile.txt

# Using git mv
git mv file.txt newfile.txt
git status
# Shows renamed: file.txt -> newfile.txt

Practical Use Cases

Refactoring Project Structure

File moves are common during project refactoring. For example, moving React components from components/ to ui/:

git mv src/components/Button.js src/ui/Button.js
git mv src/components/Modal/ src/ui/modals/

Renaming Files While Preserving History

To rename a file while keeping its Git history:

git mv old-component.jsx NewComponent.jsx

Batch Moving Files

You can combine it with shell commands to move files in bulk:

for file in src/legacy/*.js; do
  git mv "$file" "src/modern/$(basename "$file")"
done

Advanced Usage

Forced Move

If the target file already exists, use the -f option to force overwrite:

git mv -f old.js new.js

Verbose Output

Use the -v option to show detailed output:

git mv -v config.yml config/config.yml

Moving and Staging

git mv automatically stages the move operation, equivalent to:

mv old new
git add old new

Handling Special Cases

Modifying Files After Moving

Sometimes you need to modify a file immediately after moving it:

git mv Component.js components/Component.js
# Then edit the file right away
vim components/Component.js

Undoing a Move

If you accidentally moved a file, you can undo it:

git reset HEAD components/Component.js
git checkout -- components/Component.js

Moving Ignored Files

git mv can also move files ignored by .gitignore:

git mv --force logs/old.log archive/logs/old.log

Integration with Other Git Commands

Viewing Move History

Use git log to view a file's move history:

git log --follow -p components/Component.js

Interactive Staging

Handling file moves in interactive staging:

git add -i
# Then select the rename option

Troubleshooting Common Issues

Moving Modified Files

If a file has unstaged changes, Git will refuse to move it:

error: 'old.js' has local changes. Cannot move.

Commit or stage the changes first, then perform the move.

Case Sensitivity Issues

Renaming file cases on case-insensitive systems (e.g., macOS):

git mv File.js file.js

Moving Submodules

Moving submodules requires additional steps:

git mv old/submodule new/submodule
# Then edit the .gitmodules file

Under the Hood

git mv is essentially a shortcut for:

Moving the file in the working directory
Removing the old path from the index
Adding the new path to the index

Git uses a similarity algorithm to detect file moves, so even without git mv, Git can often detect renames.

Performance Considerations

For large repositories, moving many files at once may impact performance. Consider moving files in smaller batches and committing between moves.

Cross-Platform Notes

On Windows, pay attention to path separators:

git mv src\\file.js src\\subdir\\file.js

Script Automation

When automating file moves in scripts, check if the command succeeds:

if ! git mv src/old.js dest/new.js; then
  echo "Failed to move file"
  exit 1
fi

Comparison with GUI Tools

Most Git GUI tools also offer file-moving functionality, but the command-line git mv is more precise and controllable. For example, in VS Code's Git panel, you can drag and drop files to move them.