关于 GitHub CLI 扩展
GitHub CLI 扩展是任何人都可以创建和使用的自定义 GitHub CLI 命令。 有关如何使用 GitHub CLI 扩展的详细信息,请参阅“使用 GitHub CLI 扩展”。
对于您创建的每个扩展,都需要一个存储库。 存储库名称必须以 gh-
开头。 存储库名称的其余部分是扩展的名称。 存储库的� �目录下必须有一个与存储库同名的可执行文件,或者附� 到发行版的一组预编译二进制可执行文件。
注意:当依赖于可执行脚本时,我们建议使用 bash 脚本,� 为 bash 是一个广泛使用的解译程序。 您可以使用非 bash 脚本,但用户必须安装必要的解译程序才能使用扩展。 如果您不希望依赖安装了解译程序的用户,请考虑使用预编译扩展。
使用 gh extension create
创建解译的扩展
注意:运行不带参数的 gh extension create
将启动交互式向导。
可以使用 gh extension create
命令为您的扩展创建一个项目,包括包含一些起始代� �的 bash 脚本。
-
使用
gh extension create
子命令设置新的扩展。 将EXTENSION-NAME
替换为扩展的名称。gh extension create EXTENSION-NAME
-
按照打印的说明完成扩展并选择性地发布扩展。
使用 gh extension create
创建预编译的扩展
可以使用 --precompiled=go
参数为扩展创建基于 Go 的项目,包括 Go 基架、工作流程基架和起始代� �。
-
使用
gh extension create
子命令设置新的扩展。 将EXTENSION-NAME
替换为扩展的名称,并指定--precompiled=go
。gh extension create --precompiled=go EXTENSION-NAME
-
按照打印的说明完成扩展并选择性地发布扩展。
使用 gh extension create
创建非 Go 预编译的扩展
可以使用 --precompiled=other
参数为非 Go 预编译扩展(包括工作流程基架)创建项目。
-
使用
gh extension create
子命令设置新的扩展。 将EXTENSION-NAME
替换为扩展名,并指定--precompiled=other
。gh extension create --precompiled=other EXTENSION-NAME
-
使用所选的编译语言为扩展添� 一些初始代� �。
-
在
script/build.sh
中填写代� �以生成扩展,以确保可以自动生成扩展。 -
按照打印的说明完成扩展并选择性地发布扩展。
手动创建解译的扩展
-
为扩展创建一个名为
gh-EXTENSION-NAME
的本地目录。 将EXTENSION-NAME
替换为扩展的名称。 例如,gh-whoami
。 -
在您创建的目录中,添� 与该目录同名的可执行文件。
注意: 请确保您的文件是可执行的。 在 Unix上,您可以在命令行中执行
chmod +x file_name
,以使file_name
可执行。 在 Windows上,您可以依次运行git init -b main
、git add file_name
和git update-index --chmod=+x file_name
。 -
在可执行文件中编写脚本。 例如:
#!/usr/bin/env bash set -e exec gh api user --jq '"You are @\(.login) (\(.name))."'
-
从目录中,将扩展安装为本地扩展。
gh extension install .
-
验证您的扩展是否正常工作。 将
EXTENSION-NAME
替换为扩展的名称。 例如whoami
。gh EXTENSION-NAME
-
从目录中,创建一个存储库以发布扩展。 将
EXTENSION-NAME
替换为扩展的名称。git init -b main git add . && git commit -m "initial commit" gh repo create gh-EXTENSION-NAME --source=. --public --push
-
(可选)为了帮助其他用户发现您的扩展,请添� 存储库主题
gh-extension
。 这将使扩展显示在gh-extension
主题页面上。 有关如何添� 存储库主题的更多信息,请参阅“使用主题对存储库进行分类”。
编写解译型 GitHub CLI 扩展的提示
处理参数和� �志
gh my-extension-name
命令之后的所有命令行参数都将� 递给扩展脚本。 在 bash 脚本中,您可以引用 $1
、$2
等参数。 可以使用参数来接受用户输入或修改脚本的行为。
例如,此脚本处理多个� �志。 当使用 -h
或 --help
� �志调用脚本时,脚本将打印帮助文本,而不是继续执行。 当使用 --name
� �志调用脚本时,脚本会将� �志后的下一个值设置为 name_arg
。 当使用 --verbose
� �志调用脚本时,脚本将打印不同的问候语。
#!/usr/bin/env bash
set -e
verbose=""
name_arg=""
while [ $# -gt 0 ]; do
case "$1" in
--verbose)
verbose=1
;;
--name)
name_arg="$2"
shift
;;
-h|--help)
echo "Add help text here."
exit 0
;;
esac
shift
done
if [ -z "$name_arg" ]
then
echo "You haven't told us your name."
elif [ -z "$verbose" ]
then
echo "Hi $name_arg"
else
echo "Hello and welcome, $name_arg"
fi
在非交互模式下调用� �心命令
某些 GitHub CLI � �心命令将提示用户输入。 使用这些命令编写脚本时,通常需要提示。 为避免提示,请通过参数显式提供必要的信息。
例如,要以编程方式创建问题,请指定� �题和正文:
gh issue create --title "My Title" --body "Issue description"
以编程方式获取数据
许多� �心命令支持 --json
� �志,用于以编程方式获取数据。 例如,要返回其中列出拉取请求数量、� �题和可合并性状态的 JSON 对象:
gh pr list --json number,title,mergeStateStatus
如果没有从 GitHub 获取特定数据的� �心命令,则可以使用 gh api
命令来访问 GitHub API。 例如,要获取有关当前用户的信息,
gh api user
所有输出 JSON 数据的命令还具有将该数据筛选为脚本可以立即使用的数据的选项。 例如,要获取当前用户的名称:
gh api user --jq '.name'
更多信息请参阅 gh help formatting
。
手动创建预编译的扩展
-
为扩展创建一个名为
gh-EXTENSION-NAME
的本地目录。 将EXTENSION-NAME
替换为扩展的名称。 例如,gh-whoami
。 -
在您创建的目录中,添� 一些源代� �。 例如:
package main import ( "github.com/cli/go-gh" "fmt" ) func main() { args := []string{"api", "user", "--jq", `"You are @\(.login) (\(.name))"` } stdOut, _, err := gh.Exec(args...) if err != nil { fmt.Println(err) return } fmt.Println(stdOut.String()) }
-
从目录中,将扩展安装为本地扩展。
gh extension install .
-
生成代� �。 例如,使用 Go,将
YOUR-USERNAME
替换为您的 GitHub 用户名:go mod init github.com/YOUR-USERNAME/gh-whoami go mod tidy go build
-
验证您的扩展是否正常工作。 将
EXTENSION-NAME
替换为扩展的名称。 例如whoami
。gh EXTENSION-NAME
-
从目录中,创建一个存储库以发布扩展。 将
EXTENSION-NAME
替换为扩展的名称。注意: 注意不要将编译步骤生成的二进制文件提交到版本控制中。
git init -b main echo "gh-EXTENSION-NAME" >> .gitignore git add main.go go.* .gitignore && git commit -m'Initial commit' gh repo create "gh-EXTENSION-NAME"
-
创建版本以与他人共享预编译的扩展。 针对要支持的每个平台进行编译,将每个二进制文件作为资产附� 到发行版。 附� 到发行版的二进制可执行文件必须遵循命名约定,并且具有 OS-ARCHITECTURE[EXTENSION] 的后缀。
例如,为 Windows 64 位编译的名为
whoami
的扩展将具有名称gh-whoami-windows-amd64.exe
,而为 Linux 32 位编译的同一扩展具有名称gh-whoami-linux-386
。 要查看gh
识别的操作系统和架构的详尽列表,请参阅此源代� �。注意:要使扩展在 Windows 上正常运行,其资产文件必须具有
.exe
扩展名。 其他操作系统不需要扩展。可以从命令行创建版本。 例如:
-
(可选)为了帮助其他用户发现您的扩展,请添� 存储库主题
gh-extension
。 这将使扩展显示在gh-extension
主题页面上。 有关如何添� 存储库主题的更多信息,请参阅“使用主题对存储库进行分类”。
编写预编译 GitHub CLI 扩展的提示
自动化发布
考虑将 gh-extension-precompiled 操作添� 到项目中的工作流程。 此操作将自动为您的扩展生成交叉编译的 Go 二进制文件,并为非 Go 预编译扩展提供构建基架。
使用基于 Go 的扩展中的 GitHub CLI 功能
考虑使用 go-gh,这是一个公开 gh
功能的 Go 库,用于扩展。
后续步骤
要查看 GitHub CLI 扩展的更多示例,请查看 具有 gh-extension
主题的存储库。