gh

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Reference

参考指南

Interactivity policy

交互性策略

gh

already does the right thing in non-TTY contexts: it skips the pager, strips ANSI color, and errors out fast with a helpful message instead of prompting (e.g.

must provide --title and --body when not running interactively

). You don't need to defensively set

GH_PAGER

or pass

--no-pager

(no such flag exists).

gh

在非TTY环境下已具备正确的处理逻辑：它会跳过分页器、去除ANSI颜色，并且快速抛出实用的错误信息而非等待输入（例如

must provide --title and --body when not running interactively

）。你无需主动设置

GH_PAGER

或传递

--no-pager

（该标志不存在）。

Parsing JSON

解析JSON

Human output from

gh

is column-formatted. If you want structured data:

Add
```
--json field1,field2,...
```
for structured output.
Run a command with
```
--json
```
and no field list to print the full set of available fields, then pick what you need.
Use
```
--jq '<expr>'
```
for filtering without piping through a separate
```
jq
```
.
Use
```
--template '<go-template>'
```
(alongside
```
--json
```
) when you want shaped text output. Note that
```
--template
```
/
```
-T
```
collides with a body-template flag on a few commands (e.g.
```
gh pr create -T
```
,
```
gh issue create -T
```
); always check
```
--help
```
before assuming which one you're hitting.

gh

的人类可读输出为列格式。若你需要结构化数据：

添加
```
--json field1,field2,...
```
以获取结构化输出。
运行带
```
--json
```
但不指定字段列表的命令，打印所有可用字段后再选择所需内容。
使用
```
--jq '<expr>'
```
进行过滤，无需通过单独的
```
jq
```
工具管道处理。
当你需要自定义文本输出时，结合
```
--json
```
使用
```
--template '<go-template>'
```
（Go模板）。注意
```
--template
```
/
```
-T
```
与部分命令的正文模板标志冲突（例如
```
gh pr create -T
```
、
```
gh issue create -T
```
）；使用前务必查看
```
--help
```
确认你使用的是哪个标志。

Pagination and silent truncation

分页与静默截断

List commands cap results.

gh issue list

gh pr list

gh search ...

: pass

-L N

(

--limit N

). The default is usually 30.

```
gh issue list
```
/
```
gh pr list
```
do not expose aggregate totals like
```
totalCount
```
via
```
--json
```
. If you need a true total, use
```
gh api graphql
```
to query
```
totalCount
```
; otherwise, treat
```
-L
```
as the cap for the current call.
For raw API calls use
```
gh api --paginate <path>
```
. Combine with
```
--jq
```
and (optionally)
```
--slurp
```
to assemble one array.

列表类命令会限制结果数量。

```
gh issue list
```
、
```
gh pr list
```
、
```
gh search ...
```
：传递
```
-L N
```
（
```
--limit N
```
）参数。默认值通常为30。
```
gh issue list
```
/
```
gh pr list
```
无法通过
```
--json
```
暴露
```
totalCount
```
这类聚合统计值。若你需要真实总数，使用
```
gh api graphql
```
查询
```
totalCount
```
；否则，将
```
-L
```
视为当前调用的结果上限。
对于原始API调用，使用
```
gh api --paginate <path>
```
。结合
```
--jq
```
和（可选）
```
--slurp
```
来合并为一个数组。

Repo targeting

仓库定位

gh

infers the repo from the cwd's git remotes.

Pass

--repo OWNER/REPO

(

-R

) to override the resolved CWD repo.

gh

会从当前工作目录的git远程仓库推断目标仓库。

传递

--repo OWNER/REPO

（

-R

）参数可覆盖当前工作目录解析出的仓库。

Search vs list

搜索与列表的区别

```
gh search issues|prs|code|repos|commits|users
```
uses GitHub's search index and accepts the full search syntax (
```
is:open
```
,
```
author:
```
,
```
label:
```
,
```
repo:owner/name
```
,
```
in:title
```
, ...). Pass each qualifier as its own bare token, not as one quoted string:
```
gh search issues repo:cli/cli is:open author:monalisa
```
works, but
```
gh search issues "repo:cli/cli is:open"
```
is treated as a single keyword (parsed as
```
repo:"cli/cli is:open"
```
) and fails with
```
Invalid search query
```
. Quote only multi-word free text (
```
gh search issues "broken feature"
```
). Most qualifiers also have a dedicated flag (
```
--repo
```
,
```
--author
```
,
```
--label
```
, ...). Prefer search for anything cross-repo or filtered by author/label.
```
gh issue list --search "..."
```
and
```
gh pr list --search "..."
```
take the query as one quoted string (it is a flag value) and are scoped to one repo.

Bots author as GitHub Apps, so

--author dependabot

matches nothing. Use

--app dependabot

(on

pr

issue list

and

search prs|issues

; expands to

author:app/<slug>

) or

--author "dependabot[bot]"

```
gh search issues|prs|code|repos|commits|users
```
使用GitHub的搜索索引，支持完整的搜索语法（
```
is:open
```
、
```
author:
```
、
```
label:
```
、
```
repo:owner/name
```
、
```
in:title
```
等）。每个限定符需作为独立的裸令牌传递，而非单个引号字符串：
```
gh search issues repo:cli/cli is:open author:monalisa
```
是有效的，但
```
gh search issues "repo:cli/cli is:open"
```
会被视为单个关键词（解析为
```
repo:"cli/cli is:open"
```
），并抛出
```
Invalid search query
```
错误。仅对多词自由文本使用引号包裹（例如
```
gh search issues "broken feature"
```
）。大多数限定符也有专用标志（
```
--repo
```
、
```
--author
```
、
```
--label
```
等）。跨仓库或按作者/标签过滤的场景优先使用搜索功能。
```
gh issue list --search "..."
```
和
```
gh pr list --search "..."
```
将查询内容作为单个引号字符串传递（作为标志值），且作用范围限定为单个仓库。
机器人以GitHub应用身份创建内容，因此
```
--author dependabot
```
无法匹配任何结果。使用
```
--app dependabot
```
（适用于
```
pr
```
/
```
issue list
```
和
```
search prs|issues
```
；会扩展为
```
author:app/<slug>
```
）或
```
--author "dependabot[bot]"
```
。

Issue types, sub-issues, and relationships

议题类型、子议题与关联关系

Newer

gh issue

subcommands model issue types, sub-issue hierarchy, and blocked-by/blocking relationships.

gh issue create

--type <name>

--parent <number|url>

(creates the new issue as a sub-issue),

--blocked-by <number|url,...>

--blocking <number|url,...>

```
gh issue edit
```
(edits one or more issues in the same repo, e.g.
```
gh issue edit 23 34
```
):
```
--type <name>
```
/
```
--remove-type
```
,
```
--parent <n|url>
```
/
```
--remove-parent
```
,
```
--add-sub-issue <n,n>
```
/
```
--remove-sub-issue <n,n>
```
,
```
--add-blocked-by <n,n>
```
/
```
--remove-blocked-by <n,n>
```
,
```
--add-blocking <n,n>
```
/
```
--remove-blocking <n,n>
```
. Relationship and parent refs are issue numbers or URLs; a URL may point to another repo on the same host, but a different host is rejected.
```
--add-sub-issue
```
cannot be used when editing more than one issue.
```
gh issue list --type <name>
```
filters by issue type.
```
gh issue view
```
and
```
gh issue list
```
accept these as
```
--json
```
fields (prefer them over scraping the default text output):
```
issueType
```
,
```
parent
```
,
```
subIssues
```
,
```
subIssuesSummary
```
,
```
blockedBy
```
,
```
blocking
```
.
```
subIssues
```
,
```
blockedBy
```
, and
```
blocking
```
are objects shaped
```
{"nodes": [...], "totalCount": N}
```
(not flat arrays), and
```
nodes
```
is capped (
```
subIssues
```
at 100,
```
blockedBy
```
/
```
blocking
```
at 50), so compare the node count against
```
totalCount
```
to detect truncation.
GHES: issue types and sub-issues need 3.17+; blocked-by/blocking relationships need 3.19+.

较新的

gh issue

子命令支持议题类型、子议题层级以及被阻塞/阻塞关联关系的管理。

gh issue create

：

--type <name>

、

--parent <number|url>

（将新议题创建为子议题）、

--blocked-by <number|url,...>

、

--blocking <number|url,...>

。

```
gh issue edit
```
（可编辑同一仓库中的一个或多个议题，例如
```
gh issue edit 23 34
```
）：
```
--type <name>
```
/
```
--remove-type
```
、
```
--parent <n|url>
```
/
```
--remove-parent
```
、
```
--add-sub-issue <n,n>
```
/
```
--remove-sub-issue <n,n>
```
、
```
--add-blocked-by <n,n>
```
/
```
--remove-blocked-by <n,n>
```
、
```
--add-blocking <n,n>
```
/
```
--remove-blocking <n,n>
```
。关联关系和父议题引用可以是议题编号或URL；URL可指向同一主机上的其他仓库，但不同主机的URL会被拒绝。编辑多个议题时无法使用
```
--add-sub-issue
```
。
```
gh issue list --type <name>
```
按议题类型过滤结果。
```
gh issue view
```
和
```
gh issue list
```
支持将以下内容作为
```
--json
```
字段（优先使用这些字段而非解析默认文本输出）：
```
issueType
```
、
```
parent
```
、
```
subIssues
```
、
```
subIssuesSummary
```
、
```
blockedBy
```
、
```
blocking
```
。
```
subIssues
```
、
```
blockedBy
```
和
```
blocking
```
是结构为
```
{"nodes": [...], "totalCount": N}
```
的对象（非扁平数组），且
```
nodes
```
有数量限制（
```
subIssues
```
上限为100，
```
blockedBy
```
/
```
blocking
```
上限为50），因此需将节点数量与
```
totalCount
```
对比以检测截断情况。
GHES：议题类型和子议题功能需要3.17+版本；被阻塞/阻塞关联关系需要3.19+版本。

Discussions (

gh discussion

)

讨论功能（

gh discussion

）

Preview command set, subject to change. Subcommands:

gh discussion list [--state open|closed|all] [--category <name>] [--author <handle>] [--label <name>,...] [--answered] [--search <query>] [--sort created|updated] [--order asc|desc] [--limit N] [--after <cursor>] [--json <fields>] [--web]

lists a repo's discussions.

--state

defaults to open,

--sort

to updated,

--order

to desc.

--answered

is tri-state (

--answered=false

for unanswered) for Q&A categories.

```
gh discussion view {<number>|<url>|<comment-id>|<comment-url>} [--comments] [--order oldest|newest] [--limit N] [--after <cursor>] [--json <fields>] [--web]
```
shows a discussion's body; add
```
--comments
```
for its comments, or pass a comment ID/URL as the argument to list that comment's replies (no
```
--replies
```
flag;
```
--comments
```
is rejected with a comment argument).
```
--order
```
(default newest),
```
--limit
```
, and
```
--after
```
apply only to comment and reply listings.

gh discussion create [--title <t>] [--body <b> | --body-file <path>] [--category <name>] [--label <name>,...]

creates a discussion.

--title

, a body (

--body

--body-file

), and

--category

are required non-interactively; omitting any will prompt on a terminal.

gh discussion edit {<number>|<url>} [--title <t>] [--body <b>] [--body-file <path>] [--category <name>] [--add-label <name>,...] [--remove-label <name>,...]

edits title, body, category, or labels.

```
gh discussion comment {<number>|<discussion-url>|<comment-id>|<comment-url>} [--body <b>] [--body-file <path>] [--edit] [--delete] [--yes]
```
adds a top-level comment (when given a discussion) or a reply (when given a comment);
```
--edit
```
or
```
--delete
```
updates or removes a comment/reply and needs a comment ID or URL.
```
--yes
```
skips the
```
--delete
```
confirmation.
```
--json
```
/
```
--jq
```
/
```
--template
```
are available on
```
list
```
and
```
view
```
only;
```
create
```
and
```
edit
```
print the discussion URL.
```
comment
```
prints the discussion comment (or reply) URL.

预览版命令集，可能会发生变更。子命令包括：

gh discussion list [--state open|closed|all] [--category <name>] [--author <handle>] [--label <name>,...] [--answered] [--search <query>] [--sort created|updated] [--order asc|desc] [--limit N] [--after <cursor>] [--json <fields>] [--web]

列出仓库的讨论内容。

--state

默认值为open，

--sort

默认值为updated，

--order

默认值为desc。

--answered

为三态值（

--answered=false

表示未回答），适用于问答类分类。

```
gh discussion view {<number>|<url>|<comment-id>|<comment-url>} [--comments] [--order oldest|newest] [--limit N] [--after <cursor>] [--json <fields>] [--web]
```
显示讨论的正文；添加
```
--comments
```
参数可查看评论，或传递评论ID/URL作为参数以列出该评论的回复（无
```
--replies
```
标志；传递评论参数时使用
```
--comments
```
会被拒绝）。
```
--order
```
（默认值为newest）、
```
--limit
```
和
```
--after
```
仅适用于评论和回复列表。

gh discussion create [--title <t>] [--body <b> | --body-file <path>] [--category <name>] [--label <name>,...]

创建讨论内容。非交互式场景下必须提供

--title

、正文（

--body

或

--body-file

）和

--category

；省略任何一项都会在终端中触发输入提示。

gh discussion edit {<number>|<url>} [--title <t>] [--body <b>] [--body-file <path>] [--category <name>] [--add-label <name>,...] [--remove-label <name>,...]

编辑讨论的标题、正文、分类或标签。

```
gh discussion comment {<number>|<discussion-url>|<comment-id>|<comment-url>} [--body <b>] [--body-file <path>] [--edit] [--delete] [--yes]
```
添加顶级评论（传递讨论对象时）或回复（传递评论对象时）；
```
--edit
```
或
```
--delete
```
用于更新或删除评论/回复，且需要评论ID或URL。
```
--yes
```
参数可跳过
```
--delete
```
的确认步骤。
```
--json
```
/
```
--jq
```
/
```
--template
```
仅在
```
list
```
和
```
view
```
命令中可用；
```
create
```
和
```
edit
```
命令会打印讨论的URL。
```
comment
```
命令会打印讨论评论（或回复）的URL。

Reading files and directories (

gh repo read-file

read-dir

)

读取文件与目录（

gh repo read-file

read-dir

）

Preview commands, subject to change. They read a repo's contents over the API without cloning, and honor

--repo OWNER/REPO

(

-R

) and

--ref <branch|tag|commit>

(default branch when omitted).

```
gh repo read-file <path> [--ref <ref>] [--output <path> [--clobber]] [--allow-escape-sequences] [--json <fields>] [--jq <expr>]
```
prints a file's contents. In non-TTY contexts the raw bytes go straight to stdout (pipe-friendly); binary files are written as-is when piped but are refused on a TTY. By default, a file containing terminal escape sequences is refused; pass
```
--allow-escape-sequences
```
to read it anyway.
```
--output <path>
```
(
```
-o
```
) writes to disk instead of stdout (a trailing slash writes under a directory using the remote file name;
```
--clobber
```
allows overwrite); writing to disk always includes the raw bytes regardless of escape sequences.
```
--output
```
and
```
--json
```
are mutually exclusive.
```
--json
```
fields include
```
name
```
,
```
path
```
,
```
gitSHA
```
,
```
size
```
,
```
type
```
,
```
encoding
```
, and
```
content
```
(base64 encoded).
```
gh repo read-dir [<path>] [--ref <ref>] [--json <fields>] [--jq <expr>]
```
lists a directory; with no path it lists the repo root. Non-TTY output is tab separated as type, name, octal mode, and byte size.
```
--json
```
fields include
```
name
```
,
```
path
```
,
```
type
```
,
```
gitType
```
,
```
mode
```
,
```
modeOctal
```
,
```
gitSHA
```
,
```
size
```
, and
```
submodule
```
. A path pointing at a file errors and points you at
```
read-file
```
(and vice versa).

预览版命令，可能会发生变更。这些命令通过API读取仓库内容，无需克隆仓库，且支持

--repo OWNER/REPO

（

-R

）和

--ref <branch|tag|commit>

（省略时默认使用默认分支）参数。

```
gh repo read-file <path> [--ref <ref>] [--output <path> [--clobber]] [--allow-escape-sequences] [--json <fields>] [--jq <expr>]
```
打印文件内容。在非TTY环境下，原始字节会直接输出到标准输出（便于管道处理）；二进制文件在管道传输时会按原样写入，但在TTY环境下会被拒绝读取。默认情况下，包含终端转义序列的文件会被拒绝读取；传递
```
--allow-escape-sequences
```
参数可强制读取。
```
--output <path>
```
（
```
-o
```
）参数可将内容写入磁盘而非标准输出（路径末尾带斜杠时会将文件写入指定目录下，使用远程文件名；
```
--clobber
```
参数允许覆盖已存在的文件）；写入磁盘时始终包含原始字节，不受转义序列影响。
```
--output
```
和
```
--json
```
参数互斥。
```
--json
```
支持的字段包括
```
name
```
、
```
path
```
、
```
gitSHA
```
、
```
size
```
、
```
type
```
、
```
encoding
```
和
```
content
```
（base64编码）。
```
gh repo read-dir [<path>] [--ref <ref>] [--json <fields>] [--jq <expr>]
```
列出目录内容；不指定路径时列出仓库根目录。非TTY环境下的输出以制表符分隔，包含类型、名称、八进制权限和字节大小。
```
--json
```
支持的字段包括
```
name
```
、
```
path
```
、
```
type
```
、
```
gitType
```
、
```
mode
```
、
```
modeOctal
```
、
```
gitSHA
```
、
```
size
```
和
```
submodule
```
。若指定的路径指向文件，命令会报错并引导你使用
```
read-file
```
（反之亦然）。

Fall back to

gh api

for anything

--json

doesn't expose

对于

--json

未暴露的数据，降级使用

gh api

Sometimes useful data isn't on the typed commands. Examples:

Review-thread comments on a PR:
```
gh api repos/{owner}/{repo}/pulls/{n}/comments
```
(the
```
--comments
```
flag on
```
gh pr view
```
shows issue-level comments only).

Arbitrary GraphQL:

gh api graphql -f query='...' -F var=value

REST shortcuts:
```
gh api repos/{owner}/{repo}/...
```
- note the
```
{owner}/{repo}
```
placeholder is filled in for you when run from a repo with detected remotes; pass them literally if you want determinism.

有时有用的数据无法通过类型化命令获取。例如：

PR上的评审线程评论：
```
gh api repos/{owner}/{repo}/pulls/{n}/comments
```
（
```
gh pr view
```
的
```
--comments
```
标志仅显示议题级别的评论）。

任意GraphQL查询：

gh api graphql -f query='...' -F var=value

。

REST快捷方式：
```
gh api repos/{owner}/{repo}/...
```
- 注意
```
{owner}/{repo}
```
占位符会在从已检测到远程仓库的目录运行时自动填充；若需要确定性结果，请直接传递字面量。

Authentication

身份验证

```
gh auth status
```
prints the active host(s), user, and which env var (if any) is being honored.
```
gh auth status --json
```
is supported.

```
gh auth status
```
会打印当前活跃的主机、用户以及正在使用的环境变量（如有）。
```
gh auth status --json
```
参数已被支持。

Other notes

其他注意事项

```
gh pr checkout <n>
```
switches branches. Use
```
gh pr diff <n>
```
or
```
gh pr view <n>
```
if you only need to read.
```
gh pr checkout <n> --worktree <path>
```
checks the PR out into a git worktree at
```
<path>
```
instead of switching the current branch.
```
NO_COLOR
```
,
```
CLICOLOR_FORCE
```
, and
```
GH_FORCE_TTY
```
are honored. Set
```
GH_FORCE_TTY=1
```
if you want TTY-style output (colors, tables, the pager, interactivity) inside an agent harness; leave it unset unless needed.

```
gh pr checkout <n>
```
会切换分支。若你仅需查看内容，使用
```
gh pr diff <n>
```
或
```
gh pr view <n>
```
。
```
gh pr checkout <n> --worktree <path>
```
会将PR检出到
```
<path>
```
路径下的git工作区，而非切换当前分支。
```
NO_COLOR
```
、
```
CLICOLOR_FORCE
```
和
```
GH_FORCE_TTY
```
环境变量会被识别。若你希望在Agent环境中获得TTY风格的输出（颜色、表格、分页器、交互性），设置
```
GH_FORCE_TTY=1
```
；无需时请勿设置。

gh

Original

Translation

Reference

参考指南

Interactivity policy

交互性策略

Parsing JSON

解析JSON

Pagination and silent truncation

分页与静默截断

Repo targeting

仓库定位

Search vs list

搜索与列表的区别

Issue types, sub-issues, and relationships

议题类型、子议题与关联关系

Discussions (
`gh discussion`
)

讨论功能（
`gh discussion`
）

Reading files and directories (
`gh repo read-file`
/
`read-dir`
)

读取文件与目录（
`gh repo read-file`
/
`read-dir`
）

Fall back to
`gh api`
for anything
`--json`
doesn't expose

对于
`--json`
未暴露的数据，降级使用
`gh api`

Authentication

身份验证

Other notes

其他注意事项

gh

Original

Translation

Reference

参考指南

Interactivity policy

交互性策略

Parsing JSON

解析JSON

Pagination and silent truncation

分页与静默截断

Repo targeting

仓库定位

Search vs list

搜索与列表的区别

Issue types, sub-issues, and relationships

议题类型、子议题与关联关系

Discussions (gh discussion)

讨论功能（gh discussion）

Reading files and directories (gh repo read-file / read-dir)

读取文件与目录（gh repo read-file / read-dir）

Fall back to gh api for anything --json doesn't expose

对于--json未暴露的数据，降级使用gh api

Authentication

身份验证

Other notes

其他注意事项

Discussions (
`gh discussion`
)

讨论功能（
`gh discussion`
）

Reading files and directories (
`gh repo read-file`
/
`read-dir`
)

读取文件与目录（
`gh repo read-file`
/
`read-dir`
）

Fall back to
`gh api`
for anything
`--json`
doesn't expose

对于
`--json`
未暴露的数据，降级使用
`gh api`