git mv

La commande git mv déplace ou renomme un fichier ou un répertoire que Git suit déjà, et indexe la modification en une seule étape. Ce chapitre explique comment renommer un fichier, déplacer un fichier dans un répertoire, les options les plus utiles (-f, -n, -k), ainsi que les pièges à éviter — notamment que git mv ne fonctionne que sur des fichiers déjà connus de Git, et que Git ne stocke pas les renommages en tant qu'enregistrements.

Définition

git mv est un raccourci pratique. L'exécuter équivaut à déplacer le fichier manuellement, à indiquer à Git que l'ancienne entrée a disparu avec git rm, puis à ajouter le nouveau chemin avec git add — le tout en une seule opération. L'avantage est que le répertoire de travail et la zone d'index ne se désynchronisent jamais, même brièvement.

Renommer un fichier

Pour renommer un fichier suivi, indiquez l'ancien nom puis le nouveau :

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

Le fichier est renommé sur le disque et la modification est déjà indexée, prête à être validée. Un git status suivant affiche une entrée de renommage propre. La forme courte le rend évident — le drapeau R marque un renommage indexé :

git status --short

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

Il ne reste plus qu'à valider la modification avec git commit.

Déplacer un fichier dans un répertoire

Fournissez un répertoire comme destination pour déplacer un fichier sans le renommer :

git mv styles.css assets/

Vous pouvez déplacer plusieurs fichiers dans un répertoire en une seule commande, à condition que la destination soit un dossier existant :

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

Lorsque le dernier argument est un répertoire existant, tous les chemins précédents y sont déplacés. Si le répertoire n'existe pas encore, Git considère le dernier argument comme un nouveau nom de fichier — créez donc d'abord le dossier (avec mkdir) lorsque vous souhaitez y déplacer des fichiers.

Renommer un répertoire

Passez un répertoire suivi comme source pour le déplacer ou le renommer avec tout son contenu :

git mv src/ lib/

Git indexe un renommage pour chaque fichier suivi dans le répertoire, de sorte qu'un seul git mv peut produire de nombreuses entrées renamed: dans git status.

Ce que git mv vous évite

Sans git mv, le même renommage nécessite trois étapes manuelles :

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

git mv regroupe ces étapes en une seule et garantit la cohérence de la zone d'index. Notez que Git ne stocke pas réellement les renommages — il les détecte en comparant le contenu des fichiers lorsque vous exécutez git log ou git diff. git mv rend simplement la modification du répertoire de travail propre et pré-indexée.

git mv ne fonctionne que sur les fichiers suivis

git mv opère sur les fichiers que Git suit déjà. Le pointer vers un fichier non suivi échoue :

git mv note.txt moved.txt

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

Pour un fichier que Git n'a jamais vu, renommez-le simplement avec la commande shell mv, puis indexez le nouveau nom avec git add. Utilisez git mv une fois le fichier validé.

Options courantes

Quand la destination existe

Par défaut, Git refuse d'écraser un fichier existant. Si vous souhaitez le remplacer, ajoutez le drapeau de force :

git mv -f draft.md final.md

Utilisez cette option avec précaution, car elle supprime ce qui se trouvait à la destination.

Prévisualiser avec une simulation

Avant un déplacement important, utilisez -n (ou --dry-run) pour voir exactement ce que Git ferait — rien n'est renommé et rien n'est indexé :

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

Combinez-le avec -v (verbeux) pour afficher chaque renommage au fur et à mesure lors d'un déplacement réel.

Commandes associées

• git rm — supprimer des fichiers suivis ; git mv effectue un rm de l'ancien chemin en arrière-plan.
• git add — indexer des modifications ; git mv exécute l'équivalent add du nouveau chemin pour vous.
• git status — confirmer le renommage indexé avant de valider.
• git commit — enregistrer le déplacement dans l'historique.
• git log — consulter les renommages avec git log --follow <file> pour conserver l'historique d'un fichier à travers ses déplacements.

Pratique