git filter-branch

Patchs et réécriture

Réécrire l’historique avec des filtres (obsolète — utilisez git filter-repo)

La commande 'git filter-branch' réécrit chaque commit d’une branche à travers des filtres — par exemple pour retirer un fichier de tout l’historique. Elle est lente, facile à mal utiliser et officiellement déconseillée : Git lui-même affiche un avertissement et recommande git filter-repo. Comme toute réécriture, elle donne un nouveau hash à chaque commit, donc tout le monde doit recloner ou réinitialiser.

Synopsis

git filter-branch [--index-filter <cmd>] [--tree-filter <cmd>] [--msg-filter <cmd>] [--] <rev-list>
[ ] facultatif| ou<arg> valeur à remplacer... répétable--flag option

Exemples

Retirer un fichier partout

git filter-branch --index-filter 'git rm --cached --ignore-unmatch .env' HEAD

L’ancienne méthode, lente.

La méthode recommandée

git filter-repo --path .env --invert-paths

git filter-repo (outil séparé) le fait vite et sans risque.

Exemples de workflows

1
Rotate the secret

D’abord, le rendre inutilisable

2
git filter-repo --path config/secret.yml --invert-paths

Le retirer de l’historique

3
git push --force --all

Remplacer l’historique distant

Dépannage

Impossible de créer une nouvelle sauvegarde

Cause : refs/original existe depuis une exécution précédente

Supprimez-le (git update-ref -d refs/original/refs/heads/main) ou utilisez -f

Astuces et pièges

Bonnes pratiques

  • ✓Utilisez plutôt git filter-repo.
  • ✓Sauvegardez le dépôt avant toute réécriture.

Erreurs fréquentes

  • ✗Réécrire l’historique partagé sans prévenir l’équipe.
  • ✗Croire qu’une réécriture rend sûr un secret divulgué — changez le secret.

FAQ

A:

Elle est très lente et a de nombreux pièges qui corrompent la réécriture en silence ; filter-repo corrige les deux.