git-mv - Linux


git-mv is a command-line utility provided by Git used to rename or move files and directories tracked by the Git version control system. It atomically updates both the file system and the Git index, ensuring that the changes are tracked and reflected in the repository history.


git mv [-n] [-v] [-f] [-k] [-u] [-a | --all] <file/directory>... <new path>


  • -n, –dry-run: Simulates the move without making any changes to the file system or Git index.
  • -v, –verbose: Displays detailed progress information.
  • -f, –force: Overwrites existing files or directories without prompting for confirmation.
  • -k, –keep: Keeps the original file after moving, rather than deleting it.
  • -u, –update: Updates index only, without making changes to the file system.
  • -a, –all: Moves all files and directories in the current directory to the specified new path.


Simple File Rename:

git mv old-file.txt new-file.txt

Moving a Directory:

git mv old-dir new-dir

Atomic File/Directory Move (Dry Run):

git mv -n my-file.txt new-path/my-file.txt

Forcefully Overwriting Existing File:

git mv -f existing-file.txt new-file.txt

Keeping Original File After Move:

git mv -k original-file.txt new-file.txt

Common Issues

  • Destination Path Already Exists: If the specified destination path already exists, the move will fail (unless the -f flag is used).
  • Moving Outside of Repository: Git cannot move files or directories outside of the current Git repository.
  • Moving Large Files: Moving very large files can take a significant amount of time. Consider using an alternative method, such as git add -f and git commit -a.


  • git status: Use git status to verify that the move was recorded in the staging area.
  • git commit: Commit the changes to the repository using git commit.
  • git push: Push the changes to a remote repository using git push.

Related Commands

  • git add – Adds files to the staging area.
  • git commit – Commits changes to the repository.
  • git rm – Removes files from the Git index and file system.