gh 格式化

默认情况下，gh 命令的结果以基于行的纯文本格式输出。某些命令支持传递 --json 标志，它将输出转换为 JSON 格式。一旦转换为 JSON，就可以通过添加 --jq 或 --template 标志，根据所需的格式字符串进一步格式化输出。这对于选择数据子集、创建新的数据结构、以不同格式显示数据或作为另一个命令行脚本的输入非常有用。

--json 标志需要一个逗号分隔的字段列表来获取。要查看命令的可能的 JSON 字段名，请在运行命令时省略 --json 标志的字符串参数。请注意，必须传递 --json 标志和字段名才能使用 --jq 或 --template 标志。

--jq 标志需要一个以 jq 查询语法表示的字符串参数，并且只打印与查询匹配的 JSON 值。jq 查询可用于从数组中选择元素，从对象中选择字段，创建新的数组等等。该系统不需要安装 jq 实用程序即可使用此格式化指令。当连接到终端时，输出会自动以漂亮格式打印。要了解 jq 查询语法，请参阅：https://jqlang.github.io/jq/manual/

--template 标志需要一个以 Go 模板语法表示的字符串参数，并且只打印与查询匹配的 JSON 值。除了标准库中的 Go 模板函数之外，以下函数也可以与此格式化指令一起使用

• autocolor: 类似于 color，但只向终端发出颜色
• color <style> <input>: 使用 https://github.com/mgutz/ansi 对输入进行着色
• join <sep> <list>: 使用分隔符连接列表中的值
• pluck <field> <list>: 收集输入中所有项的字段的值
• tablerow <fields>...: 将输出中的字段垂直对齐，作为表格
• tablerender: 在适当的位置渲染由 tablerow 添加的字段
• timeago <time>: 将时间戳渲染为相对于现在的值
• timefmt <format> <time>: 使用 Go 的 Time.Format 函数格式化时间戳
• truncate <length> <input>: 确保输入适合长度
• hyperlink <url> <text>: 渲染终端超链接

要了解有关 Go 模板的更多信息，请参阅：https://golang.ac.cn/pkg/text/template/.

示例

# default output format
$ gh pr list
Showing 23 of 23 open pull requests in cli/cli

#123  A helpful contribution          contribution-branch              about 1 day ago
#124  Improve the docs                docs-branch                      about 2 days ago
#125  An exciting new feature         feature-branch                   about 2 days ago


# adding the --json flag with a list of field names
$ gh pr list --json number,title,author
[
  {
	"author": {
	  "login": "monalisa"
	},
	"number": 123,
	"title": "A helpful contribution"
  },
  {
	"author": {
	  "login": "codercat"
	},
	"number": 124,
	"title": "Improve the docs"
  },
  {
	"author": {
	  "login": "cli-maintainer"
	},
	"number": 125,
	"title": "An exciting new feature"
  }
]


# adding the --jq flag and selecting fields from the array
$ gh pr list --json author --jq '.[].author.login'
monalisa
codercat
cli-maintainer

# --jq can be used to implement more complex filtering and output changes:
$ gh issue list --json number,title,labels --jq \
  'map(select((.labels | length) > 0))    # must have labels
  | map(.labels = (.labels | map(.name))) # show only the label names
  | .[:3]                                 # select the first 3 results'
  [
	{
	  "labels": [
		"enhancement",
		"needs triage"
	  ],
	  "number": 123,
	  "title": "A helpful contribution"
	},
	{
	  "labels": [
		"help wanted",
		"docs",
		"good first issue"
	  ],
	  "number": 125,
	  "title": "Improve the docs"
	},
	{
	  "labels": [
		"enhancement",
	  ],
	  "number": 7221,
	  "title": "An exciting new feature"
	}
  ]
  
# using the --template flag with the hyperlink helper
gh issue list --json title,url --template '{{range .}}{{hyperlink .url .title}}{{"\n"}}{{end}}'


# adding the --template flag and modifying the display format
$ gh pr list --json number,title,headRefName,updatedAt --template \
	'{{range .}}{{tablerow (printf "#%v" .number | autocolor "green") .title .headRefName (timeago .updatedAt)}}{{end}}'

#123  A helpful contribution      contribution-branch       about 1 day ago
#124  Improve the docs            docs-branch               about 2 days ago
#125  An exciting new feature     feature-branch            about 2 days ago


# a more complex example with the --template flag which formats a pull request using multiple tables with headers:
$ gh pr view 3519 --json number,title,body,reviews,assignees --template \
'{{printf "#%v" .number}} {{.title}}

{{.body}}

{{tablerow "ASSIGNEE" "NAME"}}{{range .assignees}}{{tablerow .login .name}}{{end}}{{tablerender}}
{{tablerow "REVIEWER" "STATE" "COMMENT"}}{{range .reviews}}{{tablerow .author.login .state .body}}{{end}}
'

#3519 Add table and helper template functions

Resolves #3488

ASSIGNEE  NAME
mislav    Mislav Marohnić


REVIEWER  STATE              COMMENT
mislav    COMMENTED          This is going along great! Thanks for working on this ❤️

另请参阅

• gh