git pull
Récupérer depuis un autre dépôt ou une branche locale et intégrer
La commande 'git pull' récupère le contenu d’un dépôt distant et l’intègre aussitôt dans votre branche locale. C’est en gros 'git fetch' suivi de 'git merge' (ou de 'git rebase' avec l’option --rebase). C’est la façon la plus courante de synchroniser votre dépôt local avec les modifications des autres. Quand vous lancez git pull, Git télécharge d’abord tous les nouveaux commits du dépôt distant, puis les intègre dans votre branche courante. Si votre branche est simplement en retard, il fait un fast-forward ; si les deux côtés ont de nouveaux commits, le Git moderne s’arrête et vous demande de choisir entre merge et rebase (--no-rebase / --rebase, ou le réglage pull.rebase). En cas de modifications en conflit, Git s’arrête et vous demande de résoudre les conflits avant de terminer la fusion.
Synopsis
git pull [--rebase | --no-rebase] [--ff-only | --ff | --no-ff] [--commit | --no-commit] [--autostash | --no-autostash] [-q | --quiet] [-v | --verbose] [--depth=<depth>] [--prune] [--tags | --no-tags] [--recurse-submodules[=yes|on-demand|no]] [<repository> [<refspec>...]]Options
Choisir la bonne option
Stratégie de pull : merge ou rebase
Le choix fondamental qui influence votre historique de commits
| Commande | Crée un commit de fusion | Style d’historique | Idéal pour |
|---|---|---|---|
git pull | Dépend de la configuration (échoue en cas de divergence si rien n’est configuré) | Défini par pull.rebase / pull.ff | Fast-forward quand on est seulement en retard |
git pull --rebase | No | Linéaire | Branches de fonctionnalité, historique propre |
git pull --no-rebase | Oui (en cas de divergence) | Préserve les branches | Passer outre la config rebase, forcer merge |
git pull --ff-only | No | Linéaire (échoue en cas de divergence) | Éviter toute fusion accidentelle |
Options de sécurité et de contrôle
Des options pour éviter les erreurs et garder le contrôle
| Commande | Empêche | Comportement | Quand l’utiliser |
|---|---|---|---|
--ff-only | Fusions inattendues | Échoue si le fast-forward est impossible | CI/CD, branches protégées |
--no-commit | Commit automatique | Fusionne mais s’arrête avant le commit | Relire la fusion avant de committer |
--autostash | Erreurs de répertoire de travail modifié | Stash → pull → pop | Synchronisation rapide avec du travail non committé |
--dry-run | N’importe quelles modifications | Montre ce que fetch téléchargerait ; aucune fusion | Prévisualiser les références entrantes |
Ce qui est récupéré
Contrôler quelles références et quel historique sont téléchargés
| Commande | Récupère les tags | Récupère tout l’historique | Cas d’usage |
|---|---|---|---|
git pull | Auto (tags suivis) | Oui | Workflow normal |
--tags | Tous les tags | Oui | Synchroniser les versions publiées |
--no-tags | No | Oui | Économiser la bande passante, synchroniser une seule branche |
--depth=N | Auto (tags suivis) | Seulement les N derniers commits | Gros dépôts, builds de CI |
--unshallow | Auto (tags suivis) | Convertit un clone superficiel en clone complet | Besoin de tout l’historique après un clone superficiel |
Gestion des dépôts distants et des branches
Des options pour gérer plusieurs dépôts distants et les références périmées
| Commande | Portée | Nettoie | Scénario |
|---|---|---|---|
git pull origin main | Un seul dépôt distant/une seule branche | No | Pull standard depuis origin |
--all | Tous les dépôts distants | No | Synchroniser depuis origin + upstream |
--prune | Un seul dépôt distant | Branches supprimées | Retirer les références de suivi périmées |
Scénarios avancés
Des options pour les situations complexes ou inhabituelles
| Commande | Résout | Niveau de risque | Scénario typique |
|---|---|---|---|
--allow-unrelated-histories | Aucun ancêtre commun | Moyen | Fusionner deux dépôts séparés |
-s <strategy> | Besoins de fusion particuliers (n’évite pas les conflits) | Faible | Imposer un algorithme de fusion |
--recurse-submodules | Sous-modules pas à jour | Faible | Projets avec des sous-modules git |
Exemples de workflows
git statusVérifier les modifications non committées qui pourraient entrer en conflit
git stashMettre de côté le travail non committé si besoin (ou utiliser --autostash)
git pull --rebase origin mainFaire un pull avec rebase pour garder l’historique propre
git stash popRestaurer le travail mis de côté si vous l’aviez fait
git checkout feature-branchPasser sur votre branche de fonctionnalité
git pull --no-rebase origin mainFusionner le dernier main dans votre branche de fonctionnalité (explicitement, puisque les branches ont divergé)
git push origin feature-branchPousser la branche de fonctionnalité à jour
git fetch originTélécharger les modifications distantes sans toucher au répertoire de travail
git log HEAD..origin/mainVoir quels commits vous allez récupérer
git diff HEAD...origin/mainRelire les modifications faites à distance
git pull origin mainFaire le pull une fois satisfait des modifications
git pull --no-rebase origin mainTenter un pull par merge - peut provoquer des conflits
git statusVoir quels fichiers sont en conflit (marqués 'both modified')
(edit conflicted files)Ouvrir les fichiers et résoudre les marqueurs de conflit (<<<<<<<, =======, >>>>>>>)
git add <resolved-files>Indexer les fichiers résolus
git commitTerminer la fusion avec un commit
git pull --rebase --autostash origin mainMettre automatiquement les modifications de côté, faire le pull, puis les réappliquer
Dépannage
Your local changes would be overwritten by merge
Cause : Vous avez des modifications non committées dans des fichiers que le pull modifierait
Committez d’abord vos modifications (git add . && git commit), mettez-les de côté (git stash), ou utilisez git pull --rebase --autostash
git stash && git pull && git stash popRefusing to merge unrelated histories
Cause : Les dépôts distant et local n’ont aucun ancêtre commun (par ex. un pull dans un dépôt tout juste initialisé)
Autoriser la fusion d’historiques sans lien, ce qui est courant quand on ajoute un dépôt distant à un dépôt local existant
git pull --allow-unrelated-histories origin mainConflit de fusion dans un ou plusieurs fichiers
Cause : Vous et le dépôt distant avez modifié les mêmes lignes d’un fichier
Ouvrez les fichiers en conflit, cherchez les marqueurs (<<<<<<<, =======, >>>>>>>), corrigez, puis git add et git commit. Ou abandonnez avec git merge --abort
git add <resolved-file> && git commitNot possible to fast-forward, aborting
Cause : Vous avez utilisé --ff-only (ou pull.ff=only est configuré) mais votre branche locale a divergé du dépôt distant
Utilisez plutôt un rebase (git pull --rebase) ou acceptez un commit de fusion (git pull --no-rebase)
git pull --rebase origin mainCannot pull with rebase: You have unstaged changes
Cause : Un pull par rebase exige un arbre de travail propre, et vous avez des modifications non committées
Committez ou mettez de côté vos modifications, ou utilisez autostash pour les gérer automatiquement
git pull --rebase --autostashNo tracking information for the current branch
Cause : Votre branche n’est pas configurée pour suivre une branche distante
Définissez explicitement la branche upstream, ou précisez le dépôt distant et la branche dans la commande pull
git branch --set-upstream-to=origin/main main'origin' does not appear to be a git repository
Cause : Aucun dépôt distant nommé 'origin' n’est configuré
Vérifiez vos dépôts distants avec git remote -v, puis ajoutez origin ou utilisez le bon nom de dépôt distant
git remote add origin <url>You have divergent branches and need to specify how to reconcile them
Cause : Les deux côtés ont de nouveaux commits et ni pull.rebase ni pull.ff n’est configuré, donc le Git moderne refuse de deviner (les versions 2.27+ plus anciennes se contentaient d’avertir)
Précisez merge (--no-rebase) ou rebase (--rebase), ou configurez un défaut avec git config pull.rebase
git config --global pull.rebase trueAstuces et pièges
Bonnes pratiques
- ✓Vérifiez toujours git status avant un pull pour éviter les conflits avec des modifications non committées
- ✓Utilisez git pull --rebase pour garder un historique propre et linéaire sur les branches de fonctionnalité
- ✓Configurez pull.rebase=true globalement si vous préférez le rebase par défaut : git config --global pull.rebase true
- ✓Faites d’abord git fetch quand vous voulez relire les modifications avant de les intégrer
- ✓Utilisez --ff-only pour être sûr de ne créer aucun commit de fusion par accident
- ✓Configurez le suivi de branche avec git push -u lors du premier push pour simplifier les pulls suivants
- ✓Utilisez --autostash quand vous avez des modifications non committées mais devez faire un pull vite
- ✓Faites régulièrement un pull de main/master pour éviter plus tard des fusions grosses et complexes
- ✓Résolvez les conflits tout de suite - ne laissez jamais votre dépôt dans un état de conflit
- ✓Utilisez git pull --prune pour nettoyer les branches de suivi distantes périmées
- ✓Envisagez git fetch + git merge pour mieux contrôler l’intégration
- ✓Vérifiez toujours que vous êtes sur la bonne branche avant un pull pour ne pas mélanger les modifications
Erreurs fréquentes
- ✗Faire un pull avec des modifications non committées : cela peut provoquer des conflits ou échouer complètement. Committez ou mettez de côté vos modifications d’abord, ou utilisez --autostash pour le gérer automatiquement.
- ✗Ne pas comprendre la différence entre pull et fetch : 'git pull' fusionne automatiquement, ce qui peut surprendre. Faites d’abord 'git fetch' si vous voulez relire les modifications avant de les intégrer.
- ✗Utiliser merge quand rebase serait plus propre : sur les branches de fonctionnalité, 'git pull --rebase' donne un historique linéaire plus propre, sans commits de fusion inutiles.
- ✗Ignorer les conflits de fusion : après un pull avec conflits, il faut les résoudre et committer. Ne laissez jamais votre dépôt dans un état de conflit.
- ✗Faire un pull dans la mauvaise branche : vérifiez toujours votre branche courante avec 'git status' avant un pull. Tirer dans main alors que vous visiez une branche de fonctionnalité peut poser problème.
FAQ
git fetch télécharge seulement les nouveaux commits du dépôt distant sans modifier votre répertoire de travail ni vos branches locales. git pull fait un fetch ET fusionne (ou rebase) automatiquement ces modifications dans votre branche courante. Utilisez fetch quand vous voulez relire les modifications avant de les intégrer.
Utilisez --rebase quand vous voulez un historique propre et linéaire (surtout sur les branches de fonctionnalité). Vos commits locaux sont rejoués par-dessus les commits récupérés au lieu de créer un commit de fusion. Utilisez le pull normal (merge) quand vous voulez préserver exactement l’historique de quand les modifications ont été faites.
Le fast-forward a lieu quand votre branche locale n’a aucun commit que le dépôt distant n’a pas. Git avance simplement le pointeur de votre branche jusqu’au distant - aucun commit de fusion n’est nécessaire. Si vous avez des commits locaux, Git doit soit créer un commit de fusion, soit faire un rebase - et, sauf si vous passez --rebase/--no-rebase ou configurez pull.rebase, le Git moderne s’arrête avec « Need to specify how to reconcile divergent branches ».
Utilisez git pull --rebase pour rejouer vos commits locaux par-dessus les commits distants et obtenir un historique linéaire. Ou utilisez git pull --ff-only, qui ne réussit que si un fast-forward est possible (échoue si vous avez des commits locaux en avance).
Ça dépend. Avec un pull par merge, Git l’accepte si les commits entrants ne touchent pas les fichiers que vous avez modifiés ; sinon il refuse avec « Your local changes ... would be overwritten by merge ». Avec --rebase, la moindre modification non committée bloque le pull. Bonne pratique : committez d’abord vos modifications, ou utilisez git pull --rebase --autostash pour les mettre de côté et les restaurer automatiquement.
Git met la fusion en pause et marque les fichiers en conflit. Ouvrez chacun d’eux, cherchez les marqueurs de conflit (<<<<<<<, =======, >>>>>>>), corrigez, puis git add du fichier et git commit pour terminer la fusion. Utilisez git merge --abort pour annuler (ou, pour git pull --rebase, git rebase --continue / git rebase --abort).
Juste après le pull, lancez git reset --hard ORIG_HEAD - Git garde votre ancienne pointe dans ORIG_HEAD pour les fusions, fast-forwards et rebases. N’utilisez pas HEAD~1 : un fast-forward a pu amener plusieurs commits. --hard jette aussi les modifications non committées. Si ORIG_HEAD a bougé depuis, retrouvez l’ancienne pointe avec git reflog.
En général, vous tirez depuis la mauvaise branche ou le mauvais dépôt distant. Vérifiez : git branch -vv pour les infos de suivi, git remote -v pour les dépôts distants, puis git fetch --all suivi de git log origin/main pour voir les commits distants.
git pull origin main précise explicitement le dépôt distant et la branche d’où tirer. git pull (sans argument) utilise la branche de suivi configurée pour votre branche courante. Si aucun suivi n’est configuré, une erreur vous demande de les préciser.
Globalement : git config --global pull.rebase true (pour rebase) ou git config --global pull.rebase false (pour merge). Vous pouvez aussi le définir par dépôt sans --global, ou par branche avec git config branch.<name>.rebase true.