Githubは幾つかの機能をCLIから利用できるように、Github CLIというツールを提供している。Emacsは外部の機能と強調する事を前提としている節があるため、こういう機能があるとEmacs自身にとても組み込みやすく高感度が高い。今回は、Github CLIを使ってみる。
Github Issue
Github Issueはバグトラッカーやチケットといった機能を提供する。課題管理などを行う事を想定している。私が関わっているプロジェクトでは、何故かGithub Issueを使わない事が多い1。とはいえしばしばGithub Issueを扱う機会はある。
Github CLIでは gh issue コマンドによって、Github Issueを操作する事ができる。直感的なサブコマンドとして実装されているので、使い方はUsageを見ればある程度把握できる。ここでUsageを掲載しておく。
Work with GitHub issues. USAGE gh issue <command> [flags] GENERAL COMMANDS create: Create a new issue list: List issues in a repository status: Show status of relevant issues TARGETED COMMANDS close: Close issue comment: Add a comment to an issue delete: Delete issue develop: Manage linked branches for an issue edit: Edit issues lock: Lock issue conversation pin: Pin a issue reopen: Reopen issue transfer: Transfer issue to another repository unlock: Unlock issue conversation unpin: Unpin a issue view: View an issue FLAGS -R, --repo [HOST/]OWNER/REPO Select another repository using the [HOST/]OWNER/REPO format INHERITED FLAGS --help Show help for command ARGUMENTS An issue can be supplied as argument in any of the following formats: - by number, e.g. "123"; or - by URL, e.g. "https://github.com/OWNER/REPO/issues/123". EXAMPLES $ gh issue list $ gh issue create --label bug $ gh issue view 123 --web LEARN MORE Use 'gh <command> <subcommand> --help' for more information about a command. Read the manual at https://cli.github.com/manual
Issueを作る
gh issue create コマンドを使い Issue を作成する。詳しい説明はUsageを見れば分かると思うが、ここでは掲載しない。
gh issue create --title "日本語を受け付けるかテストする" --body "こんにちわ"https://github.com/TakesxiSximada/example/issues/1
issueが正常に作成できた。成功するとissueのURLが標準出力に表示される。
Issueを更新する
先程作成した作成済みのissueのタイトルや概要を変更する。変更には gh issue edit を使用する。引数として指定している 1 はIssueの番号だが、URLでも良い。
gh issue edit 1 --title "issueの更新をテストする"概要は幾つかの方法で指定できる。 --body (又は -b) オプションの引数として指定することができる。ところで、この --body に改行文字が含まれている場合はどうなるのか確認する事にした。
gh issue edit 1 --body "tes\nting"これを実行すると、コマンドが失敗する事はなかったが、概要の文中に改行を含める場合、 \n のような文字を設定するとバックスラッシュ自体もエスケープ処理されて本文中に表示される事になった。もしかしたら改行させる方法はあるのかもしれないけれど見付けられなかった。
改行文字を含んだり長文を書いたりする場合は、一度ファイルとして書き出し --body-file (又は -F )の引数に書き出したファイルへのパスを指定する方法が良さそうだった。
gh issue edit 1 --body-file text.mdhelpによると --body-file に - を指定すると、標準入力からデータを読み取る。
gh issue edit 1 --body-file - < text.mdこのいずれかの方法で、概要の更新ができる。
コメントする
gh issue edit ではタイトルと概要(Description)の部分を更新できるが、コメントは付けることができない。コメントを付けるためには gh issue comment コマンドを使う。コメントも概要と同様に --body と --body-file を提供しており、そこにコメントを指定する。
gh issue comment 1 --body "こんにちわ"コメントを見る
コメントを取得するには gh issue view を使う。
gh issue view 1 -cghコマンドは制御文字をを出力し、自分自身で出力に色を付けようとする。最近のコマンドの流行りなのか、このようなコマンドをよく見かける。このような出力の制御は、無効化した状態が初期値であってほしい。 ls などのコマンドもそうなっている。 gh は有効状態が初期値となっていて、無効化する機能を見付ける事ができなかった。
Issueを閉じる
Issueは、作業が完了したり却下したりすると役目を終える。役目を終えたIssueは閉じる事ができる。issueを閉じるには gh issue close を使う。
gh issue close 1 -c 'testing' -r 'not planned'-r には閉じる理由を指定できる。 completed と not planned のどちらの値を指定できる。
| 値 | 意味 |
|---|---|
completed | 完了 |
not planned | 計画しなかった |
これは今まで気が付かなかった。確認するとWeb UIでも確かに2つの理由で閉じる事が出来るようになっていた。
Issueを再び開く
閉じたIssueは、様々な理由でもう一度開きたくなる事がある。その場合、Issueは開いた状態に戻す事ができる。その場合 gh issue repen によって再開できる。
gh issue reopen 1 -c 'yay'PRのステータスをチェックする
PRのステータスをチェックを確認するには gh pr checks を使う。
https://cli.github.com/manual/gh_pr_status
$ gh pr checks Some checks were not successful 1 failing, 2 successful, and 0 pending checks X ci/circleci: foo https://circleci.com/gh/TakesxiSximad... ✓ ci/circleci: bar https://circleci.com/gh/TakesxiSximad... ✓ ci/circleci: baz https://circleci.com/gh/TakesxiSximad...
Github CLIをアップグレードする
公式のドキュメントに書いてある。 https://github.com/cli/cli#installation
私はHomebrewを使っているのでHomebrew経由でアップグレードする。
$ brew upgrade gh
==> Caveats
Bash completion has been installed to:
/usr/local/etc/bash_completion.d
zsh completions have been installed to:
/usr/local/share/zsh/site-functions
==> Summary
🍺 /usr/local/Cellar/gh/1.4.0: 65 files, 16.7MB
Removing: /usr/local/Cellar/gh/1.0.0... (60 files, 16.2MB)
Updating Homebrew...
==> Auto-updated Homebrew!
Updated 3 taps (homebrew/cask-versions, homebrew/core and homebrew/cask).
==> New Formulae
bpython pdftilecut
==> Updated Formulae
Updated 68 formulae.
==> New Casks
twobird
==> Updated Casks
appcode grandtotal microsoft-powerpoint tor-browser
arq grid microsoft-word webcatalog
audio-hijack heimdall-suite nova wechat
blitz keep-it react-native-debugger zeitgeist
boxy-suite kui securesafe zoom
chromium microsoft-excel signal-beta
dosbox-x microsoft-outlook thunderbird
==> Deleted Casks
deadbeef-devel
==> Upgrading 1 outdated package:
gh 1.0.0 -> 1.4.0
==> Upgrading gh 1.0.0 -> 1.4.0
==> Downloading https://homebrew.bintray.com/bottles/gh-1.4.0.mojave.bottle.tar.gz
==> Downloading from https://d29vzk4ow07wi7.cloudfront.net/930dd87d86bcc1b6ac220cc488766df4fc00472d
0.6%
# 2.0%
### 4.3%
###### 8.3%
######### 13.0%
############### 21.4%
##################### 29.7%
################################# 46.3%
############################################# 63.3%
########################################################## 81.2%
####################################################################### 99.0%
######################################################################## 100.0%
==> Pouring gh-1.4.0.mojave.bottle.tar.gz
バージョンを確認する。
$ gh version gh version 1.4.0 (2020-12-15) https://github.com/cli/cli/releases/latest
期待する最新のバージョンにアップグレードできた。
JSONでの出力
--json オプションを指定することで出力をJSONにするPRが作られている。
https://github.com/cli/cli/pull/3414
まだマージはされていない。 早くマージしてくれると嬉しい。
Emacsから利用する
元々はEmacsからGithubの操作をするために、Github CLIを調べ始めた。特にorg-modeでタスク管理を行っているため、org-modeとGithub Issueを良い感じに足並みを揃えて管理したかった。そのためのユーティリティを一部実装した。
コードだけ雑に置いておく事にする。
https://github.com/TakesxiSximada/example/blob/master/org-github.el
使用感について
- CLI側にいろいろと機能をいれているが本来必要ないのでplanな状態の出力をしてほしい。
- 色を付けるなどの制御文字は本来不要。それに対して着色するのはCLIツール側ではなくターミナルエミュレーターとか、エディタ側が実施するべき内容。
- 無駄に出力を見やすくしようとして情報を切り詰めたりしている。画面サイズに応じて文字を切り詰めるかどうかもCLIツール側ではなくその結果を表示しているソフトウェアが行うべき。
確かに検索性はあまりよくはないけれど、その代替として使用しているツールも決して良いとは言えないように感じる。管理がしやすいのかというと、そうでもないように思える。