GitHub CLI (gh)
從命令列與 GitHub 互動:儲存庫、版本發行、議題、PR、討論區、搜尋、程式碼審查和 Actions。
經驗證可在 gh 2.95.0 版本上使用。
Agent 指南
- 對於已知的遠端檔案或目錄,請使用
gh repo read-file/gh repo read-dir(gh2.95 中的預覽功能)。對於較舊的gh版本或僅需 API 的情況,請使用 API 模式 中的內容 API 後備方案。 - 當任務需要跨檔案搜尋或探索路徑未知的不熟悉程式碼時,請 clone 到暫存目錄(
gh repo clone owner/repo <temp-dir> -- --depth 1),然後使用本機檔案讀取和搜尋工具。 - 對於讀取/檢視,偏好預設的文字輸出而非
--json——這在 token 使用上更有效率。僅在需要以程式化方式提取特定欄位時,才使用帶有--jq的--json。若要發現支援的欄位,請在不帶欄位列表的情況下執行帶有--json的命令,然後僅請求您需要的欄位。 - 檢視日誌或差異時,請先縮小輸出範圍(例如
--name-only、--log-failed),然後再擷取完整內容。 - 在已 clone 的儲存庫內執行時,不需要
--repo旗標——預設會使用目前目錄的儲存庫。對於gh api,請使用明確路徑(repos/OWNER/REPO/...)或設定GH_REPO環境變數。 - 將此技能用於涵蓋的工作流程。當缺少所需的旗標或欄位,命令因未知/已更改的旗標而失敗,或命令標記為預覽時,請檢查該特定命令的說明(例如
gh pr diff --help)。
安全性
- 寫入操作(
create、edit、comment、review、close、merge、delete、rerun、run cancel、workflow run/enable/disable、討論區變更)會修改 GitHub 狀態。在執行之前,請與使用者確認,特別是在您不擁有的儲存庫上。 gh api搭配--method POST/PUT/PATCH/DELETE會發送寫入請求。請仔細檢查端點和酬載。預設方法為 GET(安全);新增-f/-F參數會將預設方法切換為 POST。- 破壞性操作(
delete、close、merge --admin)可能是不可逆的。需要明確的使用者確認。
先決條件
在執行命令前,請先驗證 gh 已安裝並通過驗證:
gh --version
gh auth status
如果未通過驗證,請引導使用者完成 gh auth login。
常用旗標
這些旗標可用於許多命令組,但對不同命令的支援程度可能不同:
--repo OWNER/REPO-- 指定目標儲存庫(預設:目前目錄的儲存庫)。也接受完整 URL。--json FIELDS-- 以 JSON 格式輸出,並包含指定欄位。傳入時不帶值以列出可用欄位。--jq EXPRESSION-- 使用 jq 語法過濾 JSON 輸出。需要搭配--json。--template STRING-- 使用 Go 模板格式化 JSON 輸出(--jq的替代方案)。--web-- 在瀏覽器中開啟資源,而非在終端機中顯示。--limit N-- 列表命令的結果數量上限(預設通常為 30)。
儲存庫
檢視
顯示儲存庫的描述、README、星數、語言分佈及其他後設資料。
gh repo view owner/repo
gh repo view owner/repo --json name,description,defaultBranchRef,languages,stargazerCount
Clone
本地端 Clone 儲存庫。會自動設定遠端,對於 Fork,則會設定上游遠端。
gh repo clone owner/repo [target-directory]
讀取遠端儲存庫內容
如需快速讀取已知檔案或目錄,請使用儲存庫讀取命令(gh 2.95 中的預覽功能):
# 已知檔案
gh repo read-file src/main.py --repo owner/repo --ref main
# 已知目錄
gh repo read-dir src --repo owner/repo --ref main
# 較舊 gh 版本的後備方案
gh api "repos/OWNER/REPO/contents/src/main.py?ref=main" -H "Accept: application/vnd.github.raw+json"
有關輸出格式、檔案大小限制和目錄列表注意事項,請參閱 API 模式。對於多檔案探索,請改為 clone(請參閱 Agent 指南)。
列出儲存庫
列出由使用者或組織擁有的儲存庫,可選語言和能見度篩選器。
gh repo list owner --limit 30
版本發行
列表
列出儲存庫中的版本發行,依建立日期排序(最新的在前)。預設顯示所有版本發行,包括預發行版和草稿。
gh release list --repo owner/repo --limit 10
旗標:
--exclude-pre-releases-- 排除預發行版--exclude-drafts-- 排除草稿
關鍵 JSON 欄位:tagName、name、publishedAt、isLatest、isDraft、isPrerelease、isImmutable
檢視(變更日誌、資產)
顯示版本發行的變更日誌主體、標籤、資產和後設資料。省略標籤以檢視最新版本發行。
gh release view --repo owner/repo # 最新版本發行
gh release view v1.2.0 --repo owner/repo # 特定標籤
gh release view v1.2.0 --json tagName,body,assets,publishedAt
關鍵 JSON 欄位:tagName、name、body、assets、author、publishedAt、isDraft、isPrerelease、isImmutable、url
議題
列表
列出儲存庫中的議題,可依狀態、標籤、指派對象或搜尋查詢進行篩選。預設僅列出開啟的議題。
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"
旗標:
--state VALUE--open(預設)、closed、all--label NAME-- 依標籤篩選(可重複使用以指定多個)--assignee LOGIN-- 依指派對象篩選(@me代表自己)--search QUERY-- GitHub 搜尋語法
關鍵 JSON 欄位:number、title、state、stateReason、author、labels、assignees、createdAt、updatedAt、url
檢視
顯示議題的標題、主體、標籤、指派對象和狀態。使用 --comments 以包含完整的留言串。
gh issue view 123
gh issue view 123 --comments
gh issue view 123 --json title,body,labels,comments,state
建立
建立新的議題,包含標題、主體、標籤和指派對象。
gh issue create --title "Bug: description" --body "Details..." --label bug --assignee user1
編輯
更新議題的標題、主體、標籤、指派對象或里程碑。所有旗標可以在一次呼叫中組合使用。
旗標:
--title TEXT/--body TEXT-- 更新標題或主體--add-label NAME/--remove-label NAME-- 修改標籤--add-assignee LOGIN/--remove-assignee LOGIN-- 修改指派對象--milestone NAME/--remove-milestone-- 設定或移除里程碑
留言
在現有議題上新增留言。
gh issue comment 123 --body "Comment text"
關閉 / 重新開啟
關閉或重新開啟議題。可以選擇指定關閉原因並留下留言。
gh issue close 123 --comment "Fixed in PR #456" --reason "not planned"
gh issue close 123 --duplicate-of 456
gh issue reopen 123
關閉原因:completed(預設)、not planned、duplicate。
狀態
顯示與您相關的議題摘要:指派給您的、提及您的以及由您開啟的議題。
gh issue status
有關議題類型、子議題、父關係、封鎖相依性及其 JSON 欄位(需要在支援的 GitHub 主機上),請參閱 Issues reference。
拉取請求
使用這些命令來檢視和檢查 PR。有關建立、合併、審查和管理 PR,請參閱 Pull Requests reference。
列表
列出儲存庫中的拉取請求,可依狀態、作者、標籤或搜尋查詢進行篩選。預設僅列出開啟的 PR。
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
旗標:
--state VALUE--open(預設)、closed、merged、all--draft-- 依草稿狀態篩選--author LOGIN/--assignee LOGIN-- 依作者或指派對象篩選--label NAME-- 依標籤篩選--search QUERY-- GitHub 搜尋語法--app NAME-- 依 GitHub App 作者篩選(例如dependabot)
關鍵 JSON 欄位:number、title、state、author、headRefName、baseRefName、labels、reviewDecision、isDraft、statusCheckRollup、files、commits、reviews、url
檢視
顯示 PR 的標題、主體、審查狀態、檢查及其他後設資料。不帶引數時,顯示目前分支的 PR。使用 --comments 以包含留言串。
gh pr view 123
gh pr view 123 --comments
gh pr view 123 --json title,body,files,commits,reviews,reviewDecision
狀態
顯示與您相關的 PR 摘要:目前分支的 PR、您建立的 PR,以及請求您審查的 PR。
gh pr status
討論區
使用 gh discussion 進行儲存庫討論區操作(gh 2.94 中的預覽功能)。從讀取命令開始,並使用 --help 驗證旗標,因為該命令組處於預覽狀態:
gh discussion list --repo owner/repo --limit 10
gh discussion view 123 --repo owner/repo --comments
有關建立、編輯、留言、回覆串、JSON 輸出格式及 GraphQL 後備模式,請參閱 Discussions reference。
搜尋
跨 GitHub 搜尋議題、PR、程式碼、提交紀錄和儲存庫。對單一儲存庫使用 gh issue list / gh pr list;跨儲存庫或跨擁有者的查詢則使用 gh search ...。
有關完整的搜尋查詢語法,請參閱 GitHub search docs。有關每個子命令的特定旗標,請執行 gh search <subcommand> --help。
速率限制: 搜尋 API 的速率限制比核心 API 更嚴格。程式碼搜尋的限制最嚴格(~10/分鐘,已驗證;需要驗證)。其他搜尋命令允許已驗證 ~30/分鐘,或未驗證 ~10/分鐘。使用 gh api rate_limit --jq '.resources | {search, code_search}' 檢查目前配額。
何時該 Clone 而非搜尋: 請參閱 Agent 指南,了解何時該 Clone 而非使用 API。
Bot 與 App: 對於 GitHub App 作者(例如 Dependabot),請使用 --app dependabot;--author dependabot 會過濾使用者帳戶,而非 App 作者。
偵察: 在探索不熟悉的儲存庫時,請先檢查其主要語言,以選擇正確的 --extension 和 --language 值:
gh repo view owner/repo --json primaryLanguage --jq '.primaryLanguage.name'
議題
使用關鍵字、標籤、狀態或 GitHub 搜尋語法,跨儲存庫搜尋議題。
gh search issues "error handling" --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
關鍵旗標:--repo、--owner、--state、--label、--assignee、--author、--app、--involves、--comments、--match、--sort、--include-prs。
PR
跨儲存庫搜尋拉取請求。支援依作者、審查狀態、合併狀態和草稿狀態進行篩選。
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
關鍵旗標:--repo、--owner、--state、--merged、--draft、--author、--assignee、--app、--label、--review、--review-requested、--base、--head、--checks、--sort。
程式碼
在 GitHub 儲存庫中搜尋檔案內容。僅回傳匹配的行(不含行號,不含周圍上下文)。對於定位包含特定模式的檔案很有用,但後續應透過讀取檔案或 Clone 儲存庫來理解程式碼邏輯。
限制: 使用舊版搜尋引擎(結果可能與 github.com 不符)。僅搜尋預設分支。僅索引小於 384 KB 的檔案。每個查詢必須包含至少一個搜尋詞(單獨使用限定詞的搜尋,例如 --extension ts,將會失敗)。不支援 --sort 或 --order——結果始終按相關性排序。
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
關鍵旗標:--repo、--owner、--extension、--filename、--language、--match、--size。
關鍵 JSON 欄位:path、repository、sha、textMatches、url。
textMatches 欄位提供帶有字元級匹配位置的片段上下文——當您需要的上下文比預設文字輸出所提供的更多時,請使用 --json path,textMatches。
提交紀錄
依提交訊息文字、作者、提交日期或雜湊值搜尋提交紀錄。
gh search commits "fix bug" --repo owner/repo
gh search commits --author username --committer-date ">2024-01-01"
gh search commits --hash abc1234
關鍵旗標:--repo、--owner、--author、--committer、--author-date、--committer-date、--author-name、--author-email、--hash、--merge、--sort。
儲存庫
依關鍵字、語言、主題、星數、許可證或擁有者搜尋儲存庫。注意:--repo 在此子命令上不可用——請使用 --owner 來依擁有者篩選。
gh search repos "keyword" --language python --sort stars --order desc
gh search repos --topic cli --stars ">1000" --language go
關鍵旗標:--owner、--language、--topic、--stars、--forks、--license、--created、--updated、--match、--sort、--include-forks、--visibility。
排除限定詞(連字號前綴)
包含排除項目的搜尋查詢(例如 -label:bug)需要特殊語法以避免 Shell 旗標解釋。所有旗標(例如 --limit)必須出現在 -- 之前;-- 之後的任何內容都會被解釋為搜尋查詢文字:
# 類 Unix Shell
gh search issues -- "my query -label:bug"
# PowerShell
gh --% search issues -- "my query -label:bug"
…
[truncated for translation]