Skip to content

TROUBLESHOOTING.md

Latest commit

 

History

History
189 lines (135 loc) · 12.9 KB

TROUBLESHOOTING.md

File metadata and controls

189 lines (135 loc) · 12.9 KB

Dépannage de gac

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | हिन्दी | Tiếng Việt | Français | Рус../ | Español | Português | Norsk | Svenska | Deutsch | Nederlands | Italiano

Ce guide couvre les problèmes courants et solutions pour installer, configurer et exécuter gac.

Table des matières

1. Problèmes de configuration

Problème : Commande uvx non trouvée

  • Installez uv en suivant les instructions sur astral.sh/uv
  • Assurez-vous que uv est installé et dans votre $PATH
  • Redémarrez votre terminal après l'installation

2. Problèmes de configuration

Problème : gac ne trouve pas votre clé API ou modèle

  • Si vous êtes nouveau, exécutez uvx gac init pour configurer de manière interactive votre fournisseur, modèle et clés API
  • Assurez-vous que vos .gac.env ou variables d'environnement sont correctement configurés
  • Exécutez uvx gac --log-level=debug pour voir quels fichiers de configuration sont chargés et déboguer les problèmes de configuration
  • Vérifiez les fautes de frappe dans les noms de variables (ex: GAC_GROQ_API_KEY)

Problème : Les changements $HOME/.gac.env au niveau utilisateur ne sont pas pris en compte

  • Assurez-vous d'éditer le bon fichier pour votre OS :
    • Sur macOS/Linux : $HOME/.gac.env (habituellement /Users/<votre-nom-utilisateur>/.gac.env ou /home/<votre-nom-utilisateur>/.gac.env)
    • Sur Windows : $HOME/.gac.env (généralement C:\Users\<votre-nom-utilisateur>\.gac.env ou utilisez %USERPROFILE%)
  • Exécutez uvx gac --log-level=debug pour confirmer que la configuration au niveau utilisateur est chargée
  • Redémarrez votre terminal ou ré-exécutez votre shell pour recharger les variables d'environnement
  • Si cela ne fonctionne toujours pas, vérifiez les fautes de frappe et les permissions de fichier

Problème : Les changements .gac.env au niveau projet ne sont pas pris en compte

  • Assurez-vous que votre projet contient un fichier .gac.env dans le répertoire racine (à côté de votre dossier .git)
  • Exécutez uvx gac --log-level=debug pour confirmer que la configuration au niveau projet est chargée
  • Si vous éditez .gac.env, redémarrez votre terminal ou ré-exécutez votre shell pour recharger les variables d'environnement
  • Si cela ne fonctionne toujours pas, vérifiez les fautes de frappe et les permissions de fichier

Problème : Impossible de définir ou changer la langue des messages de commit

  • Exécutez uvx gac language (ou uvx gac lang) pour sélectionner de manière interactive parmi 25+ langues supportées
  • Utilisez le drapeau -l <langue> pour remplacer la langue pour un seul commit (ex: uvx gac -l zh-CN, uvx gac -l French)
  • Vérifiez votre configuration avec uvx gac config show pour voir le paramètre de langue actuel
  • Le paramètre de langue est stocké dans GAC_LANGUAGE dans votre fichier .gac.env

3. Erreurs de fournisseur/API

Problème : Erreurs d'authentification ou API

  • Assurez-vous d'avoir configuré les clés API correctes pour votre modèle choisi (ex: ANTHROPIC_API_KEY, GROQ_API_KEY)
  • Vérifiez deux fois votre clé API et le statut du compte de votre fournisseur
  • Pour Ollama et LM Studio, confirmez que l'URL API correspond à votre instance locale. Les clés API ne sont nécessaires que si vous avez activé l'authentification.
  • Pour l'expiration du jeton Claude Code : Exécutez uvx gac auth pour vous réauthentifier rapidement et actualiser votre jeton. Votre navigateur s'ouvrira automatiquement pour OAuth.
  • Pour l'expiration du jeton ChatGPT OAuth : Exécutez uvx gac auth chatgpt login pour vous réauthentifier. Votre navigateur s'ouvrira automatiquement pour OAuth.
  • Pour les autres problèmes OAuth de Claude Code, consultez le guide de configuration Claude Code pour un dépannage complet.
  • Pour les autres problèmes OAuth de ChatGPT, consultez le guide de configuration ChatGPT OAuth pour un dépannage complet.
  • Pour l'expiration des jetons de session GitHub Copilot : Exécutez uvx gac auth copilot login pour vous réauthentifier via Device Flow. Les jetons de session sont automatiquement renouvelés à partir du jeton OAuth mis en cache.
  • Pour d'autres problèmes GitHub Copilot, consultez le guide de configuration GitHub Copilot pour un dépannage complet.

Problème : Modèle non disponible ou non supporté

  • Streamlake utilise des IDs de point de terminaison d'inférence au lieu de noms de modèle. Assurez-vous de fournir l'ID de point de terminaison de leur console.
  • Vérifiez que le nom du modèle est correct et supporté par votre fournisseur
  • Vérifiez la documentation du fournisseur pour les modèles disponibles

4. Problèmes de regroupement de commits

Problème : Le drapeau --group ne fonctionne pas comme attendu

  • Le drapeau --group analyse automatiquement les changements indexés et peut créer plusieurs commits logiques
  • L'IA peut décider qu'un seul commit a du sens pour votre ensemble de changements indexés, même avec --group
  • Ceci est un comportement intentionnel - l'IA groupe les changements basés sur les relations logiques, pas seulement la quantité
  • Assurez-vous d'avoir plusieurs changements non liés indexés (ex: correction de bug + ajout de fonctionnalité) pour de meilleurs résultats
  • Utilisez uvx gac --show-prompt pour déboguer ce que voit l'IA

Problème : Commits regroupés incorrectement ou non regroupés quand attendu

  • Le regroupement est déterminé par l'analyse de vos changements par l'IA
  • L'IA peut créer un seul commit si elle détermine que les changements sont logiquement liés
  • Essayez d'ajouter des indices avec -h "indice" pour guider la logique de regroupement (ex: -h "séparer la correction de bug de la refactorisation")
  • Revoyez les groupes générés avant de confirmer
  • Si le regroupement ne fonctionne pas bien pour votre cas d'usage, commitez les changements séparément à la place

5. Sécurité et détection de secrets

Important : L'analyse de secrets s'exécute avant tout appel à une API d'IA. Si un secret est détecté, le workflow est immédiatement abandonné et aucun appel API n'est effectué. L'analyseur utilise la correspondance de motifs basée sur des regex (pas des LLM), l'analyse est donc rapide et s'exécute entièrement en local — votre code n'est jamais envoyé à un modèle d'IA pour la détection de secrets.

Problème : Faux positif : l'analyse de secrets détecte des non-secrets

  • L'analyseur de sécurité recherche des motifs regex qui ressemblent à des clés API, jetons et mots de passe
  • Si vous commitez du code d'exemple, des fixtures de test, ou de la documentation avec des clés de remplacement, vous pouvez voir des faux positifs
  • Utilisez --skip-secret-scan pour contourner l'analyse si vous êtes certain que les changements sont sûrs
  • Envisagez d'exclure les fichiers d'exemple/test des commits, ou utilisez des remplacements clairement marqués

Problème : L'analyse de secrets ne détecte pas de vrais secrets

  • L'analyseur utilise la correspondance de motifs basée sur des regex (pas des LLM) et peut ne pas attraper tous les types de secrets
  • Revoyez toujours vos changements indexés avec git diff --staged avant de commiter
  • Envisagez d'utiliser des outils de sécurité supplémentaires comme git-secrets ou gitleaks pour une protection complète
  • Signalez tous les motifs manqués comme des problèmes pour aider à améliorer la détection

Problème : Besoin de désactiver l'analyse de secrets de manière permanente

  • Définissez GAC_SKIP_SECRET_SCAN=true dans votre fichier .gac.env
  • Utilisez uvx gac config set GAC_SKIP_SECRET_SCAN true
  • Note : Ne désactivez que si vous avez d'autres mesures de sécurité en place

6. Problèmes de hooks Pre-commit et Lefthook

Problème : Les hooks pre-commit ou lefthook échouent et bloquent les commits

  • Utilisez uvx gac --no-verify pour sauter temporairement tous les hooks pre-commit et lefthook
  • Corrigez les problèmes sous-jacents causant l'échec des hooks
  • Envisagez d'ajuster votre configuration pre-commit ou lefthook si les hooks sont trop stricts

Problème : Les hooks pre-commit ou lefthook prennent trop de temps ou interfèrent avec le workflow

  • Utilisez uvx gac --no-verify pour sauter temporairement tous les hooks pre-commit et lefthook
  • Envisagez de configurer les hooks pre-commit dans .pre-commit-config.yaml ou les hooks lefthook dans .lefthook.yml pour être moins agressifs pour votre workflow
  • Revoyez votre configuration de hook pour optimiser les performances

7. Problèmes de workflow courants

Problème : Aucun changement à commiter / rien d'indexé

  • gac nécessite des changements indexés pour générer un message de commit
  • Utilisez git add <fichiers> pour indexer les changements, ou utilisez uvx gac -a pour indexer automatiquement tous les changements
  • Vérifiez git status pour voir quels fichiers ont été modifiés
  • Utilisez uvx gac diff pour voir une vue filtrée de vos changements

Problème : Le message de commit n'est pas ce que j'attendais

  • Utilisez le système de feedback interactif : tapez r pour relancer, e pour éditer (TUI intégrée, ou éditeur externe via GAC_EDITOR), ou fournissez un feedback en langage naturel
  • Ajoutez du contexte avec -h "votre indice" pour guider l'IA
  • Utilisez -o pour des messages plus simples sur une ligne ou -v pour des messages plus détaillés
  • Utilisez --show-prompt pour voir quelles informations l'IA reçoit

Problème : gac est trop lent

  • Utilisez uvx gac -y pour sauter l'invite de confirmation
  • Utilisez uvx gac -q pour le mode silencieux avec moins de sortie
  • Envisagez d'utiliser des modèles plus rapides/bon marché pour les commits de routine
  • Utilisez uvx gac --no-verify pour sauter les hooks s'ils vous ralentissent

Problème : Impossible d'éditer ou de fournir un feedback après la génération du message

  • À l'invite, tapez e pour entrer en mode édition (TUI intégrée avec bindings vi/emacs ; définissez GAC_EDITOR pour utiliser votre éditeur préféré à la place)
  • Tapez r pour régénérer sans feedback
  • Ou tapez simplement votre feedback directement (ex: "rends-le plus court", "concentre-toi sur la correction du bug")
  • Appuyez sur Entrée sur une entrée vide pour voir l'invite à nouveau

8. Débogage général

  • Utilisez uvx gac init pour réinitialiser ou mettre à jour votre configuration de manière interactive
  • Utilisez uvx gac --log-level=debug pour une sortie de débogage détaillée et le logging
  • Utilisez uvx gac --show-prompt pour voir quel prompt est envoyé à l'IA
  • Utilisez uvx gac --help pour voir tous les drapeaux de ligne de commande disponibles
  • Utilisez uvx gac config show pour voir toutes les valeurs de configuration actuelles
  • Vérifiez les logs pour les messages d'erreur et les traces de pile
  • Vérifiez le README.md principal pour les fonctionnalités, exemples et instructions de démarrage rapide

Toujours bloqué ?

  • Cherchez les problèmes existants ou ouvrez-en un nouveau sur le dépôt GitHub
  • Incluez des détails sur votre OS, version Python, version gac, fournisseur, et sortie d'erreur
  • Plus vous fournissez de détails, plus votre problème peut être résolu rapidement

Où obtenir une aide supplémentaire