gh-cli

GitHub CLI - 远程分析与发现

无需克隆即可执行远程仓库操作、比较代码库并发现代码。

适用场景

• 无需克隆即可分析仓库
• 并排比较代码库
• 从任意仓库获取特定文件
• 查找热门仓库和代码模式
• 搜索 GitHub 上的代码

快速操作

远程获取文件

gh repo read-file path/file.ts --repo OWNER/REPO

gh repo read-file（预览版）是首选方式：它会输出原始内容，接受 --ref 来指定任意分支、标签或提交，并能处理大文件。--output PATH 会将内容写入磁盘（使用 --clobber 可覆盖）；--json 会返回元数据（content, downloadUrl, encoding, gitSHA, gitUrl, htmlUrl, name, path, size, type, url）。如果该命令不可用，则使用 gh api：

gh api repos/OWNER/REPO/contents/path/file.ts -H "Accept: application/vnd.github.raw"

没有 base64decode 模板函数——--template '{{.content | base64decode}}' 会报错 function "base64decode" not defined。若要解码默认 JSON 响应，请通过管道传递：

gh api repos/OWNER/REPO/contents/path/file.ts --jq '.content' | base64 -d

Contents API 只会内联不超过 1MB 的文件。超过此大小后，.content 会变成空字符串（encoding: "none"），上面的管道也不会输出任何内容——请改用 read-file 或原始 Accept 标头。

终端转义序列（gh 2.97.0+）

如果远程内容包含终端转义序列（ANSI 艺术字、某些测试样例），gh 会拒绝将其输出到终端，而不是直接传递：

• gh repo read-file：file contains terminal escape sequences; use --allow-escape-sequences to read anyway
• gh api 原始响应正文：the response contains terminal escape sequences; pass --allow-escape-sequences to output it anyway
• 通过管道传递时的 gh pr diff：the diff contains terminal escape sequences; pass --allow-escape-sequences to output it anyway

需要原样获取字节时，请传入 --allow-escape-sequences（gh release download --output - 和 gh gist view 也适用）；或者使用 gh repo read-file --output 写入磁盘，该方式始终保留原始字节。此检查随 GHSA-3m3g-3wcr-px46 修复一同引入；请运行 gh 2.98.0 或更高版本，以获取该修复以及其他 2.97/2.98 安全修复。

获取目录列表

gh repo read-dir PATH --repo OWNER/REPO    # omit PATH to list the repo root

# Or via the API
gh api repos/OWNER/REPO/contents/PATH

gh repo read-dir --json 返回的是对象而非数组，即 {"entries":[...]}，因此请使用 .entries[] 进行筛选：

gh repo read-dir src --repo OWNER/REPO --json name,type --jq '.entries[] | select(.type=="file") | .name'

在脚本化工作流中固定仓库

gh 会根据当前工作目录推断仓库。在 Agent 或 CI 工作流中，cd 可能会持续生效，因此务必传入 --repo OWNER/REPO，避免命令因意外的当前工作目录而悄然指向其他仓库。未传入 --repo 时可能出现以下情况：

• 当前目录不在 Git 仓库中：failed to run git: fatal: not a git repository
• 当前目录在没有远程地址的仓库中：no git remotes found
• 当前目录在另一个仓库中：不会报错——命令会针对该仓库执行，而来自其他仓库的 ID 会返回 404

搜索代码

gh search code "pattern" --language=typescript

查找热门仓库

gh search repos --language=rust --sort stars --order desc

比较两个代码库

通过系统化的工作流比较仓库，以识别异同。

使用示例：“比较 solana-fm/explorer-kit 和 tenequm/solana-idls”

第 1 步：获取目录结构

gh repo read-dir PATH --repo OWNER-A/REPO-A
gh repo read-dir PATH --repo OWNER-B/REPO-B

如果要比较单体仓库中的某个包，请指定路径（例如 packages/explorerkit-idls）。

第 2 步：比较文件列表

diff <(gh repo read-dir PATH --repo OWNER-A/REPO-A --json name --jq '.entries[].name') \
     <(gh repo read-dir PATH --repo OWNER-B/REPO-B --json name --jq '.entries[].name')

以 < 开头的行只存在于仓库 A 中，以 > 开头的行只存在于仓库 B 中。

第 3 步：获取关键文件进行比较

比较包依赖：

gh repo read-file package.json --repo OWNER-A/REPO-A
gh repo read-file package.json --repo OWNER-B/REPO-B

比较主入口点：

gh repo read-file src/index.ts --repo OWNER-A/REPO-A
gh repo read-file src/index.ts --repo OWNER-B/REPO-B

重复检查相同文件时，可为 gh api 调用添加 --cache 1h，以避免重复消耗速率限制额度。

比较同一仓库的两个引用（或其分支）只需调用一次比较 API，该 API 最多支持 250 个提交和 300 个文件：

gh api repos/OWNER/REPO/compare/v1.0.0...v2.0.0 --jq '{ahead_by, files: [.files[].filename]}'

步骤 4：分析差异

比较获取的文件，找出：

API 表面

• 导出了哪些函数／类？
• API 是相似还是完全不同？

依赖项

• 共同依赖项（采用相同的方法）
• 不同的依赖项（实现方式不同）

独有功能

• 仅 repo1 中有的功能
• 仅 repo2 中有的功能

详细的比较策略请参阅 references/comparison.md。

发现热门内容

查找热门代码仓库

# Most starred repos - a bare `--sort` with no query or filter flag fails: Invalid search query ""
gh search repos "stars:>10000" --sort stars --order desc --limit 20

# Trending in specific language
gh search repos --language=rust --sort stars --order desc

# Recently popular (created in the last 30 days; works with BSD and GNU date)
SINCE=$(date -v-30d +%F 2>/dev/null || date -d '30 days ago' +%F)
gh search repos "created:>$SINCE" --sort stars --order desc

# Trending in specific topic
gh search repos "topic:machine-learning" --sort stars --order desc

发现热门代码模式

# Find popular implementations (code search has no sorting - scope with filters)
gh search code "function useWallet" --language=typescript

# Scope to a known repo (code search can't filter by stars - stars:>N is literal text)
gh search code "implementation" --repo=honojs/hono

# Search specific organization
gh search code "authentication" --owner=anthropics

完整的发现查询和模式请参阅 references/discovery.md。

搜索基础

代码搜索

# Search across all repositories
gh search code "API endpoint" --language=python

# Search in specific organization
gh search code "auth" --owner=anthropics

# Exclude results with negative qualifiers
gh search issues -- "bug report -label:wontfix"

Issue 和 PR 搜索

# Find open bugs (--state takes only open|closed here; omit it for both)
gh search issues --label=bug --state=open

# Search assigned issues
gh search issues --assignee=@me --state=open

# Meaning-based issue search (gh 2.98.0+): relevance-ranked, issues only, one page, no --sort/--order
gh search issues worktree checkout --repo cli/cli --search-type hybrid

单独的词会按 AND 关系组合。带引号的多词参数会作为精确短语发送，因此 gh search issues "worktree checkout" 可能不返回任何结果，但退出代码仍为 0。

搜索速率限制

搜索的额度比每小时 5000 次的核心 API 紧得多——请使用 gh api rate_limit 检查：

资源	限制（已通过身份验证）
core（包括 gh api、gh repo read-file）	5000 次／小时
search（代码仓库、issue、PR、提交）	30 次／分钟
code_search	10 次／分钟
semantic_search（--search-type semantic|hybrid）	10 次／分钟——gh api rate_limit 不会列出此项

高级搜索语法请参阅 references/search.md。

特殊语法

字段名称不一致

重要： GitHub CLI 在不同命令中使用的字段名称不一致：

字段	gh repo view	gh search repos
星标数	stargazerCount	stargazersCount
派生数	forkCount	forksCount
主题	repositoryTopics	不可用
关注者	watchers（{totalCount}）	watchersCount——实际上是星标数

示例：

# ✅ Correct for gh repo view
gh repo view owner/repo --json stargazerCount,forkCount

# ✅ Correct for gh search repos
gh search repos "query" --json stargazersCount,forksCount

有些字段在看似应该存在的地方并不存在：gh pr view 没有 merged（请使用 mergedAt 或 state），gh search prs 没有 mergedAt（请使用 closedAt），gh run list 没有 jobs（请使用 gh run view <id> --json jobs）。字段错误时会显示 Unknown JSON field: "X"，随后列出有效字段。

每个参数只用一个限定符

gh search（gh 2.97.0+）会在每个参数中的第一个 : 处分割，并在其余部分包含空格时将其用引号括起来。将多个限定符打包到一个带引号的字符串中，会导致筛选条件悄无声息地失效：

# ❌ Sent as language:"go stars:>500" - the language filter is lost
gh search repos "rate limiting middleware language:go stars:>500"

# ✅ Keywords and qualifiers as separate arguments; quote only those containing > or <
gh search repos rate limiting middleware language:go "stars:>500"

gh pr list --search 和 gh issue list --search 会原样传递字符串，因此在这些命令中，将字符串用引号括起来即可。

排除搜索结果

负向限定符可以单独作为一个参数，也可以放在带引号的字符串末尾（"bug report -label:wontfix"）。只有当查询以连字符开头时才需要 --，否则 Shell 会将其识别为标志。

所有标志都要放在 -- 之前。 -- 之后的所有内容都会作为位置参数，因此末尾的标志会被并入查询字符串：

# ✅ Correct - flags first
gh search issues --limit 5 -- -label:wontfix bug

# ❌ Wrong - --limit 5 becomes part of the search query, silently returning 30 results
gh search issues -- -label:wontfix bug --limit 5

更多语法注意事项请参阅 references/syntax.md。

脚本注意事项

• 每条命令都需要身份验证——没有令牌时，gh 会打印 please run: gh auth login 并以状态码 4 退出。例外是对公开仓库运行 gh release download。

• gh api 会将错误正文写入标准输出。 失败时，它会以状态码 1 退出，在标准错误中打印 gh: Not Found (HTTP 404)，并在标准输出中打印错误 JSON，且不会应用 --jq。因此，$(gh api ...) 会将错误当作数据捕获，所以要检查退出状态：

  if sha=$(gh api repos/OWNER/REPO/contents/README.md --jq .sha); then echo "$sha"; else echo "fetch failed" >&2; fi
  

• -f/-F 会让 gh api 改用 POST，因此仅支持 GET 的端点会返回 404。添加 -X GET，以查询字符串形式发送字段：

  gh api -X GET search/issues -f q='repo:cli/cli is:open worktree' --jq '.total_count'
  

• --jq 接受一个表达式，不接受 jq 标志（末尾加上 -r 会报错 unknown shorthand flag: 'r'）；字符串结果本身就会以原始形式输出。

• --paginate --slurp 不能与 --jq/--template 组合使用。 请改用管道传给 jq，或使用 --paginate --jq，后者会逐页筛选。

• 包含 ? 的端点要加引号——zsh 会将未加引号的 ? 视为通配符，并报错 no matches found。

• 退出代码（gh help exit-codes）：0 表示成功，1 表示失败，2 表示已取消，4 表示需要身份验证。有些命令还有自己的退出代码：检查仍在等待时，gh pr checks 会以状态码 8 退出。

预览命令

近期的 gh 版本新增了与远程分析和发现相关的预览命令。这些命令可能随时变更，恕不另行通知。

# Read a repo without cloning (see Quick Operations above)
gh repo read-file PATH --repo OWNER/REPO
gh repo read-dir PATH --repo OWNER/REPO

# GitHub Discussions - often where design rationale lives
gh discussion list --repo OWNER/REPO --search "keyword" --answered
gh discussion view <number> --repo OWNER/REPO --comments

# Agent skills on GitHub
gh skill search <query>
gh skill preview OWNER/REPO <skill>    # print SKILL.md without installing
gh skill install OWNER/REPO <skill>

gh discussion list --json 会返回 {"discussions":[...],"next":...,"totalCount":...}，因此可使用 --jq '.discussions[].title' 进行筛选。gh discussion view 也接受评论 URL（.../discussions/123#discussioncomment-456），以显示一条完整的回复线程；--comments 不能与 --json 组合使用。

gh pr revert <number>（打开一个用于还原已合并 PR 的 PR）是常规命令，并非预览命令——请参阅 pull_requests.md。

高级工作流

有关特定工作流的详细文档：

核心工作流：

• remote-analysis.md - 高级文件获取模式
• comparison.md - 完整代码库比较指南
• discovery.md - 所有趋势和发现查询
• search.md - 高级搜索语法
• syntax.md - 特殊语法和命令注意事项

GitHub 操作：

• repositories.md - 仓库操作
• pull_requests.md - PR 工作流、CI 检查、评审线程
• issues.md - Issue 管理
• actions.md - GitHub Actions、运行尝试、重新运行
• releases.md - Release 管理

设置与配置：

• getting_started.md - gh auth setup-git 凭据助手
• other.md - 环境变量、身份验证陷阱、别名、配置
• extensions.md - CLI 扩展

资源

• 官方文档：https://cli.github.com/manual/
• GitHub CLI：https://github.com/cli/cli
• 搜索语法：https://docs.github.com/en/search-github