git mv

You need to rename a file or move it to a different directory, and you want Git to track that it's the same file in a new location rather than treating it as a deletion and a new file. git mv moves or renames files while automatically staging the change, making it the Git-aware way to reorganize your codebase.

Running git mv old-name.js new-name.js renames the file and stages both the deletion of the old name and the addition of the new name as a single operation. Git tracks this as a rename, preserving the file's history across the name change. You can view the file's complete history including pre-rename commits with git log --follow new-name.js.

Moving files to different directories works the same way: git mv src/utils.js src/helpers/utils.js moves the file and stages the change. You can even move and rename simultaneously: git mv old-name.js src/new-name.js.

Technically, you could rename files manually and then git rm old-name.js and git add new-name.js, but git mv does this in one step and makes the intention clearer. Git's rename detection usually figures it out either way, but using git mv is more explicit and slightly more reliable.

After running git mv, the change is staged and ready to commit. Including renamed files in commits with other logical changes (like updating imports to use the new path) keeps the history coherent.

In pull request workflows, renaming and moving files can make reviews challenging because reviewers see large diffs. GitHub and similar platforms have rename detection that shows "renamed: old-name.js → new-name.js" instead of showing the entire file as deleted and re-added. Using git mv helps these platforms correctly identify renames, making reviews clearer.

Understanding git mv means keeping Git aware of file reorganization. Instead of treating moves and renames as unrelated deletions and additions, Git sees the continuity, preserving history and making it easier to track how files evolved even as they moved around the repository.