Was macht GitHub CLI (gh)?
Interagieren Sie mit GitHub über die Kommandozeile: Repositories, Releases, Issues, PRs, Diskussionen, Suche, Code-Review und Actions.
Getestet mit gh 2.95.0.
Agenten-Richtlinien
- Für bekannte entfernte Dateien oder Verzeichnisse verwenden Sie
gh repo read-file/gh repo read-dir(Vorschau ingh2.95). Für älteregh-Versionen oder reine API-Anforderungen verwenden Sie den Contents-API-Fallback in API-Muster. - Wenn eine Aufgabe das Durchsuchen von Dateien oder das Erkunden unbekannten Codes erfordert, bei dem Pfade nicht im Voraus bekannt sind, klonen Sie in ein temporäres Verzeichnis (
gh repo clone owner/repo <temp-dir> -- --depth 1) und verwenden Sie lokale Datei-Lese- und Suchwerkzeuge. - Bevorzugen Sie die Standard-Textausgabe gegenüber
--jsonzum Lesen/Anzeigen – sie ist token-effizienter. Verwenden Sie--jsonmit--jqnur, wenn Sie programmatisch bestimmte Felder extrahieren. Um unterstützte Felder zu entdecken, führen Sie den Befehl mit--jsonohne Feldliste aus und fordern Sie dann nur die benötigten Felder an. - Wenn Sie Logs oder Diffs anzeigen, grenzen Sie die Ausgabe zuerst ein (z.B.
--name-only,--log-failed), bevor Sie den vollständigen Inhalt abrufen. - Das Flag
--repoist nicht erforderlich, wenn Sie innerhalb eines geklonten Repositorys arbeiten – das Repository des aktuellen Verzeichnisses wird standardmäßig verwendet. Verwenden Sie fürgh apiden expliziten Pfad (repos/OWNER/REPO/...) oder setzen Sie die UmgebungsvariableGH_REPO. - Verwenden Sie diese Fähigkeit für abgedeckte Workflows. Wenn ein benötigtes Flag oder Feld hier fehlt, ein Befehl mit einem unbekannten/geänderten Flag fehlschlägt oder der Befehl als Vorschau markiert ist, überprüfen Sie die Hilfe des jeweiligen Befehls (z.B.
gh pr diff --help).
Sicherheit
- Schreiboperationen (
create,edit,comment,review,close,merge,delete,rerun,run cancel,workflow run/enable/disable, Diskussions-Mutationen) ändern den GitHub-Status. Bestätigen Sie mit dem Benutzer, bevor Sie sie ausführen, insbesondere bei Repositories, die Ihnen nicht gehören. gh apimit--method POST/PUT/PATCH/DELETEsendet Schreibanfragen. Überprüfen Sie den Endpunkt und die Nutzlast. Die Standardmethode ist GET (sicher); das Hinzufügen von-f/-F-Parametern ändert den Standard auf POST.- Destruktive Operationen (
delete,close,merge --admin) können irreversibel sein. Erfordern explizite Benutzerbestätigung.
Voraussetzungen
Stellen Sie sicher, dass gh installiert und authentifiziert ist, bevor Sie Befehle ausführen:
gh --version
gh auth status
Wenn nicht authentifiziert, führen Sie den Benutzer durch gh auth login.
Allgemeine Flags
Diese Flags sind in vielen Befehlgruppen verfügbar, aber die Unterstützung variiert je nach Befehl:
--repo OWNER/REPO– Ein anderes Repository anvisieren (Standard: Repository des aktuellen Verzeichnisses). Akzeptiert auch vollständige URLs.--json FIELDS– Ausgabe als JSON mit angegebenen Feldern. Ohne Wert übergeben, um verfügbare Felder aufzulisten.--jq EXPRESSION– JSON-Ausgabe mit jq-Syntax filtern. Erfordert--json.--template STRING– JSON-Ausgabe mit einer Go-Vorlage formatieren (Alternative zu--jq).--web– Die Ressource im Browser öffnen, anstatt sie im Terminal anzuzeigen.--limit N– Maximale Anzahl von Ergebnissen für List-Befehle (Standard ist normalerweise 30).
Repositories
Anzeigen
Zeigt die Beschreibung, README, Sterne, Sprachaufteilung und andere Metadaten eines Repositorys an.
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
Klonen
Klonen Sie ein Repository lokal. Konfiguriert automatisch den Remote und, bei Forks, den Upstream-Remote.
gh repo clone owner/repo [target-directory]
Remote-Repository-Inhalte lesen
Für schnelles Lesen bekannter Dateien oder Verzeichnisse verwenden Sie die Repository-Read-Befehle (Vorschau in gh 2.95):
# Bekannte Datei
gh repo read-file src/main.py --repo owner/repo --ref main
# Bekanntes Verzeichnis
gh repo read-dir src --repo owner/repo --ref main
# Fallback für ältere gh-Versionen
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
Für Ausgabeformen, Dateigrößenbeschränkungen und Einschränkungen bei der Verzeichnisauflistung siehe API-Muster. Für die Erkundung mehrerer Dateien stattdessen klonen (siehe Agenten-Richtlinien).
Repositories auflisten
Listet Repositories eines Benutzers oder einer Organisation auf, mit optionalen Sprach- und Sichtbarkeitsfiltern.
gh repo list owner --limit 30
Releases
Auflisten
Listet Releases in einem Repository auf, geordnet nach Erstellungsdatum (neueste zuerst). Standardmäßig werden alle Releases einschließlich Pre-Releases und Entwürfe angezeigt.
gh release list --repo owner/repo --limit 10
Flags:
--exclude-pre-releases– Pre-Releases ausschließen--exclude-drafts– Entwürfe ausschließen
Wichtige JSON-Felder: tagName, name, publishedAt, isLatest, isDraft, isPrerelease, isImmutable
Anzeigen (Änderungsprotokoll, Assets)
Zeigt den Änderungsprotokolltext, Tag, Assets und Metadaten eines Releases an. Lassen Sie das Tag weg, um das neueste Release anzuzeigen.
gh release view --repo owner/repo # Neuestes Release
gh release view v1.2.0 --repo owner/repo # Bestimmtes Tag
gh release view v1.2.0 --json tagName,body,assets,publishedAt
Wichtige JSON-Felder: tagName, name, body, assets, author, publishedAt, isDraft, isPrerelease, isImmutable, url
Issues
Auflisten
Listet Issues in einem Repository auf, gefiltert nach Status, Label, Bearbeiter oder Suchabfrage. Standardmäßig werden nur offene Issues angezeigt.
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(Standard),closed,all--label NAME– Nach Label filtern (für mehrere wiederholen)--assignee LOGIN– Nach Bearbeiter filtern (@mefür sich selbst)--search QUERY– GitHub-Suchsyntax
Wichtige JSON-Felder: number, title, state, stateReason, author, labels, assignees, createdAt, updatedAt, url
Anzeigen
Zeigt Titel, Text, Labels, Bearbeiter und Status eines Issues an. Verwenden Sie --comments, um den vollständigen Kommentarthread einzuschließen.
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
Erstellen
Erstellt ein neues Issue mit Titel, Text, Labels und Bearbeitern.
gh issue create --title "Bug: Beschreibung" --body "Details..." --label bug --assignee user1
Bearbeiten
Aktualisiert Titel, Text, Labels, Bearbeiter oder Meilenstein eines Issues. Alle Flags können in einem einzigen Aufruf kombiniert werden.
Flags:
--title TEXT/--body TEXT– Titel oder Text aktualisieren--add-label NAME/--remove-label NAME– Labels ändern--add-assignee LOGIN/--remove-assignee LOGIN– Bearbeiter ändern--milestone NAME/--remove-milestone– Meilenstein setzen oder entfernen
Kommentieren
Fügt einem vorhandenen Issue einen Kommentar hinzu.
gh issue comment 123 --body "Kommentartext"
Schließen / Wiedereröffnen
Schließt ein Issue oder öffnet es wieder. Optional können ein Schließgrund angegeben und ein Kommentar hinterlassen werden.
gh issue close 123 --comment "Behoben in PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
Schließgründe: completed (Standard), not planned, duplicate.
Status
Zeigt eine Zusammenfassung von Issues, die für Sie relevant sind: Ihnen zugewiesene, die Sie erwähnen und die von Ihnen eröffnete.
gh issue status
Für Issue-Typen, Unter-Issues, Elternbeziehungen, blockierende Abhängigkeiten und deren JSON-Felder (erfordert unterstützte GitHub-Hosts) siehe Issues-Referenz.
Pull Requests
Verwenden Sie diese Befehle, um PRs anzuzeigen und zu überprüfen. Zum Erstellen, Zusammenführen, Überprüfen und Verwalten von PRs siehe Pull Requests-Referenz.
Auflisten
Listet Pull-Requests in einem Repository auf, gefiltert nach Status, Autor, Label oder Suchabfrage. Standardmäßig werden nur offene PRs angezeigt.
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(Standard),closed,merged,all--draft– Nach Entwurfsstatus filtern--author LOGIN/--assignee LOGIN– Nach Autor oder Bearbeiter filtern--label NAME– Nach Label filtern--search QUERY– GitHub-Suchsyntax--app NAME– Nach GitHub-App-Autor filtern (z.B.dependabot)
Wichtige JSON-Felder: number, title, state, author, headRefName, baseRefName, labels, reviewDecision, isDraft, statusCheckRollup, files, commits, reviews, url
Anzeigen
Zeigt Titel, Text, Überprüfungsstatus, Checks und andere Metadaten eines PRs an. Ohne Argument zeigt es den PR für den aktuellen Branch an. Verwenden Sie --comments, um den Kommentarthread einzuschließen.
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
Status
Zeigt eine Zusammenfassung von PRs, die für Sie relevant sind: den PR des aktuellen Branches, von Ihnen erstellte PRs und PRs, bei denen Ihre Überprüfung angefordert wurde.
gh pr status
Diskussionen
Verwenden Sie gh discussion für Repository-Diskussionen (Vorschau in gh 2.94). Beginnen Sie mit Lese-Befehlen und überprüfen Sie Flags mit --help, da die Befehlssammlung eine Vorschau ist:
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
Zum Erstellen, Bearbeiten, Kommentieren, Antwort-Threads, JSON-Ausgabeformen und GraphQL-Fallback-Mustern siehe Diskussionen-Referenz.
Suche
Durchsuchen Sie GitHub nach Issues, PRs, Code, Commits und Repositories. Verwenden Sie gh issue list / gh pr list für ein Repository; verwenden Sie gh search ... für repositoriumsübergreifende oder besitzerweite Abfragen.
Die vollständige Suchabfragesyntax finden Sie in der GitHub-Suchdokumentation. Für für jeden Unterbefehl spezifische Flags führen Sie gh search <subcommand> --help aus.
Ratenlimits: Such-APIs haben strengere Ratenlimits als die Kern-API. Die Codesuche ist am restriktivsten (~10/Min. authentifiziert; erfordert Authentifizierung). Andere Suchbefehle erlauben ~30/Min. authentifiziert oder ~10/Min. nicht authentifiziert. Überprüfen Sie das aktuelle Kontingent mit gh api rate_limit --jq '.resources | {search, code_search}'.
Wann stattdessen klonen: Siehe Agenten-Richtlinien für die Entscheidung, ob geklont oder die API verwendet werden soll.
Bots und Apps: Für GitHub-App-Autoren wie Dependabot verwenden Sie --app dependabot; --author dependabot filtert Benutzerkonten, nicht App-Autoren.
Erkundung: Wenn Sie ein unbekanntes Repository durchsuchen, prüfen Sie zuerst dessen primäre Sprache, um die richtigen --extension- und --language-Werte auszuwählen:
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
Issues
Durchsuchen Sie Issues in verschiedenen Repositories mit Schlüsselwörtern, Labels, Status oder GitHub-Suchsyntax.
gh search issues "Fehlerbehandlung" --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
Wichtige Flags: --repo, --owner, --state, --label, --assignee, --author, --app, --involves, --comments, --match, --sort, --include-prs.
PRs
Durchsuchen Sie Pull-Requests in verschiedenen Repositories. Unterstützt Filter nach Autor, Überprüfungsstatus, Zusammenführungsstatus und Entwurfsstatus.
gh search prs "Refactoring" --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
Wichtige Flags: --repo, --owner, --state, --merged, --draft, --author, --assignee, --app, --label, --review, --review-requested, --base, --head, --checks, --sort.
Code
Durchsuchen Sie Dateiinhalte in verschiedenen GitHub-Repositories. Gibt nur übereinstimmende Zeilen zurück (keine Zeilennummern, kein umgebender Kontext). Nützlich zum Auffinden von Dateien, die ein Muster enthalten, aber folgen Sie mit Datei-Lesevorgängen oder klonen Sie das Repository, um die Codelogik zu verstehen.
Einschränkungen: Verwendet eine veraltete Suchmaschine (Ergebnisse können von github.com abweichen). Durchsucht nur den Standard-Branch. Nur Dateien unter 384 KB werden indiziert. Jede Abfrage muss mindestens einen Suchbegriff enthalten (nur aus Qualifizierern bestehende Suchen wie --extension ts allein schlagen fehl). Unterstützt kein --sort oder --order – Ergebnisse werden immer nach Relevanz sortiert.
gh search code "functionName" --repo owner/repo
gh search code "createServer" --repo owner/repo --extension ts
gh search code "lint" --repo owner/repo --filename package.json
Wichtige Flags: --repo, --owner, --extension, --filename, --language, --match, --size.
Wichtige JSON-Felder: path, repository, sha, textMatches, url.
Das Feld textMatches bietet Fragmentkontext mit Übereinstimmungspositionen auf Zeichenebene – verwenden Sie --json path,textMatches, wenn Sie mehr Kontext benötigen, als die Standardtextausgabe bietet.
Commits
Durchsuchen Sie Commits nach Nachrichtentext, Autor, Committer-Datum oder Hash.
gh search commits "Fehler behoben" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
Wichtige Flags: --repo, --owner, --author, --committer, --author-date, --committer-date, --author-name, --author-email, --hash, --merge, --sort.
Repositories
Durchsuchen Sie Repositories nach Schlüsselwort, Sprache, Thema, Sternen, Lizenz oder Besitzer. Hinweis: --repo ist bei diesem Unterbefehl nicht verfügbar – verwenden Sie --owner, um nach Besitzer zu filtern.
gh search repos "Schlüsselwort" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
Wichtige Flags: --owner, --language, --topic, --stars, --forks, --license, --created, --updated, --match, --sort, --include-forks, --visibility.
Ausschließen von Qualifizierern (Bindestrich-Präfix)
Suchabfragen mit Ausschlüssen wie -label:bug benötigen eine spezielle Syntax, um die Interpretation als Shell-Flag zu vermeiden. Alle Flags (z.B. --limit) müssen vor -- erscheinen; alles nach -- wird als Suchabfrage-Text interpretiert:
# Unix-ähnliche Shells
gh search issues -- "my query -label:bug"
# PowerShell
gh --% search issues -- "my query -label:bug"
…
[gekürzt zur Übersetzung]