Sinopsis

git mv [-f] [-k] [-n] <source> <destination>

Descripción

El comando git mv renombra o mueve un archivo rastreado y stagea el cambio. Internamente equivale a ejecutar mv seguido de git add en la nueva ruta y git rm en la antigua. La conveniencia es que el rename ocurre en un único paso atómico que se stagea sin ambigüedad.

Nota: Git no almacena renames como operaciones de primera clase. En cambio, detecta renames comparando la similitud de contenido de archivos al momento del diff y log. Así que ya sea que uses git mv o mv + git add + git rm, el commit resultante es idéntico, y la detección de rename funciona igual.

En el uso diario, git mv se integra con alias de shell y herramientas de edición. Para depurar, ejecuta con GIT_TRACE=1 para ver las llamadas internas.

Entender cómo git mv interactúa con el resto del modelo de datos de Git rinde dividendos al predecir resultados y recuperarse de errores.

Opciones comunes

Ejemplos

git mv old-name.txt new-name.txt
# Renombra un archivo en un paso

git mv src/utils.js src/lib/utils.js
# Mueve un archivo a un nuevo directorio (ya debe existir)

git mv -n *.md docs/
# Previsualiza mover todos los archivos markdown a docs/

git mv -f draft.md final.md
# Sobrescritura forzada si final.md ya existe

Errores comunes

Si renombras un archivo fuera de Git (con tu editor o mv), la detección de rename de Git aún suele funcionar al momento del diff, pero debes ejecutar git add -A para stagear tanto la eliminación como la adición. Otro problema: renames solo de capitalización en sistemas de archivos insensibles a mayúsculas (macOS, Windows) requieren git mv -f o un rename de dos pasos a través de un nombre temporal.

Comandos relacionados

git add, git rm, git log --follow