Moving or Renaming Files (git mv)

As your project evolves, you'll inevitably need to reorganize your files. You might rename a file to better reflect its purpose or move it to a different directory to improve structure. While you could use your operating system's commands (like mv on Linux/macOS or ren/move on Windows) directly, Git provides a specific command, git mv, to handle these operations more gracefully within the context of version control.

Using git mv informs Git directly that a file has been renamed or moved, rather than treating it as a deletion of the old file and the addition of a new, untracked file. This helps Git track the history of the file across the rename or move operation.

Renaming a File with git mv

Let's say you have a file named temp_script.py and you want to rename it to utility_script.py. Instead of using your operating system's rename command followed by git add and git rm, you can simply use git mv:

# Rename the file using Git
git mv temp_script.py utility_script.py

# Check the status
git status

The output of git status will look something like this:

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        renamed:    temp_script.py -> utility_script.py

Notice how Git explicitly recognizes this as a rename operation. The change is already staged, ready for your next commit. You don't need to run git add or git rm separately; git mv handles it for you.

Moving a File with git mv

Moving a file works similarly. Suppose you want to move utility_script.py into a new directory called scripts.

First, create the directory if it doesn't exist:

# Create a new directory (standard OS command)
mkdir scripts

Then, use git mv to move the file:

# Move the file into the new directory
git mv utility_script.py scripts/utility_script.py

# Check the status
git status

Again, git status will show the staged change, indicating the move:

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        renamed:    utility_script.py -> scripts/utility_script.py

Even though we moved the file to a different directory, Git often reports this as a "rename" because, from Git's perspective, the path (which includes the directory) has changed. The main point is that Git understands the file's identity is preserved.

You can also move and rename a file in a single step:

# Move the file and rename it simultaneously
git mv old_location/old_name.txt new_directory/new_name.txt

What git mv Actually Does

The git mv command is essentially a convenience command that performs three actions:

1. Renames or moves the file on your filesystem (like the OS mv or ren/move command).
2. Removes the old file path from the Git index (similar to git rm <old_path>).
3. Adds the new file path to the Git index (similar to git add <new_path>).

By using git mv, you ensure Git correctly tracks the file's history through the rename or move, making it the recommended approach for managing file locations within your repository. If you forget to use git mv and instead use your operating system's tools, Git will see the old file as deleted and the new file as untracked. You would then need to manually git rm the old path and git add the new path to achieve the same result. Using git mv streamlines this process.