git-mv

Move a file inside the repo and add the movement to the next commit

$ git mv [path/to/file] [path/to/destination]

$ git mv [path/to/file_or_directory] [path/to/destination]

$ git mv [[-f|--force]] [path/to/file_or_directory] [path/to/destination]

git mv [<options>] <source> <destination>
git mv [<options>] <source> ... <directory>

-f, --force
    Force the move or rename, even if the destination path exists and is different from the source. This will overwrite the existing destination file.

-k
    Skip moving or renaming a file if its destination already exists and is different from the source. The command will proceed with other files if multiple sources are specified.

-n, --dry-run
    Perform a "dry run"; show what would happen without actually moving or renaming any files or modifying the Git index.

-v, --verbose
    Report the names of files as they are moved or renamed, providing more detailed output.

--cached
    Only move/rename files in the index, not in the working directory. This is useful for correcting an erroneous `git add` of a renamed file without touching the disk.

<source>
    The path to the file or directory to be moved or renamed. Multiple sources can be specified when moving into a directory.

<destination>
    The new path for the file or directory, or the target directory if multiple sources are specified. If a directory, it must already exist.

The git-mv command is used to move or rename files and directories within a Git repository, automatically updating the Git index to reflect these changes. It effectively performs the actions of a traditional mv command, followed by a git rm of the old path and a git add of the new path. This ensures that Git tracks the file's history across its new name or location.

Unlike simply using the shell's mv command, git-mv stages the move operation immediately, marking the file's old path for deletion and its new path for addition. This streamlined process saves manual steps and prevents potential issues with Git losing track of file history. It is particularly useful for maintaining an accurate and consistent repository state when reorganizing project structure.

The command is designed to work with files and directories that are already tracked by Git. After executing git-mv, the changes are staged and ready for a subsequent git commit to permanently record the move in the repository's history.

1. Tracks Existing Files Only: git-mv only operates on files and directories that are already tracked by Git (i.e., present in the index). Untracked files need to be handled manually.
2. Immediate Staging: The command stages the move operation immediately. This means the changes are ready for commit right after execution, but they are not committed until git commit is run.
3. Destination Overwrites: If the destination path already exists and is a tracked file, git-mv will overwrite it unless the -k option is used.
4. Directory Handling: When moving multiple sources into a directory, the destination directory must already exist. git-mv will not create new directories for you.

Git doesn't explicitly store rename events as distinct objects. Instead, when you use git-mv, it records a deletion of the old path and an addition of the new path in the index. During operations like git log --follow or git diff, Git uses a heuristic algorithm to detect file renames by comparing the content of files that were deleted in one commit and added in another. By using git-mv, you provide Git with a strong hint that a file was moved, making these rename detections more reliable and efficient.

git-mv is a fundamental command in the Git version control system, designed to simplify file reorganization while preserving history. Its inclusion from early Git versions reflects the importance of tracking file renames and moves seamlessly. Before dedicated commands like git-mv, users had to manually perform a shell mv, followed by a git rm of the old path and a git add of the new path. git-mv automates this common pattern, making repository maintenance more efficient and less error-prone. It ensures that Git's rename detection heuristics can effectively link the old and new paths, thereby maintaining a coherent file history across commits.

git-rm(1), git-add(1), git-status(1), git-commit(1), mv(1)