Que fait GitHub CLI (gh) ?
Interagissez avec GitHub depuis la ligne de commande : dépôts, versions, issues, PRs, discussions, recherche, revue de code et Actions.
Vérifié avec gh 2.95.0.
Directives pour l'agent
- Pour les fichiers ou répertoires distants connus, utilisez
gh repo read-file/gh repo read-dir(aperçu dansgh2.95). Pour les versions antérieures deghou des besoins uniquement via API, utilisez l'API de contenu en repli dans API Patterns. - Lorsqu'une tâche nécessite de chercher dans plusieurs fichiers ou d'explorer du code inconnu dont les chemins ne sont pas connus à l'avance, clonez dans un répertoire temporaire (
gh repo clone owner/repo <temp-dir> -- --depth 1) et utilisez les outils locaux de lecture et de recherche de fichiers. - Préférez la sortie texte par défaut à
--jsonpour la lecture/visualisation — elle est plus économe en jetons. Utilisez--jsonavec--jquniquement lorsque vous extrayez des champs spécifiques de manière programmatique. Pour découvrir les champs pris en charge, exécutez la commande avec--jsonsans liste de champs, puis demandez uniquement les champs dont vous avez besoin. - Lorsque vous consultez des logs ou des diffs, limitez d'abord la sortie (par ex.,
--name-only,--log-failed) avant de récupérer le contenu complet. - Le flag
--repoest inutile lorsque vous travaillez dans un dépôt cloné — le dépôt du répertoire courant est utilisé par défaut. Pourgh api, utilisez le chemin explicite (repos/OWNER/REPO/...) ou définissez la variable d'environnementGH_REPO. - Utilisez cette compétence pour les workflows couverts. Si un flag ou un champ nécessaire est manquant ici, si une commande échoue avec un flag inconnu/modifié, ou si la commande est marquée comme aperçu, consultez l'aide spécifique de cette commande (par ex.,
gh pr diff --help).
Sécurité
- Opérations d'écriture (
create,edit,comment,review,close,merge,delete,rerun,run cancel,workflow run/enable/disable, mutations de discussion) modifient l'état GitHub. Confirmez avec l'utilisateur avant d'exécuter, en particulier sur les dépôts que vous ne possédez pas. gh apiavec--method POST/PUT/PATCH/DELETEenvoie des requêtes d'écriture. Vérifiez doublement le point de terminaison et la charge utile. La méthode par défaut est GET (sûre) ; l'ajout des paramètres-f/-Fchange la méthode par défaut en POST.- Les opérations destructrices (
delete,close,merge --admin) peuvent être irréversibles. Exigent une confirmation explicite de l'utilisateur.
Prérequis
Vérifiez que gh est installé et authentifié avant d'exécuter des commandes :
gh --version
gh auth status
Sinon, guidez l'utilisateur via gh auth login.
Flags communs
Ces flags sont disponibles sur de nombreux groupes de commandes, mais leur prise en charge varie selon la commande :
--repo OWNER/REPO-- Cible un dépôt différent (par défaut : le dépôt du répertoire courant). Accepte également les URL complètes.--json FIELDS-- Sortie au format JSON avec les champs spécifiés. Passez sans valeur pour lister les champs disponibles.--jq EXPRESSION-- Filtre la sortie JSON en utilisant la syntaxe jq. Nécessite--json.--template STRING-- Formate la sortie JSON avec un template Go (alternative à--jq).--web-- Ouvre la ressource dans le navigateur au lieu de l'afficher dans le terminal.--limit N-- Nombre maximum de résultats pour les commandes de liste (par défaut généralement 30).
Dépôts
Voir
Affiche la description, le README, les étoiles, la répartition des langages et d'autres métadonnées d'un dépôt.
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
Cloner
Clone un dépôt localement. Configure automatiquement le remote et, pour les forks, configure le remote amont.
gh repo clone owner/repo [répertoire-cible]
Lire le contenu d'un dépôt distant
Pour des lectures rapides de fichiers ou répertoires connus, utilisez les commandes de lecture de dépôt (aperçu dans gh 2.95) :
# Fichier connu
gh repo read-file src/main.py --repo owner/repo --ref main
# Répertoire connu
gh repo read-dir src --repo owner/repo --ref main
# Repli pour les versions antérieures de gh
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
Pour les formes de sortie, les limites de taille de fichier et les mises en garde sur le listage des répertoires, voir API Patterns. Pour l'exploration multi-fichiers, clonez plutôt (voir Directives pour l'agent).
Lister les dépôts
Liste les dépôts appartenant à un utilisateur ou une organisation, avec des filtres optionnels par langue et visibilité.
gh repo list owner --limit 30
Versions
Lister
Liste les versions dans un dépôt, triées par date de création (les plus récentes en premier). Par défaut, affiche toutes les versions, y compris les pré-versions et les brouillons.
gh release list --repo owner/repo --limit 10
Flags :
--exclude-pre-releases-- Exclure les pré-versions--exclude-drafts-- Exclure les brouillons
Champs JSON clés : tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable
Voir (journal des modifications, actifs)
Affiche le corps du journal des modifications, le tag, les actifs et les métadonnées d'une version. Omettre le tag pour voir la dernière version.
gh release view --repo owner/repo # Dernière version
gh release view v1.2.0 --repo owner/repo # Tag spécifique
gh release view v1.2.0 --json tagName,body,assets,publishedAt
Champs JSON clés : tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url
Issues
Lister
Liste les issues dans un dépôt, filtrées par état, label, assigné ou requête de recherche. Par défaut, affiche uniquement les issues ouvertes.
gh issue list --repo owner/repo
gh issue list --repo owner/repo --state all --label bug --assignee @me
gh issue list --repo owner/repo --search "error no:assignee sort:created-asc"
Flags :
--state VALUE--open(par défaut),closed,all--label NAME-- Filtrer par label (répéter pour plusieurs)--assignee LOGIN-- Filtrer par assigné (@mepour soi-même)--search QUERY-- Syntaxe de recherche GitHub
Champs JSON clés : number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url
Voir
Affiche le titre, le corps, les labels, les assignés et le statut d'une issue. Utilisez --comments pour inclure le fil de commentaires complet.
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
Créer
Crée une nouvelle issue avec un titre, un corps, des labels et des assignés.
gh issue create --title "Bug: description" --body "Détails..." --label bug --assignee user1
Modifier
Met à jour le titre, le corps, les labels, les assignés ou le jalon d'une issue. Tous les flags peuvent être combinés en un seul appel.
Flags :
--title TEXTE/--body TEXTE-- Mettre à jour le titre ou le corps--add-label NOM/--remove-label NOM-- Modifier les labels--add-assignee LOGIN/--remove-assignee LOGIN-- Modifier les assignés--milestone NOM/--remove-milestone-- Définir ou supprimer le jalon
Commenter
Ajoute un commentaire à une issue existante.
gh issue comment 123 --body "Texte du commentaire"
Fermer / Rouvrir
Ferme ou rouvre une issue. Optionnellement, spécifiez une raison de fermeture et laissez un commentaire.
gh issue close 123 --comment "Corrigé dans la PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
Raisons de fermeture : completed (par défaut), not planned, duplicate.
Statut
Affiche un résumé des issues qui vous concernent : assignées à vous, vous mentionnant, et ouvertes par vous.
gh issue status
Pour les types d'issues, sous-issues, relations parent, dépendances bloquantes et leurs champs JSON (nécessite des hôtes GitHub compatibles), voir Issues reference.
Pull Requests
Utilisez ces commandes pour visualiser et inspecter les PRs. Pour la création, la fusion, la revue et la gestion des PRs, voir Pull Requests reference.
Lister
Liste les pull requests dans un dépôt, filtrées par état, auteur, label ou requête de recherche. Par défaut, affiche uniquement les PRs ouvertes.
gh pr list --repo owner/repo
gh pr list --repo owner/repo --state all --author @me --label "needs-review"
gh pr list --repo owner/repo --search "status:success review:required"
gh pr list --repo owner/repo --app dependabot
Flags :
--state VALUE--open(par défaut),closed,merged,all--draft-- Filtrer par état brouillon--author LOGIN/--assignee LOGIN-- Filtrer par auteur ou assigné--label NAME-- Filtrer par label--search QUERY-- Syntaxe de recherche GitHub--app NAME-- Filtrer par auteur GitHub App (par ex.,dependabot)
Champs JSON clés : number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url
Voir
Affiche le titre, le corps, le statut de la revue, les vérifications et d'autres métadonnées d'une PR. Sans argument, affiche la PR pour la branche courante. Utilisez --comments pour inclure le fil de commentaires.
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
Statut
Affiche un résumé des PRs qui vous concernent : la PR de la branche courante, les PRs que vous avez créées et les PRs où votre revue est demandée.
gh pr status
Discussions
Utilisez gh discussion pour les Discussions de dépôt (aperçu dans gh 2.94). Commencez par les commandes de lecture et vérifiez les flags avec --help car l'ensemble de commandes est en aperçu :
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
Pour la création, l'édition, les commentaires, les fils de réponse, les formes de sortie JSON et les modèles de repli GraphQL, voir Discussions reference.
Recherche
Recherche sur GitHub pour les issues, les PRs, le code, les commits et les dépôts. Utilisez gh issue list / gh pr list pour un seul dépôt ; utilisez gh search ... pour les requêtes multi-dépôts ou à l’échelle d’un propriétaire.
Pour la syntaxe complète des requêtes de recherche, voir la documentation de recherche GitHub. Pour les flags spécifiques à chaque sous-commande, exécutez gh search <sub-commande> --help.
Limites de débit : Les API de recherche ont des limites de débit plus strictes que l'API de base. La recherche de code est la plus restrictive (~10/min authentifié ; nécessite une authentification). Les autres commandes de recherche permettent ~30/min authentifié ou ~10/min non authentifié. Vérifiez le quota actuel avec gh api rate_limit --jq '.resources | {search, code_search}'.
Quand cloner plutôt : Voir Directives pour l'agent pour savoir quand cloner plutôt que d'utiliser l'API.
Robots et apps : Pour les auteurs GitHub App comme Dependabot, utilisez --app dependabot ; --author dependabot filtre les comptes utilisateur, pas les auteurs d'applications.
Reconnaissance : Lorsque vous explorez un dépôt inconnu, vérifiez d'abord son langage principal pour sélectionner les valeurs --extension et --language correctes :
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
Issues
Recherchez des issues dans plusieurs dépôts en utilisant des mots-clés, des labels, un état ou une syntaxe de recherche GitHub.
gh search issues "gestion d'erreurs" --repo owner/repo
gh search issues --label bug --state open --assignee @me
gh search issues --app dependabot --repo owner/repo
gh search issues --involves username --comments ">10" --repo owner/repo
Flags clés : --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.
PRs
Recherchez des pull requests dans plusieurs dépôts. Prend en charge le filtrage par auteur, statut de revue, état de fusion et statut brouillon.
gh search prs "refactor" --repo owner/repo
gh search prs --review-requested @me --state open
gh search prs --app dependabot --repo owner/repo
gh search prs --author username --merged --repo owner/repo
Flags clés : --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.
Code
Recherche dans le contenu des fichiers sur tous les dépôts GitHub. Renvoie uniquement les lignes correspondantes (pas de numéros de ligne, pas de contexte environnant). Utile pour localiser les fichiers contenant un motif, mais suivez avec une lecture de fichier ou clonez le dépôt pour comprendre la logique du code.
Limitations : Utilise un moteur de recherche hérité (les résultats peuvent ne pas correspondre à github.com). Ne recherche que la branche par défaut. Seuls les fichiers de moins de 384 Ko sont indexés. Chaque requête doit inclure au moins un terme de recherche (les recherches par qualificateur seul comme --extension ts échoueront). Ne prend pas en charge --sort ou --order — les résultats sont toujours classés par pertinence.
gh search code "nomDeFonction" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json
Flags clés : --repo, --owner, --extension, --filename, --language, --match, --size.
Champs JSON clés : path, repository, sha, textMatches, url.
Le champ textMatches fournit un contexte de fragment avec des positions de correspondance au niveau des caractères — utilisez --json path,textMatches lorsque vous avez besoin de plus de contexte que la sortie texte par défaut.
Commits
Recherchez des commits par texte de message, auteur, date de commit ou hash.
gh search commits "correction bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
Flags clés : --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.
Dépôts
Recherchez des dépôts par mot-clé, langage, sujet, étoiles, licence ou propriétaire. Note : --repo n'est pas disponible sur cette sous-commande — utilisez --owner pour filtrer par propriétaire.
gh search repos "mot-clé" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
Flags clés : --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.
Exclure des qualificateurs (préfixe trait d'union)
Les requêtes de recherche avec des exclusions comme -label:bug nécessitent une syntaxe spéciale pour éviter l'interprétation des flags du shell. Tous les flags (par ex., --limit) doivent apparaître avant -- ; tout ce qui suit -- est interprété comme le texte de la requête de recherche :
# Shells de type Unix
gh search issues -- "ma requête -label:bug"
# PowerShell
gh --% search issues -- "ma requête -label:bug"
…
[tronqué pour la traduction]