hub コマンドの BDD がユーザードキュメントとして素晴らしい
OSSメンテナをしていると他人のPRやブランチをチェックアウトして何かを確認したいということは頻繁にあって、いちいち git remote add して fetch してってのが面倒なので Github 製の Github CLI クライアントである hub を愛用している。
でも hub コマンドって、ドキュメントがあまりなくて、 help コマンドの出力も最小限で、頻繁に使う一部の機能以外はほとんど使いこなせずにいた。
しかし、 hub コマンドが Cucumber を使って BDD をしているのを最近知った。「どういう仕組でBDDが動いているのか」は全くわからないけれども、 「hub がどういうコマンドを実行するとどういう動作をするのか」は凄くわかりやすい。
たとえば、 hub pr checkout コマンドの Behavior を見てみると、
Feature: hub pr checkout <PULLREQ-NUMBER> Background: Given I am in "git://github.com/mojombo/jekyll.git" git repo And I am "mojombo" on github.com with OAuth token "OTOKEN" Scenario: Checkout a pull request Given the GitHub API server: """ get('/repos/mojombo/jekyll/pulls/77') { json :number => 77, :head => { :ref => "fixes", :repo => { :owner => { :login => "mislav" }, :name => "jekyll", :private => false } }, :base => { :repo => { :name => 'jekyll', :html_url => 'https://github.com/mojombo/jekyll', :owner => { :login => "mojombo" }, } }, :maintainer_can_modify => false, :html_url => 'https://github.com/mojombo/jekyll/pull/77' } """ When I run `hub pr checkout 77` Then "git fetch origin refs/pull/77/head:fixes" should be run And "git checkout fixes" should be run And "fixes" should merge "refs/pull/77/head" from remote "origin"
- mojombo/jekyll をチェックアウトしたリポジトリにいるときに
hub pr checkout 77
を実行すると、- hubが
git fetch origin refs/pull/77/head:fixes
を実行して、 (ここで "fixes" は上の Github API のレスポンスで判断していることがなんとなくわかる) git checkout fixes
を実行してくれる
事がわかる。
例となるシナリオを用意して、どんな git コマンドを実行してくれるのかわかる。しらない git コマンドがあればそれは git のマニュアルで調べればいい。
コマンドごとにいくつかシナリオが用意されているので、 hub help コマンド名 するよりも、この feature ファイルを探して斜め読みするほうがずっと hub コマンドで何ができるのか具体的に理解できる。