命令速查表与最佳实践#
本章是 GitHub CLI 的完整命令速查表，按功能分类组织，并集成了 SpecWeave 工作流的最佳实践和常用自动化模式。
使用方式：按
Ctrl+F搜索命令名或场景关键词，快速定位所需命令。本节也是前几章所有命令的浓缩索引，适合日常开发中随时查阅。
1. 命令速查表#
1.1 Auth & Config（认证与配置）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
交互式登录 |
|
|
非交互式登录（CI/CD） |
|
|
使用 SSH 协议登录 |
|
|
登录到 GHES |
|
|
登出 |
|
|
查看认证状态 |
|
|
查看指定主机认证状态 |
|
|
查看当前 Token |
|
|
刷新认证凭证 |
|
|
列出所有配置 |
|
|
设置配置项 |
|
|
获取配置项 |
|
1.2 Repo（仓库管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
克隆仓库 |
|
|
浅克隆 |
|
|
交互式创建仓库 |
|
|
创建公开仓库并克隆 |
|
|
创建私有仓库 |
|
|
从模板创建 |
|
|
Fork 当前仓库 |
|
|
Fork 并克隆 |
|
|
Fork 到组织 |
|
|
终端查看仓库信息 |
|
|
浏览器打开仓库 |
|
|
JSON 格式输出 |
|
|
列出自己的仓库 |
|
|
列出指定用户的仓库 |
|
|
按语言筛选 |
|
|
按话题筛选 |
|
|
仅非 Fork 仓库 |
|
|
同步 Fork 仓库 |
|
|
同步指定仓库 |
|
|
重命名仓库 |
|
|
删除仓库 |
|
|
归档仓库 |
|
1.3 Issue（议题管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
交互式创建议题 |
|
|
快速创建议题 |
|
|
指定负责人和标签 |
|
|
关联里程碑 |
|
|
浏览器创建 |
|
|
从文件读取正文 |
|
|
列出开放议题 |
|
|
列出所有议题 |
|
|
按标签筛选 |
|
|
按负责人筛选 |
|
|
按里程碑筛选 |
|
|
全文搜索 |
|
|
限制返回数量 |
|
|
JSON 输出 |
|
|
查看议题详情 |
|
|
查看含评论 |
|
|
浏览器查看 |
|
|
查看与自己相关的议题 |
|
|
关闭议题 |
|
|
关闭并注明原因 |
|
|
关闭并评论 |
|
|
重新打开议题 |
|
|
重新打开并评论 |
|
|
添加评论 |
|
|
从文件评论 |
|
|
修改标题 |
|
|
添加标签 |
|
|
移除标签 |
|
|
添加负责人 |
|
|
设置里程碑 |
|
|
锁定议题 |
|
|
解锁议题 |
|
|
转移议题 |
|
1.4 PR（Pull Request 工作流）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
交互式创建 PR |
|
|
快速创建 PR |
|
|
自动填充（宽松模式） |
|
|
自动填充（详细模式） |
|
|
创建草稿 PR |
|
|
浏览器创建 |
|
|
指定源/目标分支 |
|
|
指定审查者和负责人 |
|
|
指定标签和里程碑 |
|
|
从文件读取描述 |
|
|
恢复中断的 PR 创建 |
|
|
列出 PR |
|
|
列出所有状态 |
|
|
列出已合并 PR |
|
|
按标签筛选 |
|
|
按负责人筛选 |
|
|
按作者筛选 |
|
|
按目标分支筛选 |
|
|
全文搜索 |
|
|
限制数量 |
|
|
JSON 输出 |
|
|
查看 PR 详情 |
|
|
查看含评论 |
|
|
浏览器查看 |
|
|
JSON 输出 |
|
|
查看 PR 概览 |
|
|
检出 PR 到本地 |
|
|
跨仓库检出 |
|
|
查看 CI 检查 |
|
|
实时监控 CI |
|
|
查看变更差异 |
|
|
仅列文件名 |
|
|
彩色输出 |
|
|
合并 PR（默认策略） |
|
|
压缩合并 |
|
|
变基合并 |
|
|
自动合并（CI 通过后） |
|
|
合并后删除分支 |
|
|
批准 PR |
|
|
批准并评论 |
|
|
仅评论 |
|
|
请求修改 |
|
|
关闭 PR |
|
|
关闭并评论 |
|
|
重新打开 PR |
|
|
重新打开并评论 |
|
|
草稿→就绪 |
|
|
添加评论 |
|
|
从文件评论 |
|
1.5 Actions（CI/CD 管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
列出工作流 |
|
|
列出所有（含禁用） |
|
|
限制数量 |
|
|
查看工作流 |
|
|
按 ID 查看 |
|
|
浏览器查看 |
|
|
启用工作流 |
|
|
禁用工作流 |
|
|
手动触发工作流 |
|
|
带参数触发 |
|
|
指定分支触发 |
|
|
列出运行记录 |
|
|
按工作流筛选 |
|
|
按分支筛选 |
|
|
仅失败运行 |
|
|
限制数量 |
|
|
查看运行详情 |
|
|
查看运行日志 |
|
|
仅查看失败日志 |
|
|
查看指定 Job 日志 |
|
|
浏览器查看 |
|
|
实时监控运行 |
|
|
重新运行 |
|
|
仅重跑失败 Job |
|
|
下载产物 |
|
|
按名称下载产物 |
|
|
指定下载目录 |
|
|
取消运行 |
|
|
删除运行记录 |
|
1.6 Release（发布管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
创建 Release |
|
|
指定标题和说明 |
|
|
自动生成 Release Notes |
|
|
创建为草稿 |
|
|
标记为预发布 |
|
|
指定目标分支 |
|
|
上传资产文件 |
|
|
列出 Release |
|
|
限制数量 |
|
|
排除草稿 |
|
|
排除预发布 |
|
|
查看 Release |
|
|
浏览器查看 |
|
|
JSON 输出 |
|
|
下载 Release 资产 |
|
|
按模式下载 |
|
|
指定下载目录 |
|
|
上传资产 |
|
|
删除 Release |
|
|
编辑 Release |
|
1.7 Gist（代码片段管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
创建 Gist |
|
|
创建含描述 |
|
|
创建公开 Gist |
|
|
从管道创建 |
|
|
指定文件名 |
|
|
多文件 Gist |
|
|
列出 Gist |
|
|
限制数量 |
|
|
仅公开 Gist |
|
|
仅私密 Gist |
|
|
查看 Gist |
|
|
查看指定文件 |
|
|
原始格式输出 |
|
|
浏览器查看 |
|
|
编辑 Gist |
|
|
修改描述 |
|
|
添加文件 |
|
|
删除 Gist |
|
1.8 API & Search（API 调用与搜索）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
REST API 调用 |
|
|
指定 HTTP 方法 |
|
|
发送表单字段 |
|
|
发送原始字段 |
|
|
自定义 Header |
|
|
自动翻页 |
|
|
jq 过滤 |
|
|
GraphQL 查询 |
|
|
GraphQL 变量 |
|
|
搜索仓库 |
|
|
限制结果数 |
|
|
按星标排序 |
|
|
搜索 Issue |
|
|
搜索 PR |
|
|
搜索代码 |
|
|
搜索提交 |
|
1.9 Extensions（扩展管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
安装扩展 |
|
|
列出已安装扩展 |
|
|
搜索扩展 |
|
|
移除扩展 |
|
|
升级扩展 |
|
|
升级全部扩展 |
|
|
浏览器浏览扩展 |
|
|
创建新扩展 |
|
1.10 Secret & Variable（密钥与变量管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
列出仓库 Secrets |
|
|
列出环境 Secrets |
|
|
列出组织 Secrets |
|
|
设置 Secret |
|
|
直接设置值 |
|
|
设置环境 Secret |
|
|
设置组织 Secret |
|
|
删除 Secret |
|
|
列出变量 |
|
|
设置变量 |
|
|
删除变量 |
|
1.11 Alias（别名管理）#
命令 |
用途 |
常用示例 |
|---|---|---|
|
创建别名 |
|
|
创建 Shell 别名 |
|
|
列出别名 |
|
|
删除别名 |
|
1.12 其他命令#
命令 |
用途 |
常用示例 |
|---|---|---|
|
浏览器打开仓库主页 |
|
|
打开指定 Issue/PR |
|
|
打开指定文件 |
|
|
打开指定行范围 |
|
|
打开指定分支 |
|
|
打开最后一次提交 |
|
|
打开仓库设置 |
|
|
打开 Wiki |
|
|
仅打印 URL |
|
|
列出标签 |
|
|
创建标签 |
|
|
编辑标签 |
|
|
删除标签 |
|
|
列出 Codespaces |
|
|
创建 Codespace |
|
|
SSH 连接 Codespace |
|
|
删除 Codespace |
|
|
Copilot 建议 |
|
|
Copilot 解释 |
|
|
验证产物签名 |
|
|
生成补全脚本 |
|
2. SpecWeave 工作流集成最佳实践#
在 SpecWeave 的 AI 辅助开发范式中，gh 是 AI 智能体与 GitHub 之间的核心桥梁。以下最佳实践覆盖了 gh 在 SpecWeave 工作流中的典型应用场景。
2.1 Spec 驱动的开发（Spec → Issue → PR）#
SpecWeave 的核心理念是"先规范、后编码"。gh 在此过程中的角色是将 Spec 文档映射为 GitHub 上的 Issue 和 PR：
# 1. 从 Spec 创建 Issue（将 spec.md 中的任务拆解为 Issue）
gh issue create \
-t "feat: 实现用户认证模块（Spec S-001）" \
-F ./specs/feature-auth/spec.md \
-a @me -l "feature,spec" -m "v2.0"
# 2. 开始开发后，基于 Issue 创建关联 PR
git checkout -b feature/auth-module
# ... 编写代码 ...
git add . && git commit -m "feat: 实现 JWT 认证流程
实现 S-001 规范中的认证模块核心功能：
- Token 签发与验证
- 中间件集成
- 单元测试覆盖
Closes #42"
git push -u origin feature/auth-module
# 3. 创建 PR，关联 Issue 和 Spec
gh pr create \
-t "feat: 实现用户认证模块（Spec S-001）" \
-F ./specs/feature-auth/pr-body.md \
-r "tech-lead" -a @me \
-l "feature,spec" -m "v2.0"
2.2 原子化提交工作流#
SpecWeave 要求每次提交遵循 Conventional Commits 规范，且单一职责——一个 PR 对应一个 Spec 中的一个清晰变更单元。
# 原子化提交流程：每个功能点一个 PR
# 1. 先创建 Issue 作为任务追踪
gh issue create -t "feat: 添加报表导出功能" -a @me -l "feature,atomized"
# 2. 从 Issue 创建特性分支
ISSUE_NUM=$(gh issue view --json number --jq '.number' 2>/dev/null || echo "42")
git checkout -b "feature/issue-${ISSUE_NUM}"
# 3. 原子化提交：每个 commit 只做一件事
git commit -m "feat: 添加 CSV 导出接口"
git commit -m "feat: 添加 PDF 导出接口"
git commit -m "test: 添加导出功能单元测试"
git push -u origin "feature/issue-${ISSUE_NUM}"
# 4. 创建 PR，关联 Issue
gh pr create -t "feat: 添加报表导出功能" -F ./pr-body.md \
-r "reviewer" -a @me -l "feature" --body "Closes #${ISSUE_NUM}"
# 5. CI 验证通过后，压缩合并
gh pr checks --watch && gh pr merge --squash --delete-branch
2.3 CI/CD 流水线管理#
SpecWeave 的 CI 综合检查流水线通过 gh 命令进行管理：
# 查看所有工作流
gh workflow list
# 查看 CI 综合检查工作流的最新运行
gh run list -w "CI 综合检查" -L 5
# 手动触发 CI 综合检查
gh workflow run "CI 综合检查" --ref main
# 实时监控 CI 流水线状态
RUN_ID=$(gh run list -w "CI 综合检查" -L 1 --json databaseId --jq '.[0].databaseId')
gh run watch "$RUN_ID"
# 查看失败的检查日志
gh run view "$RUN_ID" --log-failed
# 重跑失败的工作流
gh run rerun "$RUN_ID" --failed
2.4 Secret 与变量管理#
在 CI/CD 自动化中，通过 gh 管理密钥和变量，避免手动操作 Web UI：
# 设置仓库级 Secret
gh secret set DEPLOY_SSH_KEY < ~/.ssh/deploy_key
# 设置环境级 Secret（适用于生产环境）
gh secret set DB_PASSWORD -e production -b "$(vault read -field=password secret/db)"
# 设置组织级 Secret（多仓库共享）
gh secret set NPM_PUBLISH_TOKEN -o my-org -b "$NPM_TOKEN"
# 设置 CI 变量
gh variable set DEPLOY_ENV -b "production"
gh variable set NOTIFY_SLACK_CHANNEL -b "#deployments"
# 批量导出 Secrets（审计用）
gh secret list --json name,updatedAt,visibility > secrets-audit.json
2.5 gh copilot — AI 辅助开发集成#
gh copilot 是 GitHub CLI 的 Copilot 扩展，将 AI 辅助能力直接集成到命令行中，与 SpecWeave 的 AI 辅助开发理念高度契合：
# 解释复杂命令
gh copilot explain "git rebase -i HEAD~5"
# 生成 Shell 命令
gh copilot suggest "找出最近 7 天修改过的所有 TypeScript 文件"
# 解释代码逻辑
gh copilot explain "gh api /repos/owner/repo/actions/runs --jq '.workflow_runs[] | select(.conclusion==\"failure\")'"
# 将 Copilot 与 gh 命令结合使用
# 例如：生成一个分析 PR 合并趋势的脚本
gh copilot suggest "使用 gh api 和 jq 统计最近 30 天合并的 PR 数量"
2.6 跨仓库协作模式#
在 SpecWeave 的多仓库架构中，gh 支持跨仓库的 Issue 转移和 PR 管理：
# 将 Issue 转移到其他仓库
gh issue transfer 42 owner/other-repo
# 列出跨仓库的待审查 PR
gh search prs --review-requested=@me --state=open --owner=my-org
# 跨仓库搜索代码引用
gh search code "import.*SpecWeave" --owner=my-org --language=typescript
# 批量克隆组织下的所有仓库
gh repo list my-org --limit 100 --json nameWithOwner --jq '.[].nameWithOwner' | \
while read repo; do gh repo clone "$repo" "repos/$repo"; done
3. 常用工作流模式#
3.1 日常开发一行命令#
以下 Shell 一行命令覆盖了日常开发中最常见的场景：
# 快速创建 PR：推送当前分支后自动创建 PR
git push -u origin HEAD && gh pr create --fill
# 快速查看需要我审查的 PR
gh search prs --review-requested=@me --state=open
# 快速查看我被分配的 Issue
gh issue list --assignee @me --state open
# 快速查看我创建的 PR 的 CI 状态
gh pr checks $(gh pr list --author @me --limit 1 --json number --jq '.[0].number')
# 快速检出最近一个需要审查的 PR
gh pr checkout $(gh search prs --review-requested=@me --state=open --limit 1 --json number --jq '.[0].number')
# 快速合并当前分支对应的 PR（需确认 CI 通过）
gh pr checks --watch && gh pr merge --squash --delete-branch
# 快速同步 Fork 仓库
gh repo sync && git pull
# 快速查看今天的 GitHub 动态
gh api "users/$(gh api user --jq .login)/events" --jq '.[] | select(.created_at > "'$(date -u -Iseconds --date="24 hours ago")'") | "\(.type) \(.repo.name)"'
3.2 批量操作模式#
# 批量关闭满足条件的 Issue
gh issue list -l "stale" -s open --limit 100 --json number --jq '.[].number' | \
while read num; do
gh issue close "$num" -c "自动关闭：超过 30 天无活动"
done
# 批量标记 PR 的审查状态
gh pr list --label "needs-review" --limit 50 --json number --jq '.[].number' | \
while read num; do
gh pr review "$num" --comment -b "批量审查：请检查 CI 是否通过"
done
# 批量下载 Release 资产
gh release list -L 10 --json tagName --jq '.[].tagName' | \
while read tag; do
gh release download "$tag" -p "*.tar.gz" -d "./releases/$tag"
done
# 批量删除已合并的本地分支
git branch --merged | grep -v "main\|master\|develop" | xargs -r git branch -d
3.3 脚本自动化模板#
以下是一个完整的 PR 自动化脚本模板，可在 SpecWeave 项目中使用：
#!/bin/bash
# auto-pr.sh — 自动化 PR 创建与合并脚本
# 用法：./auto-pr.sh "feat: 添加新功能" "feature/my-branch"
set -euo pipefail
TITLE="${1:?请提供 PR 标题}"
BRANCH="${2:?请提供特性分支名}"
BASE_BRANCH="${3:-main}"
REVIEWER="${4:-tech-lead}"
echo "=== 1. 创建特性分支 ==="
git checkout -b "$BRANCH"
echo "=== 2. 提交变更 ==="
git add .
git commit -m "$TITLE" || { echo "无变更可提交"; exit 1; }
echo "=== 3. 推送分支 ==="
git push -u origin "$BRANCH"
echo "=== 4. 创建 PR ==="
PR_URL=$(gh pr create \
--title "$TITLE" \
--base "$BASE_BRANCH" \
--head "$BRANCH" \
--fill \
--reviewer "$REVIEWER" \
--assignee "@me")
echo "=== 5. PR 已创建 ==="
echo "$PR_URL"
echo "=== 6. 等待 CI 检查 ==="
PR_NUM=$(echo "$PR_URL" | grep -oP '\d+$')
gh pr checks "$PR_NUM" --watch
echo "=== 7. CI 检查通过，是否立即合并？(y/n) ==="
read -r answer
if [ "$answer" = "y" ]; then
gh pr merge "$PR_NUM" --squash --delete-branch
echo "=== PR #$PR_NUM 已合并 ==="
git checkout "$BASE_BRANCH"
git pull
git branch -d "$BRANCH"
else
echo "=== PR #$PR_NUM 等待审查 ==="
fi
3.4 GitHub Actions 中的 gh 集成模板#
# .github/workflows/pr-automation.yml
name: PR Automation
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
auto-label:
runs-on: ubuntu-latest
permissions:
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: 自动添加标签
run: |
# 根据 PR 标题自动添加标签
if echo "${{ github.event.pull_request.title }}" | grep -qi "^feat"; then
gh pr edit ${{ github.event.pull_request.number }} --add-label "feature"
elif echo "${{ github.event.pull_request.title }}" | grep -qi "^fix"; then
gh pr edit ${{ github.event.pull_request.number }} --add-label "bug"
elif echo "${{ github.event.pull_request.title }}" | grep -qi "^docs"; then
gh pr edit ${{ github.event.pull_request.number }} --add-label "documentation"
fi
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ci-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 运行 CI 检查
run: |
# 运行项目 CI 检查
npm ci
npm run lint
npm run test
- name: 报告 CI 结果到 PR
if: success() || failure()
run: |
STATUS="${{ job.status }}"
if [ "$STATUS" = "success" ]; then
gh pr comment ${{ github.event.pull_request.number }} \
-b "✅ CI 检查全部通过"
else
gh pr comment ${{ github.event.pull_request.number }} \
-b "❌ CI 检查失败，请查看 [Actions 日志](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})"
fi
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3.5 常用别名推荐#
将以下别名添加到 Shell 配置文件中，大幅提升日常开发效率：
# 将以下内容添加到 ~/.bashrc 或 ~/.zshrc
# GitHub CLI 快捷别名
alias ghpr='gh pr create --fill' # 快速创建 PR
alias ghprw='gh pr create --web' # 浏览器创建 PR
alias ghprs='gh pr status' # 查看 PR 状态
alias ghprl='gh pr list' # 列出 PR
alias ghprv='gh pr view' # 查看 PR 详情
alias ghprc='gh pr checkout' # 检出 PR
alias ghprd='gh pr diff' # 查看 PR 差异
alias ghprm='gh pr merge --squash --delete-branch' # 压缩合并 PR
alias ghprr='gh pr review --approve' # 批准 PR
alias ghisl='gh issue list --assignee @me' # 列出我的 Issue
alias ghisc='gh issue create' # 创建 Issue
alias ghiss='gh issue status' # 查看 Issue 状态
alias ghrc='gh repo clone' # 克隆仓库
alias ghrv='gh repo view --web' # 浏览器查看仓库
alias ghrl='gh repo list' # 列出仓库
alias ghci='gh run watch' # 监控 CI 运行
alias ghcil='gh run list -L 5' # 列出最近 CI 运行
alias ghb='gh browse' # 快速打开 GitHub
alias ghbs='gh browse --settings' # 打开仓库设置
3.6 gh 别名管理#
除了 Shell 别名，gh 本身也支持内置别名，可在所有环境中使用：
# 创建 gh 内置别名
gh alias set co "pr checkout"
gh alias set prs "pr status"
gh alias set prm "pr merge --squash --delete-branch"
gh alias set prr "pr review --approve"
gh alias set issues "issue list --assignee @me"
gh alias set ci "run watch"
# 创建带 Shell 扩展的别名
gh alias set ci-status --shell 'gh run list -L 5 -w "CI"'
# 查看所有别名
gh alias list
# 删除别名
gh alias delete ci
4. 环境变量快速参考#
环境变量 |
用途 |
示例 |
|---|---|---|
|
认证 Token（优先于 |
|
|
认证 Token（GitHub Actions 兼容） |
在 Actions 中自动注入 |
|
默认 GitHub 主机名 |
|
|
GHES 专用 Token |
|
|
默认仓库（ |
|
|
覆盖编辑器设置 |
|
|
覆盖分页器设置 |
|
|
开启调试日志 |
|
|
禁用更新通知 |
|
|
禁用交互式提示 |
|
|
自定义配置目录 |
|
5. 常用筛选参数汇总#
5.1 Issue 搜索语法速查#
搜索语法 |
说明 |
示例 |
|---|---|---|
|
按状态筛选 |
|
|
按标签筛选 |
|
|
按负责人筛选 |
|
|
按作者筛选 |
|
|
按里程碑筛选 |
|
|
在标题中搜索 |
|
|
无负责人 |
|
|
无标签 |
|
|
按创建时间 |
|
|
按更新时间 |
|
5.2 PR 搜索语法速查#
搜索语法 |
说明 |
示例 |
|---|---|---|
|
按状态筛选 |
|
|
待我审查的 PR |
|
|
已批准的 PR |
|
|
需要修改的 PR |
|
|
草稿 PR |
|
|
按目标分支 |
|
|
按源分支 |
|
|
按合并时间 |
|
6. 故障排查速查#
问题 |
排查命令 |
解决方案 |
|---|---|---|
认证失败 |
|
重新登录： |
Token 权限不足 |
|
刷新 Token： |
找不到仓库 |
|
检查仓库名拼写，确认有访问权限 |
PR 无法合并 |
|
确认 CI 通过且审查满足要求 |
CI 运行失败 |
|
查看失败日志定位原因 |
网络超时 |
|
配置 HTTP 代理 |
Fork 仓库过期 |
|
同步上游更新 |
命令无响应 |
|
开启调试模式查看 API 请求 |
7. 相关资源#
概述 — 教程总览与架构图
安装与配置指南 — 环境搭建与认证
基础命令指南 — 仓库/Issue/Gist 核心操作
Pull Request 工作流指南 — PR 全生命周期管理
GitHub CLI 官方手册 — 完整命令参考
GitHub CLI 仓库 — 源代码与 Issue 追踪