Réécrire l'historique Git

git commit --amend modifie le dernier commit, git rebase -i réorganise les N derniers commits, et git filter-repo nettoie tout l’historique. Réécrire l’historique produit des commits propres et logiques avant de les partager. Ce guide couvre les trois niveaux de réécriture.

Prérequis : Rebase fondamental et Staging interactif.

Règle d'or

Ne réécrivez jamais l’historique de commits déjà poussés et partagés. Réécrire crée de nouveaux SHA, ce qui casse l’historique des collaborateurs. Réécrivez uniquement vos commits locaux, avant le push.

Ce que vous allez apprendre

• Modifier le dernier commit avec --amend (message ou contenu)
• Réécrire plusieurs commits avec rebase -i : squash, fixup, reword, edit, drop
• Supprimer un fichier de tout l’historique avec git filter-repo
• Appliquer la règle d’or : ne jamais réécrire un historique déjà partagé

git commit --amend : modifier le dernier commit

La forme la plus simple de réécriture. Modifie le message et/ou le contenu du dernier commit :

Modifier le message

git commit --amend -m "fix: corriger le calcul de TVA"

Ajouter des fichiers oubliés

git add fichier-oublie.py
git commit --amend --no-edit

--no-edit conserve le message original. Le commit ammendé remplace l’ancien (nouveau SHA).

Modifier l’auteur

git commit --amend --author="Alice <alice@example.com>"

git rebase -i : le couteau suisse

Le rebase interactif permet de réorganiser, fusionner, renommer, éditer ou supprimer une série de commits.

Lancer un rebase interactif

# Réécrire les 5 derniers commits
git rebase -i HEAD~5

Git ouvre l’éditeur avec une liste de commits (du plus ancien au plus récent) :

pick a1b2c3d feat: ajouter le module pricing
pick e4f5a6b fix: corriger la remise
pick d7c8b9a wip: debug
pick f0e1d2c feat: ajouter les tests
pick b3a4c5d fix: typo dans le README

Les commandes disponibles

Commande	Effet
pick (p)	Garder le commit tel quel
reword (r)	Garder le commit, modifier le message
edit (e)	S’arrêter pour modifier le commit (contenu + message)
squash (s)	Fusionner avec le commit précédent (combiner les messages)
fixup (f)	Fusionner avec le précédent (supprimer le message du fixup)
drop (d)	Supprimer le commit

Glissez pour voir

Vous pouvez aussi réordonner les lignes pour changer l’ordre des commits.

Exemple : nettoyer avant un push

Historique initial :

pick a1b2c3d feat: ajouter le module pricing
pick e4f5a6b fix: corriger la remise
pick d7c8b9a wip: debug
pick f0e1d2c feat: ajouter les tests
pick b3a4c5d fix: typo dans le README

Réécriture souhaitée :

pick a1b2c3d feat: ajouter le module pricing
fixup e4f5a6b fix: corriger la remise
drop d7c8b9a wip: debug
pick f0e1d2c feat: ajouter les tests
fixup b3a4c5d fix: typo dans le README

Résultat : 2 commits propres au lieu de 5.

Workflow rebase -i pas à pas

1. Vérifiez que vos commits ne sont pas encore poussés :

   git log origin/main..HEAD --oneline

2. Lancez le rebase interactif :

   git rebase -i HEAD~5

3. Modifiez les commandes (pick → squash, fixup, drop…) dans l’éditeur, sauvegardez, fermez.

4. Si squash : Git ouvre l’éditeur pour combiner les messages. Rédigez un message propre.

5. Si conflit : résolvez puis continuez :

   git add fichier-resolu.py
   git rebase --continue

6. Pour annuler à tout moment :

   git rebase --abort

L’option edit en détail

edit stoppe le rebase pour vous laisser modifier un commit intermédiaire :

# Le rebase s'arrête au commit marqué "edit"
# Modifiez les fichiers...
git add .
git commit --amend
git rebase --continue

Vous pouvez même découper un commit en deux :

# Au point d'arrêt "edit"
git reset HEAD~1              # Annuler le commit (garder les fichiers)
git add partie-1.py
git commit -m "feat: partie 1"
git add partie-2.py
git commit -m "feat: partie 2"
git rebase --continue

--autosquash : automatiser le fixup

Git peut placer automatiquement les commits de fixup au bon endroit :

# Créer un commit de fixup lié au commit a1b2c3d
git commit --fixup=a1b2c3d

# Lancer le rebase avec autosquash
git rebase -i --autosquash HEAD~10

Le commit fixup! feat: ajouter le module pricing est automatiquement placé juste après et marqué fixup.

Pour activer --autosquash par défaut :

git config --global rebase.autoSquash true

git filter-repo : nettoyage profond

Pour supprimer un fichier de tout l’historique (par exemple un secret commité par erreur), git filter-repo remplace l’ancien filter-branch (déprécié).

Impact équipe : à ne pas sous-estimer

git filter-repo réécrit tous les SHA de l’historique. Conséquences concrètes pour votre équipe :

• Tous les collaborateurs doivent recloner le dépôt — leurs clones locaux seront incompatibles
• Toutes les PR/MR ouvertes devront être recréées
• Les références externes (issues liées à un SHA, liens dans des wikis, pipelines CI) seront brisées
• Si le dépôt est public, les forks tiers seront aussi impactés

Avant de lancer, synchronisez avec toute l’équipe et planifiez une fenêtre de maintenance. Il faut un consensus explicite.

Checklist avant d’utiliser filter-repo

• Le secret exposé est-il déjà changé/révoqué ? (sinon, faites-le d’abord)
• Tout le monde est-il prévenu et ses branches locales sauvegardées ?
• Avez-vous une sauvegarde du dépôt original (git bundle create backup.bundle --all) ?
• Le dépôt est-il clôné en « fresh clone » (ne pas l’exécuter sur un dépôt avec des modifications locales) ?

Installation

# Via pip
pip install git-filter-repo

# Via le gestionnaire de paquets
# Debian/Ubuntu
apt install git-filter-repo
# macOS
brew install git-filter-repo

Supprimer un fichier de tout l’historique

git filter-repo --invert-paths --path secrets/api-key.txt

Cette commande réécrit chaque commit pour supprimer le fichier. Tous les SHA changent.

Remplacer du texte dans tout l’historique

Créez un fichier de remplacement :

replacements.txt

regex:AKIA[A-Z0-9]{16}==>REDACTED_AWS_KEY
literal:mon-mot-de-passe==>REDACTED

git filter-repo --replace-text replacements.txt

Après filter-repo

Tous les SHA changent. Les collaborateurs doivent recloner le dépôt. Sur une plateforme (GitHub/GitLab), vous devez aussi force push et invalider les caches.

Et surtout : changez immédiatement le secret exposé. Supprimer le fichier de l’historique ne suffit pas — le secret est déjà potentiellement compromis.

BFG Repo Cleaner : alternative rapide

BFG est plus simple que filter-repo pour des cas courants :

# Installer (nécessite Java)
# Télécharger depuis https://rtyley.github.io/bfg-repo-cleaner/

# Supprimer un fichier de tout l'historique
bfg --delete-files api-key.txt

# Supprimer les fichiers > 100 Mo
bfg --strip-blobs-bigger-than 100M

# Remplacer du texte
bfg --replace-text passwords.txt

# Nettoyer après BFG
git reflog expire --expire=now --all
git gc --prune=now --aggressive

Comparatif des outils

Outil	Portée	Cas d’usage	Complexité
--amend	Dernier commit	Message ou contenu oublié	Faible
rebase -i	N derniers commits	Squash, reword, réordonner	Moyenne
filter-repo	Tout l’historique	Supprimer secrets/gros fichiers	Élevée
BFG	Tout l’historique	Supprimer fichiers/texte	Moyenne

Glissez pour voir

Dépannage

Symptôme	Cause probable	Solution
CONFLICT pendant rebase -i	Commits interdépendants réordonnés	Résolvez chaque conflit, git rebase --continue
Rebase boucle sur le même conflit	Commit conflictuel non résolu	git rebase --abort et repensez l’ordre
Cannot rebase: You have unstaged changes	Working dir sale	git stash avant le rebase
filter-repo refuse de s’exécuter	N’est pas un clone « fresh »	Ajoutez --force ou clonez le repo d’abord
push rejected après réécriture	SHA ont changé	git push --force-with-lease (jamais --force seul)

Glissez pour voir

À retenir

• --amend : rapide pour le dernier commit
• rebase -i : squash, fixup, reword, edit, drop, réordonner
• --fixup + --autosquash automatisent le nettoyage
• filter-repo : pour les nettoyages profonds (secrets, gros fichiers)
• Règle d’or : ne réécrivez jamais des commits déjà partagés
• Après réécriture : --force-with-lease (pas --force)

Prochaines étapes

Reset démystifié Comprenez les 3 arbres et les modes --soft, --mixed, --hard.

Merge avancé -Xours, -Xtheirs, rerere et merge --squash.

Secrets dans le code et l'historique Git Évitez de committer des secrets, détectez et nettoyez.

×

📖 Voir la documentation →