Intégration Git - Depannage

Ce guide de dépannage couvre les problèmes les plus fréquents liés à l'intégration Git dans Claude Code : commits qui échouent, conflits de merge non détectés, hooks pre-commit bloquants et erreurs d'authentification. Diagnostiquez chaque symptôme avec les commandes fournies et appliquez la solution adaptée en moins de 5 minutes.

L'intégration Git dans Claude Code est le mécanisme qui permet à l'agent IA de créer des commits, gérer des branches et résoudre des conflits directement depuis votre terminal. cette intégration repose sur le binaire Git local (version 2.39 ou supérieure) et le système de permissions de Claude Code v1.0.23. plus de 78 % des incidents remontés concernent la configuration Git locale plutôt que Claude Code lui-même.

Quels sont les symptômes les plus courants et leurs solutions ?

Avant de plonger dans le détail de chaque problème, consultez ce tableau de référence. Il regroupe les 12 symptômes les plus fréquents avec leur cause probable et la commande de résolution. Vous pouvez aussi vous appuyer sur le guide complet de dépannage Claude Code pour les erreurs non liées à Git.

Symptôme	Cause probable	Solution
`fatal: not a git repository`	Répertoire non initialisé ou `.git` manquant	Exécutez `git init` ou vérifiez le chemin du projet
`error: failed to push some refs`	Branche distante en avance sur la locale	Lancez `git pull --rebase origin main` avant le push
Commit refusé par Claude Code	Permission `Bash` non accordée pour `git commit`	Acceptez la permission ou ajoutez-la dans `.claude/settings.json`
Hook pre-commit qui bloque	Linter ou formatter qui échoue sur le code généré	Corrigez le code, puis relancez `git add . && git commit`
`Author identity unknown`	`user.name` ou `user.email` non configuré	Configurez `git config --global user.name "Nom"`
Conflits de merge non résolus	Fichiers modifiés simultanément par vous et Claude Code	Ouvrez les fichiers marqués `<<<<<<<` et résolvez manuellement
`Permission denied (publickey)`	Clé SSH absente ou non ajoutée à l'agent	Ajoutez la clé avec `ssh-add ~/.ssh/id_ed25519`
Diff vide après génération	Claude Code a édité puis annulé les changements	Vérifiez l'historique avec `git reflog` pour retrouver les modifications
`loose object is corrupt`	Corruption du dépôt Git local	Réparez avec `git fsck --full` puis `git gc --prune=now`
Branch checkout échoue	Modifications non commitées dans le working tree	Sauvegardez avec `git stash` avant de changer de branche
`fatal: refusing to merge unrelated histories`	Historiques Git divergents	Ajoutez le flag `--allow-unrelated-histories` au merge
Token GitHub expiré	Personal Access Token (PAT) périmé	Régénérez le token dans GitHub Settings > Developer settings

Ce tableau couvre environ 90 % des cas rencontrés en formation. En pratique, 6 problèmes sur 10 se résolvent par une simple reconfiguration Git locale.

À retenir : Consultez ce tableau en premier pour identifier rapidement votre problème avant d'explorer les sections détaillées.

Comment résoudre l'erreur « fatal: not a git repository » ?

Cette erreur signifie que Claude Code ne détecte aucun dépôt Git dans le répertoire courant. Le dossier .git est soit absent, soit situé dans un répertoire parent inaccessible. En pratique, 15 % des débutants lancent Claude Code depuis leur dossier $HOME au lieu du dossier projet.

Vérifiez d'abord votre répertoire de travail avec la commande suivante :

pwd
ls -la .git

Si le dossier .git n'existe pas, initialisez un nouveau dépôt :

git init
git add .
git commit -m "Initial commit"

Si vous travaillez dans un monorepo, le .git peut se trouver plusieurs niveaux au-dessus. Utilisez git rev-parse --show-toplevel pour localiser la racine du dépôt. Pour approfondir la configuration initiale, consultez le tutoriel d'intégration Git qui détaille chaque étape.

À retenir : Lancez toujours Claude Code depuis la racine de votre projet Git, là où se trouve le dossier .git.

Comment corriger les problèmes d'authentification Git ?

L'authentification Git repose sur deux mécanismes principaux : les clés SSH et les tokens HTTPS (PAT). Claude Code v1.0.23 utilise le credential helper configuré dans votre environnement. les Personal Access Tokens classiques ont été dépréciés au profit des Fine-grained tokens, ce qui cause des erreurs chez 23 % des utilisateurs migrant vers le nouveau système.

Diagnostic SSH

Testez votre connexion SSH avec cette commande :

ssh -T git@github.com

Si vous obtenez Permission denied, vérifiez que votre clé est chargée :

ssh-add -l

Une sortie vide signifie qu'aucune clé n'est active. Ajoutez votre clé avec ssh-add ~/.ssh/id_ed25519. Le fichier ~/.ssh/config doit contenir une entrée pour GitHub.

Diagnostic HTTPS

Pour les dépôts clonés en HTTPS, vérifiez la configuration du credential helper :

git config --global credential.helper

Sur macOS, la valeur attendue est osxkeychain. Sur Linux, utilisez store ou cache --timeout=3600 pour conserver le token 1 heure (3 600 secondes). Consultez le guide d'intégration Git pour configurer l'authentification de bout en bout.

À retenir : Privilégiez SSH avec ed25519 pour une authentification fiable et sans expiration de token.

Pourquoi les hooks pre-commit bloquent-ils Claude Code ?

Les hooks pre-commit sont des scripts Git exécutés automatiquement avant chaque commit. Un hook pre-commit est un script shell ou un programme déclenché par git commit pour valider le code avant enregistrement. Quand Claude Code génère du code, ce code passe par les mêmes hooks que vos commits manuels : ESLint, Prettier, Black, ou tout linter configuré.

En pratique, 35 % des blocages de commit dans Claude Code proviennent d'un hook pre-commit qui échoue sur du formatage. Le problème survient car Claude Code ne connaît pas forcément vos règles locales de formatage.

Diagnostiquez le hook en exécutant manuellement :

cat .git/hooks/pre-commit
# ou avec husky
cat .husky/pre-commit

Outil	Fichier de config	Commande de fix auto
ESLint	`.eslintrc.json`	`npx eslint --fix .`
Prettier	`.prettierrc`	`npx prettier --write .`
Black (Python)	`pyproject.toml`	`black .`

Si vous souhaitez que Claude Code contourne temporairement le hook, vous pouvez ajouter cette instruction dans votre fichier CLAUDE.md. Mais attention : cette approche est déconseillée en production. Consultez les erreurs courantes liées aux commandes slash pour d'autres cas similaires.

À retenir : Configurez vos hooks pour qu'ils fassent du fix automatique (--fix) plutôt que de simplement rejeter le commit.

Comment résoudre les conflits de merge générés par Claude Code ?

Un conflit de merge est une situation où Git ne peut pas fusionner automatiquement deux versions d'un même fichier. Un conflit de merge survient quand vous et Claude Code modifiez les mêmes lignes d'un fichier simultanément. Claude Code ne résout pas automatiquement les conflits - il vous signale leur présence.

Identifiez les fichiers en conflit :

git status
# cherchez les lignes "both modified"
git diff --name-only --diff-filter=U

Chaque conflit est délimité par des marqueurs <<<<<<<, ======= et >>>>>>>. Ouvrez le fichier concerné et choisissez la version correcte. Vous pouvez aussi demander à Claude Code de vous aider à résoudre le conflit - il analysera les deux versions et proposera une fusion.

la commande git mergetool lance un outil visuel de résolution. VS Code intègre un résolveur natif accessible via la palette de commandes. Pour les cas récurrents, consultez le guide de référence rapide de l'intégration Git qui liste les commandes de merge essentielles.

Stratégie	Commande	Cas d'usage
Garder votre version	`git checkout --ours fichier.ts`	Vos modifications sont prioritaires
Garder la version distante	`git checkout --theirs fichier.ts`	Le code distant est plus récent
Merge manuel	Éditer les marqueurs `<<<<<<<`	Les deux versions contiennent du code utile
Abandon du merge	`git merge --abort`	Recommencer sur une base propre

En pratique, le merge manuel reste la méthode la plus sûre dans 70 % des cas.

À retenir : Utilisez git diff --name-only --diff-filter=U pour lister instantanément tous les fichiers en conflit.

Quelles commandes de diagnostic utiliser en priorité ?

Concrètement, un diagnostic efficace repose sur 6 commandes Git que vous devez connaître. Ces commandes couvrent 95 % des scénarios de dépannage. Vous pouvez les copier directement dans votre terminal.

# 1. État du dépôt
git status

# 2. Historique récent (5 derniers commits)
git log --oneline -5

# 3. Modifications non commitées
git diff --stat

# 4. Vérifier l'intégrité du dépôt
git fsck --full

# 5. Historique des opérations (reflog)
git reflog --date=relative -10

# 6. Configuration Git active
git config --list --show-origin

La commande git reflog est un journal de référence qui enregistre chaque mouvement de HEAD dans votre dépôt. C'est votre filet de sécurité : même après un reset, vous pouvez retrouver un commit perdu grâce au reflog. le reflog conserve les entrées pendant 90 jours par défaut.

Vous rencontrerez souvent le besoin de vérifier la version de Git installée. Exécutez git --version - Claude Code nécessite Git 2.39 ou supérieur pour fonctionner correctement. En 2026, la version stable est Git 2.47. Consultez le dépannage de l'installation et premier lancement si Git n'est pas détecté.

À retenir : Commencez toujours par git status et git reflog - ces deux commandes répondent à 80 % des questions de diagnostic.

Comment débloquer un push refusé vers le dépôt distant ?

Un push refusé est un rejet par le serveur distant lorsque votre branche locale est en retard par rapport à la branche distante. Ce problème survient dans 40 % des cas quand vous travaillez à plusieurs sur la même branche. Claude Code crée des commits locaux, mais si un collègue a poussé entre-temps, Git refuse votre push.

Exécutez cette séquence pour résoudre le problème :

git fetch origin
git rebase origin/main
# Résolvez les éventuels conflits, puis :
git push origin main

Le rebase est une opération de réécriture d'historique qui replace vos commits au-dessus des commits distants. Concrètement, cela donne un historique linéaire plus lisible qu'un merge commit. Si vous préférez un merge classique, remplacez rebase par merge.

Scénario	Commande recommandée	Résultat
Push simple refusé	`git pull --rebase origin main && git push`	Historique linéaire
Force push nécessaire (branche perso)	`git push --force-with-lease origin feature`	Écrase la branche distante avec protection
Push sur branche protégée	Créer une Pull Request	Passage par review obligatoire

Vous pouvez consulter la page principale de l'intégration Git pour comprendre comment Claude Code gère les opérations push. Vous y trouverez aussi la configuration des branches protégées.

À retenir : N'utilisez jamais --force sur main - préférez --force-with-lease qui vérifie que personne n'a poussé entre-temps.

Faut-il configurer CLAUDE.md pour améliorer l'intégration Git ?

Le fichier CLAUDE.md est le fichier de mémoire persistante de Claude Code qui stocke les instructions personnalisées pour chaque projet. Oui, configurer CLAUDE.md améliore considérablement la qualité des commits générés par Claude Code. Ce fichier transmet à l'IA vos conventions de nommage, votre workflow Git et vos règles de commit.

Voici comment ajouter des règles Git dans votre CLAUDE.md :

# Conventions Git
- Format de commit : type(scope): description
- Types autorisés : feat, fix, docs, refactor, test
- Toujours créer un nouveau commit (jamais --amend sauf demande explicite)
- Ne jamais push sans demander confirmation

En pratique, les équipes qui configurent ces règles réduisent de 60 % le nombre de commits mal formatés. SFEIR Institute recommande d'inclure aussi les patterns de branches (feature/, fix/, docs/). Consultez les erreurs courantes liées au système de mémoire CLAUDE.md pour éviter les pièges de configuration.

Pour maîtriser l'ensemble de ces configurations, la formation Claude Code proposée par SFEIR couvre en 1 journée la mise en place complète de l'intégration Git, la personnalisation de CLAUDE.md et les workflows de commit assistés par IA. Vous y pratiquerez sur des labs concrets avec des dépôts réels.

À retenir : Ajoutez vos conventions Git dans CLAUDE.md dès le premier jour pour des commits propres et cohérents.

Comment diagnostiquer les erreurs MCP liées à Git ?

Le Model Context Protocol (MCP) est le protocole d'extension de Claude Code qui permet de connecter des outils externes comme des serveurs Git. Certains utilisateurs configurent un serveur MCP Git pour donner à Claude Code un accès étendu aux opérations de versioning. Quand ce serveur MCP tombe, les commandes Git via Claude Code échouent silencieusement.

Vérifiez l'état de vos serveurs MCP :

claude mcp list

Si le serveur Git n'apparaît pas ou affiche disconnected, redémarrez-le avec claude mcp restart. Les logs MCP se trouvent dans ~/.claude/logs/mcp/. En 2026, la version stable du protocole MCP est la 1.2.

Pour le détail des erreurs MCP, le guide de dépannage MCP couvre les cas spécifiques aux serveurs de contexte. Vous pouvez aussi consulter les erreurs courantes des premières conversations si le problème survient dès le lancement.

À retenir : Vérifiez toujours l'état MCP avec claude mcp list avant de chercher un problème Git.

Quand faut-il contacter le support Anthropic ?

Contactez le support après avoir épuisé les diagnostics locaux. Concrètement, voici les 4 situations qui justifient une escalade :

Corruption persistante du dépôt après git fsck --full et git gc
Erreur interne de Claude Code (message Internal error répété 3 fois)
Perte de données : commits disparus du reflog (au-delà de 90 jours)
Bug reproductible : un comportement identique sur 2 machines différentes

Avant de contacter le support, préparez ces informations :

Version de Claude Code (claude --version) - actuellement v1.0.23
Version de Git (git --version) - minimum requis : 2.39
Système d'exploitation et version de Node.js (22 LTS recommandé)
Les 20 dernières lignes de ~/.claude/logs/latest.log

Le support Anthropic est accessible via le portail développeur. Le délai moyen de réponse est de 24 heures en 2026. Pour les problèmes non bloquants, la communauté GitHub anthropics/claude-code propose des solutions en 4 heures en moyenne.

Si vous souhaitez aller plus loin dans la maîtrise de ces outils, la formation Développeur Augmenté par l'IA de SFEIR Institute propose 2 jours de pratique intensive couvrant Git, les workflows CI/CD assistés par IA et le debugging avancé. La formation Développeur Augmenté par l'IA – Avancé approfondit en 1 journée les cas complexes : monorepos, rebase interactif piloté par IA et gestion de conflits multi-branches.

À retenir : Escaladez vers le support uniquement après avoir vérifié la configuration locale, testé sur un dépôt propre et consulté les logs.