In a Git repository, how to properly rename a directory?

How to Properly Rename a Directory in Git

Learn the correct and most effective methods for renaming directories within a Git repository, ensuring history is preserved and changes are tracked accurately.

Renaming a directory in Git might seem straightforward, but it's crucial to understand how Git tracks file and directory movements to maintain a clean and accurate repository history. Unlike some version control systems, Git doesn't explicitly track renames; instead, it detects them by comparing file content and metadata between commits. This article will guide you through the proper techniques for renaming directories, focusing on methods that ensure Git correctly recognizes the change.

Understanding Git's Approach to Renames

Git doesn't have a dedicated 'rename directory' command in the same way it has git add or git commit. When you rename a directory using your operating system's file explorer or a standard mv command, Git sees this as a deletion of the old directory and an addition of a new one. However, Git is smart enough to detect that the content of the files in the 'new' directory is identical to the content of the files in the 'old' directory, and it will infer a rename during the commit process. The key is to stage the changes correctly.

flowchart TD
    A[Start: Directory 'old_dir'] --> B{OS Rename Command}
    B --> C[Files moved to 'new_dir']
    C --> D{Git Status: 'old_dir' deleted, 'new_dir' untracked}
    D --> E[Git Add 'new_dir']
    E --> F{Git Commit: Git detects rename}
    F --> G[End: Rename recorded in history]

Git's rename detection process

Method 1: Using git mv (Recommended)

The git mv command is the most straightforward and recommended way to rename files or directories in Git. It handles both the file system operation (moving/renaming) and staging the change for Git, ensuring that Git explicitly records the rename operation in its index. This makes the rename detection more robust and less prone to issues, especially in complex scenarios or when dealing with large numbers of files.

git mv old_directory_name new_directory_name

Renaming a directory using git mv

After executing git mv, the changes are automatically staged. You can verify this with git status.

$ git mv src/components src/ui-components
$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	renamed:    src/components/Button.js -> src/ui-components/Button.js
	renamed:    src/components/Input.js -> src/ui-components/Input.js

Output of git status after git mv

Finally, commit the changes:

git commit -m "Rename src/components to src/ui-components"

Committing the directory rename

Method 2: Manual Rename and Staging

If you've already renamed a directory using your operating system's mv command or file explorer, you can still inform Git about the rename. This method requires a few more steps but achieves the same result as git mv.

1. Rename the directory

Use your operating system's command to rename the directory. For example, on Linux/macOS:

2. Stage the changes

Git will now see the old files as deleted and the new files as untracked. You need to stage both the deletions and the additions. Git is usually smart enough to detect the rename when you stage both sides of the change.

3. Commit the changes

After staging, commit the changes. Git will typically infer the rename.

# Step 1: Rename using OS command
mv old_directory_name new_directory_name

# Step 2: Stage the changes
git add -A
# OR: git rm -r old_directory_name && git add new_directory_name

# Step 3: Commit the changes
git commit -m "Rename old_directory_name to new_directory_name"

Manual directory rename and staging

Verifying the Rename History

After committing a directory rename, you can verify that Git correctly tracked the change using git log with the --follow option for a specific file that was moved.

git log --follow -- new_directory_name/file_inside_it.js

Checking file history after a rename

This command will show the history of file_inside_it.js, including its history before the rename, demonstrating that Git successfully linked the old and new versions of the file.