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 コマンドで何ができるのか具体的に理解できる。