pastak / githelp

Gitコマンドの使いこなし支援

GitHelp

Gitのコマンドの使いこなしを支援

概要

Gitのような複雑なシステムは使い方がわからなくて苦労する。 ある程度使い方を知っている場合でも あまり標準的でない操作は難しい。 たとえば以下のような場合は どういうコマンドを使えばいいだろうか?

• README.mdは3日前からどう変わった?
• 3日前のREADME.mdを見たい
• package.jsonからcoffeeという名前が消えたのはいつ?
• ここ1週間ぐらい変更されてないファイルは?
• 最近最も大量に修正したファイルはどれだっけ?

複雑なシステムにはヘルプやマニュアルが用意されているのが普通だし、 FAQや逆引き辞典が用意されていることもあるし、 答がWebでみつかることもあるが、 うまく検索できないことも多いし、 やり方がわかった場合でも キーワードやパラメタを指定して実行しなおす必要があるので手間がかかる。 このような問題をExpandHelpで解決する。

利用例

Gitに関連するタスクのキーワードやパラメタを指定すると 候補のリストが表示され、選択すると実行される。

• README 8 比較 のような引数を指定してgithelpコマンドを起動すると以下のような候補リストが提示される

$ githelp README 8 比較
[0] 「README.md」ファイルを8分前のものと比較する
   % git diff HEAD "@{8 minutes ago}" README.md
[1] 「README.md」ファイルを8時間前のものと比較する
   % git diff HEAD "@{8 hours ago}" README.md
[2] 「README.md」ファイルを8日前のものと比較する
   % git diff HEAD "@{8 days ago}" README.md
$

• -x オプションで2のような数字を指定すると実行できる

$ githelp README 8 比較 -x2
diff --git a/README.md b/README.md
index 862f185..34c8907 100644
--- a/README.md
+++ b/README.md
@@ -1,90 +1,3 @@
 # GitHelp
 
-**Gitのコマンドの使いこなしを支援する**
-
-### 解決したい問題
...

• -i オプションを指定すると対話的に選択できる

インストール

% gem install githelp

実装

• re_expand という正規表現展開ライブラリを利用
• dataディレクトリの下に問題パタンと解決コマンドを並べたものを用意しておく

[
  "「(#{files.join('|')})」ファイルを(#{numbers.join('|')})分前の(もの|バージョン)と比較する",
  'git diff HEAD "@{#{$2} minutes ago}" #{$1}'
],

• ファイル名にマッチする引数(e.g. README)や 数字にマッチする引数(e.g. 8)が指定されると1行目の記述にマッチすることになる
• ワンライナーでは難しい場合は exe の下にヘルパーコマンドを用意する (e.g. exe/githelp-changed )

解説

• ExpandHelp方式とは、 様々なタスクの説明と実際の操作を組にして記述しておき、 ユーザが与えたキーワードやパラメタにマッチするものを リストして実行可能にするというものである。
• いろんなクエリに対応できるようにするため説明は正規表現で記述しておく。 たとえばシステムの時刻をセットする機能の説明は(時計|時刻|時間)を((設定|セット)する|あわせる) のような正規表現で記述しておくことにより、時刻をセットする 時間をあわせる などのクエリにマッチするようにする。
• 「README.mdを消す方法」はマニュアルには書いてない。 「ファイルを消す方法」しか書いてない。 ファイルを消す方法を知った後で「README.md」を指定して実行する必要がある。
• そういえば先日「らくらくホン」画面上の鬱陶しい「羊」を消す方法が全くわからなかったのだが、あれは「マチキャラ」と呼ばれるものなので「マチキャラ」を消すという操作が必要だった。「羊 消す」とか「消す」とかで消せるべきだろう。githelpでは $ githelp 削除 と入力すれば削除関連で何ができるのかわかる。
• ヘルプといえば人工知能的なアプローチの方がトレンドかもしれないが、 本方式だと 自分が何をやりたいのかはっきりわかってない場合でも使えるし、 正しいセンテンスを正確に入力したり発声したりする必要がないから楽だと思う。 予測入力に近いといえるかもしれない。
• Gitは単なる適用例であり、広い範囲で使いたいと思っている。

お願い

• データが全然足りないので、足すべきデータを教えて下さい。 issueでもプルリクでも@masuiへのツイートでもいいです。

注意

• Gitリポジトリのディレクトリで実行して下さい
• re_expandの実装が富豪的なので大きなリポジトリだと不具合があるかもしれません