gh-search-repos

GitHub CLI：搜索仓库

概述

使用 gh search repos 搜索 GitHub 上的所有仓库。可按星标数、复刻数、语言、主题、许可证等条件筛选。

何时使用此技能

在 GitHub 上搜索仓库时使用此技能：

• 按受欢迎程度（星标数／复刻数）查找仓库
• 按编程语言或主题搜索
• 查找包含优质入门问题的仓库
• 按许可证或归档状态筛选
• 在特定组织中或按所有者搜索
• 需要排除某些结果（需要使用 -- 标志）

语法

gh search repos [<query>] [flags]

关键标志参考

仓库属性

标志	用途	示例
--language <string>	编程语言	--language python
--topic <strings>	仓库主题	--topic machine-learning
--license <strings>	许可证类型	--license mit
--archived {true|false}	归档状态	--archived false
--owner <strings>	仓库所有者	--owner github
--visibility <string>	可见性：public、private、internal	--visibility public

受欢迎程度指标

标志	用途	示例
--stars <number>	星标数	--stars ">1000"
--forks <number>	复刻数	--forks ">100"
--followers <number>	关注者数	--followers ">50"
--size <string>	大小（KB）	--size "100..1000"

问题数量

标志	用途	示例
--good-first-issues <number>	“适合新手的问题”标签数量	--good-first-issues ">=5"
--help-wanted-issues <number>	“需要帮助”标签数量	--help-wanted-issues ">=3"

日期筛选

标志	用途	示例
--created <date>	创建日期	--created ">2024-01-01"
--updated <date>	最后更新日期	--updated ">2024-06-01"

搜索范围

标志	用途	示例
--match <strings>	搜索范围：名称、描述、readme	--match name
--include-forks {false|true|only}	包含／排除复刻仓库	--include-forks false

输出与排序

标志	用途	示例
-L, --limit <int>	最大结果数（默认值：30）	--limit 100
--sort <string>	排序依据：星标数、复刻数、更新时间等	--sort stars
--order <string>	排序方向：asc 或 desc	--order desc
--json <fields>	JSON 输出	--json name,stargazersCount,language
-w, --web	在浏览器中打开	-w

JSON 输出字段

createdAt、defaultBranch、description、forksCount、fullName、hasDownloads、hasIssues、hasPages、hasProjects、hasWiki、homepage、id、isArchived、isDisabled、isFork、isPrivate、language、license、name、openIssuesCount、owner、pushedAt、size、stargazersCount、updatedAt、url、visibility、watchersCount

排除语法（至关重要！）

使用内联查询排除项（以 - 表示否定）时，必须使用 -- 分隔符：

✅ 正确：gh search repos -- "search-terms -qualifier:value" ❌ 错误：gh search repos "search-terms" --flag=-value ❌ 错误：gh search repos "search-terms" --flag=!value ❌ 错误：gh search repos --language=-Go

示例：

• gh search repos -- "cli -language:go"（排除该语言）
• gh search repos -- "starter -archived:true"（排除已归档仓库）
• gh search repos -- "web -topic:deprecated"（排除该主题）
• gh search repos -- "library -license:gpl-3.0"（排除该许可证）

为什么需要使用 -- 分隔符： -- 会告诉 shell 停止解析标志，并将其后的所有内容视为参数。否则，引号中的 -qualifier:value 可能会被误解。

关键语法规则

何时使用标志语法与查询语法

决策树：

Does your search include:
  - Any exclusions (NOT, minus, without, except)?  → Use Query Syntax with `--`
  - Complex boolean logic (OR, AND)?              → Use Query Syntax with `--`

Otherwise:
  - Simple positive filters only?                  → Use Flag Syntax

标志语法（用于正向筛选）：

gh search repos "cli" --language go --stars ">100"

使用 -- 的查询语法（排除时必须使用）：

gh search repos -- "cli -language:javascript -archived:true"

⚠️ 绝不要在同一条命令中混用这两种语法！

1. 排除与否定

**重要：**排除结果时，必须使用带 -- 分隔符的查询语法。

排除语法规则：

1. 在查询前使用 -- 分隔符
2. 使用 -限定符:值 格式（用连字符前缀表示否定）
3. 将整个查询字符串括在引号中

示例：

单项排除：

# Exclude specific language
gh search repos -- "web framework -language:javascript"

# Exclude archived repos
gh search repos -- "cli tool -archived:true"

多项排除：

# Exclude multiple languages
gh search repos -- "game engine -language:javascript -language:python"

# Exclude archived and small repos
gh search repos -- "starter -archived:true -stars:<10"

与使用标志的正向筛选组合：

# Wrong - mixing syntaxes:
gh search repos "cli" --language go -archived:true  # ❌

# Correct - use query syntax for everything when excluding:
gh search repos -- "cli language:go -archived:true"  # ✅

PowerShell 排除：

# Use --% to prevent PowerShell parsing
gh --% search repos -- "cli -language:javascript"

常见排除模式：

用户请求	命令
“查找非归档仓库”	gh search repos -- "starter -archived:true"
“排除特定语言的仓库”	gh search repos -- "web framework -language:php"
“不属于特定主题的仓库”	gh search repos -- "cli -topic:deprecated"
“排除多种语言的仓库”	gh search repos -- "game -language:javascript -language:css"
“非分叉仓库”	gh search repos -- "template -is:fork"（或使用 --include-forks false）
“排除星标数较少的仓库”	gh search repos -- "framework -stars:<100"
“不使用特定许可证的仓库”	gh search repos -- "library -license:gpl-3.0"

2. 特殊值

• 多个主题：--topic unix,terminal
• 布尔标志：--archived false 或 --archived true
• 是否包含分叉仓库：--include-forks false|true|only

3. 引号规则

多词搜索：

gh search repos "machine learning"

比较运算符需要加引号：

gh search repos "python" --stars ">1000"

范围需要加引号：

gh search repos "cli" --stars "100..500"

常见用例

查找热门 Python 仓库：

gh search repos "data science" --language python --stars ">5000"

查找适合新手的议题：

gh search repos --language javascript --good-first-issues ">=10"

查找近期更新的仓库：

gh search repos "react" --updated ">2024-01-01" --stars ">100"

按主题查找仓库：

gh search repos --topic machine-learning --language python

按许可证查找仓库：

gh search repos "web framework" --license mit,apache-2.0

排除归档仓库：

gh search repos "cli tool" --archived false

按组织查找仓库：

gh search repos --owner microsoft --visibility public

排除分叉仓库：

gh search repos "starter" --include-forks false

仅查找分叉仓库：

gh search repos "template" --include-forks only

查找星标数在指定范围内的仓库：

gh search repos "game engine" --stars "100..1000"

排除特定语言：

gh search repos -- "cli -language:go"

仅搜索名称：

gh search repos "awesome" --match name

常见错误

错误	问题	修正方法
--language="NOT javascript" 或 --archived=-true	标志语法不支持否定	使用查询：-- "-language:javascript" 或 -- "-archived:true"
gh search repos cli -language:js	-language 被解释为标志	使用 --：-- "cli -language:js"
"cli NOT language:js"	NOT 关键字不起作用	使用 -：-- "cli -language:js"
混用语法：--stars ">100" "cli -language:js"	不能混用标志和查询限定符	全部使用查询：-- "cli stars:>100 -language:js"
比较值未加引号	Shell 会解释 >	加引号：--stars ">1000"
--archived archived	值无效	使用布尔值：--archived true 或 false
多词搜索未加引号	会分别搜索	加引号："machine learning"
所有者前使用 @	语法无效	去掉 @：--owner github
在 PowerShell 中不使用 --%	排除条件会导致命令出错	添加：gh --%

安装检查

如果找不到 gh 命令：

# Check if gh is installed
which gh

# Install: https://cli.github.com/manual/installation

如果尚未通过身份验证：

# Authenticate with GitHub
gh auth login

比较运算符

• > - 大于
• >= - 大于或等于
• < - 小于
• <= - 小于或等于
• .. - 范围：100..1000 或 2024-01-01..2024-12-31

常见许可证

• mit - MIT 许可证
• apache-2.0 - Apache 许可证 2.0
• gpl-3.0 - GNU GPL v3
• bsd-2-clause - BSD 2-Clause
• bsd-3-clause - BSD 3-Clause
• mpl-2.0 - Mozilla 公共许可证 2.0
• isc - ISC 许可证

匹配字段选项

• name - 仅搜索仓库名称
• description - 仅搜索描述
• readme - 仅搜索 README 文件

示例：gh search repos "documentation" --match readme

相关内容

• GitHub 搜索语法：https://docs.github.com/search-github/searching-on-github/searching-for-repositories
• 搜索其他资源：gh-search-code、gh-search-commits、gh-search-issues、gh-search-prs