Guide complet de Git Stash

Vous êtes en plein milieu d’une fonctionnalité, profondément engagé dans un refactoring, lorsqu’un coéquipier vous contacte au sujet d’un bug critique en production. Votre répertoire de travail est un fouillis de modifications à moitié terminées. Vous n’êtes pas prêt à committer, mais vous ne pouvez pas changer de branche avec du travail non committé qui traîne.

C’est exactement à cela que sert git stash. Ce guide couvre toutes les commandes git stash que vous utiliserez réellement, comment gérer les conflits, ainsi que les astuces de workflow qui rendent le stashing naturel plutôt que risqué.

Qu’est-ce que Git Stash ?

git stash enregistre vos modifications non committées — qu’elles soient indexées (staged) ou non — dans une pile locale et ramène votre répertoire de travail à l’état du dernier commit (HEAD). Vous pouvez restaurer ces modifications ultérieurement, sur la même branche ou sur une autre.

Les stashes sont uniquement locaux. Ils ne sont pas envoyés vers votre remote avec git push, et ne sont pas partagés avec vos coéquipiers.

Ce qui est stashé par défaut :

• Les modifications indexées (index)
• Les modifications non indexées sur les fichiers suivis

Ce qui n’est PAS stashé par défaut :

• Les fichiers non suivis (nouveaux fichiers pas encore ajoutés à Git)
• Les fichiers ignorés

Commandes Git Stash essentielles

Enregistrer les modifications avec git stash push

git stash

git stash seul est un raccourci pour git stash push. C’est le moyen le plus rapide d’obtenir un répertoire de travail propre.

Ajoutez un message descriptif pour savoir ce qu’il contient plus tard :

git stash push -m "WIP: refactor auth middleware"

Remarque : L’ancienne syntaxe git stash save est dépréciée. Utilisez plutôt git stash push.

Stasher les fichiers non suivis

Par défaut, les nouveaux fichiers que vous n’avez pas encore indexés sont laissés en place. Utilisez -u pour les inclure :

git stash push -u -m "WIP: new login component"

Pour stasher également les fichiers correspondant à .gitignore, utilisez -a (--all). Cela est rarement nécessaire, mais utile lorsque les fichiers ignorés interféreraient avec un changement de branche ou un build.

Stasher des fichiers spécifiques

Vous pouvez stasher uniquement certains fichiers à l’aide d’un pathspec :

git stash push -m "WIP: api changes" -- src/api/client.js src/api/utils.js

Cela laisse tout le reste de votre répertoire de travail intact.

Lister vos stashes

git stash list

Sortie :

stash@{0}: On main: WIP: refactor auth middleware
stash@{1}: WIP on feature/login: 9ab3c12 Add login form

Les stashes sont stockés dans une pile LIFO (last-in, first-out). stash@{0} est toujours le plus récent.

Inspecter un stash avant de l’appliquer

git stash show stash@{0}        # résumé
git stash show -p stash@{0}     # diff complet

Git Stash Pop vs Apply : lequel choisir ?

C’est l’une des sources de confusion les plus fréquentes avec les commandes git stash.

Utilisez pop lorsque vous en avez terminé avec le stash et que vous voulez simplement récupérer vos modifications. Utilisez apply lorsque vous souhaitez appliquer le même stash à plusieurs branches, ou lorsque vous voulez tester le résultat avant de vous engager à le supprimer.

Pour appliquer un stash spécifique :

git stash pop stash@{1}
git stash apply stash@{1}

Restaurer l’état indexé avec --index

Par défaut, l’application d’un stash restaure toutes les modifications comme non indexées. Si vous souhaitez restaurer la distinction indexé/non indexé telle qu’elle était au moment du stash, utilisez --index :

git stash pop --index

Résoudre les conflits lors de l’application d’un stash

Si la branche a évolué depuis votre stash, vous pourriez rencontrer des conflits :

CONFLICT (content): Merge conflict in src/api/client.js
The stash entry is kept in case you need it again.

Les commandes pop et apply conservent toutes deux le stash dans la pile lorsqu’un conflit survient. Pour résoudre :

1. Exécutez git status pour identifier les fichiers en conflit.
2. Ouvrez chaque fichier et résolvez les marqueurs de conflit.
3. Indexez les fichiers résolus : git add src/api/client.js.
4. Supprimez manuellement le stash une fois satisfait : git stash drop stash@{0}.

Quand les conflits deviennent complexes : utilisez git stash branch

Si les conflits sont trop enchevêtrés, git stash branch est la solution de secours la plus propre. Elle crée une nouvelle branche à partir du commit exact où vous avez stashé, puis y applique le stash. Comme la branche démarre depuis le commit où le stash a été créé, cela permet souvent d’éviter les conflits :

git stash branch fix/auth-refactor stash@{0}

Si l’application réussit, le stash est automatiquement supprimé.

Gérer et nettoyer les stashes

git stash drop stash@{0}   # supprimer un stash spécifique
git stash clear            # supprimer TOUS les stashes (irréversible)

⚠️ git stash clear est définitif. Il n’y a pas d’annulation possible. Vérifiez bien avant de l’exécuter.

Avancé : stashing partiel et stash indexé uniquement

Le mode patch interactif vous permet de choisir quels hunks stasher :

git stash push -p

Git vous présente chaque modification et vous demande s’il faut la stasher. Utile lorsqu’un fichier contient à la fois des modifications liées et non liées.

Stasher uniquement les modifications indexées (Git 2.35 et versions ultérieures) :

git stash push --staged

Cela stashe ce qui se trouve dans votre index et laisse le travail non indexé en place — pratique pour isoler une modification que vous voulez mettre de côté sans perdre votre progression actuelle.

Conserver les modifications indexées dans l’index tout en stashant le reste :

git stash push --keep-index

Notez que --keep-index stashe quand même à la fois les modifications indexées et non indexées ; il laisse simplement les modifications indexées en place dans votre répertoire de travail après le stash.

Récupérer un Git Stash supprimé

Si vous supprimez ou videz accidentellement vos stashes, ils peuvent encore être récupérables sous forme de commits orphelins (dangling commits) dans votre dépôt. Les entrées de stash sont stockées sous forme de commits de merge, vous pouvez donc les rechercher avec :

git fsck --unreachable | grep commit | cut -d' ' -f3 | xargs git log --merges --no-walk --grep=WIP

Cela liste les commits de merge inaccessibles qui ressemblent à des entrées de stash. Une fois que vous avez identifié le hash du commit souhaité, restaurez-le avec :

git stash apply <commit-hash>

La récupération n’est pas garantie — le ramasse-miettes (garbage collector) de Git finira par éliminer les objets inaccessibles — alors agissez rapidement.

Transférer des stashes entre machines

Les versions récentes de Git ont ajouté git stash export et git stash import, qui permettent de transférer les stashes via les workflows habituels de fetch et push.

Pour les versions antérieures de Git, ou pour de simples transferts ponctuels, des alternatives pratiques existent toujours :

• Exporter sous forme de patch : git stash show -p stash@{0} > my-stash.patch, puis l’appliquer ailleurs avec git apply my-stash.patch.
• Le committer sur une branche jetable : créez une branche, committez le travail, poussez-la vers un remote, puis pullez et réinitialisez sur l’autre machine.

Les patches restent généralement la méthode la plus simple pour les transferts ponctuels.

Bonnes pratiques pour Git Stash

• Ajoutez toujours un message. git stash push -m "WIP: quoi et pourquoi" vous évite de fixer une liste d’entrées anonymes du type WIP on main.
• Le stash est un stockage temporaire, pas une sauvegarde. Committez votre travail lorsqu’il atteint un point de contrôle logique.
• Gardez votre liste de stashes courte. Examinez-la régulièrement et supprimez les stashes dont vous n’avez plus besoin.
• Faites un pull avant de pop. Mettre à jour votre branche avant de restaurer un stash réduit les risques de conflits.
• Préférez apply à pop en cas de doute. Vous pourrez toujours supprimer le stash manuellement une fois que vous aurez confirmé que tout est en ordre.

Référence rapide : commandes Git Stash

Conclusion

git stash est l’une de ces commandes qui semble optionnelle jusqu’à ce que vous en ayez réellement besoin — et qui devient alors une partie intégrante de votre workflow quotidien. Les habitudes clés : nommez toujours vos stashes, gardez la liste propre, et tournez-vous vers git stash branch lorsque les conflits rendent un simple pop peu pratique. Bien utilisé, le stashing préserve la propreté de votre historique Git et rend vos changements de contexte indolores.

FAQ

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.