git mv

El comando git mv mueve o renombra un archivo o directorio que Git ya rastrea, y prepara el cambio en un único paso. Este capítulo explica cómo renombrar un archivo, mover un archivo a un directorio, las opciones que usarás en la práctica (-f, -n, -k), y los puntos a tener en cuenta — principalmente que git mv solo funciona con archivos que Git ya conoce, y que Git no almacena los cambios de nombre como registros.

Definición

git mv es un envoltorio de conveniencia. Ejecutarlo equivale a mover el archivo manualmente, indicarle a Git que la ruta antigua ha desaparecido con git rm, y añadir la nueva ruta con git add — todo de una vez. La ventaja es que el árbol de trabajo y el área de preparación nunca quedan desincronizados, ni por un momento.

Renombrar un archivo

Para renombrar un archivo rastreado, indica el nombre antiguo y el nombre nuevo:

git mv old-name.txt new-name.txt

El archivo se renombra en disco y el cambio ya queda preparado, listo para confirmar. Un git status posterior muestra una entrada de renombrado limpia. El formato corto lo hace evidente — la bandera R marca un renombrado preparado:

git status --short

R  old-name.txt -> new-name.txt

Solo queda confirmar el cambio con git commit.

Mover un archivo a un directorio

Indica un directorio como destino para mover un archivo sin renombrarlo:

git mv styles.css assets/

Puedes mover varios archivos a un directorio en un solo comando, siempre que el destino sea una carpeta existente:

git mv main.css reset.css print.css assets/

Cuando el último argumento es un directorio existente, todas las rutas anteriores se mueven a él. Si el directorio aún no existe, Git trata el último argumento como un nuevo nombre de archivo — así que crea la carpeta primero (con mkdir) cuando quieras mover archivos a ella.

Renombrar un directorio

Pasa un directorio rastreado como origen para moverlo o renombrarlo junto con todo su contenido:

git mv src/ lib/

Git prepara un renombrado para cada archivo rastreado dentro del directorio, por lo que un solo git mv puede generar muchas entradas renamed: en git status.

Lo que te ahorra git mv

Sin git mv, el mismo renombrado requiere tres pasos manuales:

mv old-name.txt new-name.txt
git rm old-name.txt
git add new-name.txt

git mv los colapsa en uno y garantiza que el área de preparación se mantiene consistente. Ten en cuenta que Git no almacena realmente los cambios de nombre — los detecta comparando el contenido de los archivos cuando ejecutas git log o git diff. git mv simplemente hace que el cambio en el árbol de trabajo quede ordenado y ya preparado.

git mv solo funciona con archivos rastreados

git mv opera sobre archivos que Git ya rastrea. Apuntarlo a un archivo no rastreado falla:

git mv note.txt moved.txt

fatal: not under version control, source=note.txt, destination=moved.txt

Para un archivo que Git nunca ha visto, simplemente renómbralo con el comando mv del shell y luego prepara el nuevo nombre con git add. Usa git mv una vez que el archivo esté confirmado.

Opciones comunes

Cuando el destino ya existe

Por defecto Git se niega a sobrescribir un archivo existente. Si tienes la intención de reemplazarlo, añade la bandera de forzar:

git mv -f draft.md final.md

Úsalo con cuidado, ya que descarta lo que hubiera en el destino.

Vista previa con ejecución en seco

Antes de un movimiento grande, usa -n (o --dry-run) para ver exactamente lo que Git haría — nada se renombra y nada se prepara:

git mv -n old-name.txt new-name.txt

Checking rename of 'old-name.txt' to 'new-name.txt'
Renaming old-name.txt to new-name.txt

Combínalo con -v (verbose) para imprimir cada renombrado a medida que ocurre durante un movimiento real.

Comandos relacionados

• git rm — elimina archivos rastreados; git mv realiza un rm de la ruta antigua internamente.
• git add — prepara cambios; git mv ejecuta el add equivalente de la nueva ruta por ti.
• git status — confirma el renombrado preparado antes de confirmar.
• git commit — registra el movimiento en el historial.
• git log — visualiza renombrados con git log --follow <file> para mantener el historial de un archivo a través de los movimientos.

Práctica