Si git pull échoue alors que votre projet Mac semble propre, identifiez d’abord l’erreur exacte : Git protège peut-être des fichiers locaux ou ignorés, masque des modifications de sous-modules ou refuse de combiner des historiques de branches divergents. Dans Terminal, examinez l’état complet du dépôt et le suivi des branches avant de modifier des fichiers ou de choisir un comportement de fusion ou de rebasage.

Commencez dans le dépôt et capturez l’erreur réelle

Ouvrez Terminal, placez-vous dans le dossier du projet et réexécutez le pull uniquement si vous avez besoin de reproduire le message. Terminal utilise zsh par défaut sur les versions actuelles de macOS, et les commandes entre guillemets ci-dessous fonctionnent sous zsh et bash. Guide de Terminal par Apple

cd "/path/to/your/project"
git status --short --branch
git pull

Remplacez le chemin entre guillemets par le dossier réel de votre projet. Lisez l’intégralité de l’erreur de pull. « Your local changes … would be overwritten » indique une obstruction au niveau des fichiers. « Divergent branches » ou « Not possible to fast-forward » signifie que les historiques de commits local et distant (upstream) nécessitent un choix de réconciliation. Ces problèmes peuvent sembler similaires dans un client graphique, mais ils exigent des démarches différentes.

Recherchez les fichiers masqués par un affichage d'état abrégé

Un affichage d'état court peut omettre des détails importants. Lancez une inspection plus complète en lecture seule :

git status --untracked-files=all --ignored=matching --ignore-submodules=none
git diff --
git diff --cached --

git status signale normalement les fichiers non suivis, mais un paramètre local peut les masquer ; --untracked-files=all liste les fichiers individuels à l'intérieur des dossiers non suivis. Les fichiers ignorés sont exclus sauf demande contraire, ainsi --ignored=matching révèle les chemins ignorés qui correspondent aux règles d’exclusion. --ignore-submodules=none demande à status de signaler les modifications des sous-modules, même si la configuration les masquerait autrement. Git documente ces modes d'état et précise que les chemins ignorés reçoivent un marqueur de statut distinct. Documentation de Git status

Les deux commandes git diff affichent respectivement les modifications de l'arbre de travail suivies et les modifications indexées (staged). Elles ne listent pas le contenu des fichiers ignorés ou non suivis. Un résultat « propre » provenant d'une interface graphique, d'un autre dossier ou d'une vue de statut filtrée ne garantit donc pas que chaque obstruction soit visible ; utilisez Terminal dans le même dépôt et examinez le chemin exact indiqué par Git. Les règles d'exclusion gardent intentionnellement les fichiers non suivis correspondants hors de la sortie standard de status. Documentation de Git ignore

Si le chemin signalé est ignoré ou non suivi, inspectez-le avant de le déplacer ou de le supprimer. N'exécutez pas git clean, git reset --hard, ou n'écrasez pas le chemin comme un raccourci de diagnostic : ces commandes peuvent supprimer du travail ou des fichiers locaux. S'il contient quelque chose dont vous avez besoin, faites-en une copie séparée ou préservez-le d'une autre manière avant de résoudre le conflit.

Vérifiez les sous-modules et les indicateurs d'index

Un dépôt contenant des sous-modules peut sembler propre à son niveau supérieur alors qu'un sous-module comporte des modifications locales, des fichiers non suivis ou un commit extrait différent. La commande de statut enrichie ci-dessus demande à Git de ne pas ignorer l'état des sous-modules. Vous pouvez également entrer dans le répertoire du sous-module concerné et y exécuter git status --untracked-files=all ; chaque sous-module possède son propre arbre de travail et son propre état.

Dans un cas moins fréquent, l'index de Git peut comporter des indicateurs (flags) qui influencent la manière dont il traite les chemins. assume-unchanged indique à Git de supposer qu'un fichier correspond à l'index, et skip-worktree peut éviter la mise à jour d'un chemin lors d'opérations telles que pull. Inspectez les entrées inhabituelles avec :

git ls-files -v

Cette commande liste les chemins suivis avec les balises d'index ; les balises en minuscules peuvent indiquer des entrées assume-unchanged, tandis que S indique skip-worktree. Considérez cela comme un indice d'inspection, et non comme une commande de nettoyage. N'effacez pas aveuglément les indicateurs sur l'ensemble du dépôt ; si un chemin affecté est mentionné, vérifiez son contenu ainsi que la configuration de sparse-checkout du projet avant de modifier son état dans l'index. Documentation de Git update-index

Si le message concerne des branches divergentes

Un arbre de travail propre ne signifie pas que votre branche locale et sa branche amont partagent le même historique. Vérifiez quelle branche est active et ce qu'elle suit :

git branch --show-current
git branch -vv
git status --short --branch

Les sorties de status et de branch peuvent indiquer si la branche locale est en avance, en retard ou divergente par rapport à sa branche amont. Git pull commence par récupérer les modifications distantes (fetch), puis intègre la branche amont configurée. Son comportement par défaut en avance rapide uniquement (fast-forward-only) s'interrompt lorsque les branches locale et distante ont divergé ; il s'agit d'une politique d'historique, et non d'une preuve de modifications de fichiers non validées. Documentation de Git pull

Si des commits locaux existent, choisissez une méthode conforme aux règles de collaboration du projet : rebase réapplique les commits locaux par-dessus la branche amont, tandis que merge réunit les historiques et peut créer un commit de fusion. Consultez les responsables du dépôt ou vérifiez les conventions de l'équipe en cas de doute. Évitez de définir une préférence globale pour pull ou de réinitialiser la branche de force (force-reset) simplement pour faire taire l'erreur ; aucune de ces solutions n'explique ce qu'il doit advenir de ces commits.

Utilisez l'erreur pour déterminer la prochaine vérification

Une collision de fichiers nécessite de vérifier le chemin indiqué, y compris les fichiers ignorés et les sous-modules. Un message de divergence nécessite d'inspecter l'historique des branches et de décider comment intégrer les commits. Si le statut reste propre mais que l'erreur mentionne un chemin, confirmez que Terminal se trouve bien dans l'extraction attendue, inspectez directement ce chemin et vérifiez les indicateurs d'index pertinents. Le message exact constitue le diagnostic le plus utile : préservez les fichiers et les commits locaux jusqu'à ce que vous compreniez quel type de refus Git signale.

Sources