はじめに
以前から気になっていたgh cliを触ってみただけの記事です。
私と同じく、気になっているけどまだ触ったことない方へ参考になれば幸いです。
公式ドキュメントが読みやすくまとまっているのですが、その中で個人的に使えそうなものをまとめました。
GitHub CLI | Take GitHub to the command line
GitHub CLIとは
GitHub公式のOSS (オープンソースソフトウェア)です。
以下、公式ブログから引用します。
GitHub CLI とは、利用しているターミナルでGitHubを使用できるようにするものです。コンテキストの切り替え回数が減るため、これまで以上に作業そのものに集中でき、スクリプトの記述や独自のワークフローの作成が、さらに簡素化されます。
引用：GitHub CLI 1.0をリリース - GitHubブログ
利点としては、「画面ポチポチする作業をコマンドで解決する」という一般的なものだと思います。
例えば、
- コンテキストの切り替え回数が減る1ので楽になる
- 作業をコード化できる
- 似た作業を素早く行える
- 作業フローを振り返りやすくなる
- 作業を自動化しやすくなる
とかだと思います。
本題
インストールと認証
Manual | GitHub CLI の通り行いました。
インストールはこちらから
cli/cli: GitHub's official command line tool
インストールできたら以下のコマンドを実行します。
gh auth login
詳細は多くの記事で紹介されているので割愛させていただきます。
GitHub CLI を使ってみた | DevelopersIO
GitHub CLI 2.0でIssue周りの操作を試してみた | DevelopersIO
そのまま使えそうなコマンド
gh issue list # イシューを一覧取得する(最新30件)
gh pr list # プルリクエストを一覧表示する(最新30件)
gh pr diff # プルリクエストの差分確認
gh pr checkout 1 # プルリクエスト#1の状態をチェックアウトする
gh pr view # 現在のブランチに対するプルリクエストを表示する
プルリクエストをローカルでチェック アウトする
gh pr checkout {<number> | <url> | <branch>}
例えば、プルリクエストの番号を確認してコマンドを打つだけで、ローカルへチェックアウトできます。
ブランチを確認して、切り替えるという作業を一発で行えそうな気がします。
参考： gh pr checkout | GitHub CLI
リポジトリ間でラベルをクローンする
gh label clone <repository>
現在のリポジトリに対して、指定したリポジトリのラベルをクローンできます。
同名ラベルがあるとスキップされます。
上書きしたい場合は、-fオプションを使います。
Labels from the source repository that already exist in the destination repository will be skipped. You can overwrite existing labels in the destination repository using the --force flag.
gh label clone | GitHub CLI
エイリアスを貼って使いたいコマンド
gh aliasでエイリアスを作成・一覧・削除できるので活用しましょう。
（以下は公式の例を引用してます）
# 自分に割り当てられたイシューを一覧表示する
gh issue list --assignee @me
# エイリアスを作成する
gh alias set homework 'issue list --assignee @me'
# 使用例
gh homework
# 設定したエイリアスを一覧表示する
gh alias list
# 設定したエイリアス'homework'を削除する
gh alias delete homework
イシュー本文中にキーワードを含むものを一覧表示する
# イシュー本文中に「hoge」を含むものを一覧表示する
gh issue list -S hoge
# エイリアスを作成する
gh alias set --shell isearch 'gh issue list -S "$1"'
# 使用例
gh isearch hoge
ラベルに紐づいたイシューを確認する
# bugsラベルのイシューを一覧表示する
gh issue list --label=bugs
# エイリアスを作成する
gh alias set bugs 'issue list --label=bugs'
# 使用例
gh bugs
↓ ラベルを引数で渡す形にしました
# bugsラベルのイシューを一覧表示する
gh issue list --label=bugs
# エイリアスを作成する
gh alias set --shell iwith 'gh issue list --label="$1"'
# 使用例
gh iwith bugs
--shell: エイリアスに引数を設定する
ブラウザで新規プルリクエストを作成する
# ブラウザでプルリクエストを作成する
gh pr create -w
# エイリアスを作成する
gh alias set propen 'pr create -w'
# 使用例
gh propen
-w: ブラウザで開く
pushした後に便利だと思います。
コマンドラインだけでもプルリクエストを作成できますが、ここはお好みで・・
Githubのリモートブランチを一覧表示する
# Githubのリモートブランチを一覧表示する
gh api -H "Accept: application/vnd.github.v3+json" repos/{owner}/{repo}/branches --jq ".[].name" --paginate
# エイリアスを作成する
gh alias set branch 'api -H "Accept: application/vnd.github.v3+json" repos/{owner}/{repo}/branches --jq ".[].name" --paginate'
# 使用例
gh branch
-
gh api: GitHub API(v3)を利用する-
-H: リクエストヘッダを指定する-
"Accept: application/vnd.github.v3+json": AcceptヘッダにGitHub API v3のjsonを指定する (参考: メディアタイプ - GitHub Docs)
-
-
--jq: レスポンスをjq形式に整形する -
--paginate: レスポンス結果がなくなるまでリクエストする -
{owner}、{repo}: 現在のユーザー、リポジトリが反映される（PowerShellなどは{}の解釈で競合するので注意らしいです）
Placeholder values "{owner}", "{repo}", and "{branch}" in the endpoint argument will get replaced with values from the repository of the current directory or the repository specified in the GH_REPO environment variable. Note that in some shells, for example PowerShell, you may need to enclose any value that contains "{...}" in quotes to prevent the shell from applying special meaning to curly braces.
引用：gh api | GitHub CLI -
参考：
gh api | GitHub CLI
ブランチ - GitHub Docs
プルリクエストの変更ファイルを一覧表示する
# プルリクエストの変更ファイルを一覧表示する
gh api -H "Accept: application/vnd.github.v3+json" repos/{owner}/{repo}/pulls/{pull_number}/files --paginate --jq '.[].filename'
# エイリアスを作成する
gh alias set --shell prfiles 'gh api -H "Accept: application/vnd.github.v3+json" repos/{owner}/{repo}/pulls/"$1"/files --paginate --jq ".[].filename"'
# 使用例
gh pr list
gh prfiles 1
役立つ場面は滅多にないかもしれません。。
プルリクエストのリンクを取得する
メモ・報告用です。
# プルリクエスト(#1)のリンクを取得する
gh pr view 1 --json number,title,url -q "\"[#\" + (.number|tostring) + \" \" + .title + \"](\" + .url + \")\""
# エイリアスを作成する(クリップボードへ保存するコマンドを加えてます)
gh alias set --shell pclip \
'gh pr view "$1" --json number,title,url -q "\"[#\" + (.number|tostring) + \" \" + .title + \"](\" + .url + \")\"" | pbcopy'
# 使用例
gh pr list
gh pclip 1
-qオプションでjq -rと同じようにjsonでなく文字列で出力できます。
The --jq option accepts a query in jq syntax and will print only the resulting values that match the query. This is equivalent to piping the output to jq -r, but does not require the jq utility to be installed on the system.
引用： gh formatting | GitHub CLI
参考： jq 1.6 Manual
クリップボードへ保存するコマンド
macOSの場合
pbcopy
Ubuntuの場合
xselをインストールして行う。
xsel --clipboard --input
Windows、WSLの場合
clip.exe
イシューのリンクを取得する
# イシュー(#1)のリンクを取得する
gh issue view 1 --json number,title,url --template "[#{{.number}} {{.title}}]({{.url}})"
# エイリアスを作成する(クリップボードへ保存するコマンドを加えてます)
gh alias set --shell iclip \
'gh issue view "$1" --json number,title,url --template "[#{{.number}} {{.title}}]({{.url}})" | pbcopy'
# 使用例
gh issue list
gh iclip 1
jqだけでなく、Go言語のテンプレート形式でも出力を整形できます。
With --template, the provided Go template is rendered using the JSON data as input.
引用： gh formatting | GitHub CLI
参考： template package - text/template - pkg.go.dev
実現できなかったこと
Github上で最新ブランチから新規リモートブランチを作成する
ローカルで作業ブランチを作成する前のfetch忘れを防ぐためです。
参考：リポジトリ内でブランチを作成および削除する - GitHub Docs
イシュー、プルリクエストの本文をVSCodeで編集する
とても些細なことですが、ブラウザ上だと編集しにくいからです。
(タブでインデントできない、慣れたショートカット使えない、etc...)
以下のようにvimは設定できますが、VSCodeは使えないようでした。
gh config set editor vim
（決してvimが嫌いなわけではないです。好きになっていきたいです。）
参考
GitHub CLIで始める快適GitHub生活 - Qiita
jqでjson以外の文字列を表示する | 瀬戸内の雲のように
bshでのクォーテーションの入れ子 | b.l0g.jp
おわりに
導入も使用方法も簡単なので、少しでも効率的にしたい方におすすめでした。
個人的には、コマンドで解決できることは理解して使っていけるようになりたいです。
gh apiを使えば、
GitHubのREST API - GitHub Docs
に載っている内容は大体実現できそうなことが分かったのでよかったです。
最後にgh cliの拡張機能を置いておきます。
gh-extension · GitHub Topics
どんどん便利になっていきそうですね！
-
例えば
(ターミナル → ブラウザ（GitHub）→ ターミナル → 他作業)
が
(ターミナル → 他作業)
になることだと思います。 ↩