GitHubの彼と自分を比べて何になるの？ gh-diffの紹介〜翻訳プロジェクトのために
過去の自分と今の自分を比べてみてそこに何か変化があったとき、人は生きていることを実感します。UNIXを作った人達は自分たちが生きているということをコンピュータスクリーン上で実感したくて、「diff」というツールを作りました。diffがあれば簡単に一年前の自分と今の自分を比べられるのです。
% diff -u me_in_last_summer.txt me.txt
--- me_in_last_summer.txt 2013-07-03 18:17:21.000000000 +0900
+++ me.txt 2014-07-03 18:17:21.000000000 +0900
@@ -1,3 +1,4 @@
My name is Charlie.
I can do a handstand.
-I hate carrots.
+I love carrots.
+I speak Japanese a little.diffが吐き出す列をみて、あるときは成長を喜び、あるときは無為に過ごした１年を後悔したものです。
しかし時が過ぎ、自分の過去とだけ向き合う平穏な時代は終わりました。人々が常時繋がったソーシャルネットワークの時代が到来したのです。diffは昔と何も変わりませんが、時代の変化によりその使われ方が変化しました。人々は自分の成長を確認するためにdiffを使うことを止め、ソーシャルネットワークの向こう側にいる他人との比較にこれを利用するようになったのです。
% diff -u me.txt inet/linus.txt
--- me.txt 2015-07-03 22:17:21.000000000 +0900
+++ inet/linus.txt 2015-07-03 22:18:21.000000000 +0900
@@ -1,4 +1,4 @@
-My name is Charlie.
-I am single.
-I created let_it_fall.
-I am anus or git.
+My name is Linus
+I am married.
+I created Linux.
+I created Git.diffが吐き出す列をみて、あるときは勝ち誇り、あるときは辛すぎる現実に目を背けるのです。
それでも私たちはこの過酷な時代を生き抜いていかなければならないのです…diffという武器を持って..。
そんなわけで…。
GitHub上のファイルとローカルのファイルを簡単に比較できる「gh-diff」というツールを作りましたので紹介させてください（どんなわけ）😅
恐らく用途は限定的ですが、git管理下にない、またはGitHub上のプロジェクトとは別管理のファイル群と、GitHub上のファイル群とのdiffを取ることができます。後述するように、gh-diffは原文を組み込んだ翻訳ドキュメントと、オリジナルドキュメントを比較するのに便利なように作られています。
作った経緯
最近、@goshujinさんがホストの「jekyllrb-ja」というJekyllの日本語ドキュメント作成プロジェクトに関わっています。このプロジェクトでは、本家のドキュメントのアップデートにどうやって追随していくかということが現在進行形で問題になっています。その過程でこの問題の一部を解決するためのツールとして、@goshujinさんがRakeタスク（togglate）を作り、僕がそれを改良したThorタスク（jekyllja.thor）を作りました。gh-diffはjekyllja.thorを汎用化、Gem化したものとして生まれました。
使い方
ライブラリに付属する「README.ja.md」を転載して説明に代えます。
gh-diffにはgh-diffというターミナルコマンドが付いています。
% gh-diff
Commands:
gh-diff diff LOCAL_FILE [REMOTE_FILE] # Compare FILE(s) between local and remote repository. LOCAL_FILE can be DIRECTORY.
gh-diff dir_diff DIRECTORY # Print added and removed files in remote repository
gh-diff get FILE # Get FILE content from github repository
gh-diff help [COMMAND] # Describe available commands or one specific command
Options:
-g, [--repo=REPO] # target repository
-r, [--revision=REVISION] # target revision
# Default: master
-p, [--dir=DIR] # target file directory
[--username=USERNAME] # github username
[--password=PASSWORD] # github password
[--token=TOKEN] # github API access token‘melborne/tildoc’レポジトリのREADME.mdを比較するには、こうします。
% gh-diff diff README.md --repo=melborne/tildoc
Diff found on README.md <-> README.md [6147df8:master]--name_onlyオプションをfalseにセットすれば、その差分がプリントアウトされます。
% gh-diff diff README.md --repo=melborne/tildoc --no-name_only
Base revision: 6147df8378545a4807a2ed73c9e55f8d7204c14c[refs/heads/master]
--- README.md
+++ README.md
Add String#~ for removing leading margins of heredocs.
-Added this line to local.
-
## Installation
Add this line to your application's Gemfile:差分の結果を保存する場合は、--saveオプションをdiffコマンドに追加します。
翻訳などのプロジェクトのために
HTMLコメントタグを使って原文が挿入された翻訳ファイルがあり、この原文とリモートのオリジナルとを比較したい場合には、commentoutオプションが役立つでしょう。
% gh-diff diff README.ja.md README.md --commentout
これは、README.ja.mdからコメントテキストを抽出し、リモートのREADME.mdと比較します。
より詳細はgh-diff help diffを見てください。
環境変数ENVにおけるオプション
これらのオプションは、接頭辞GH_を使って環境変数にプリセットできます。
% export GH_USERNAME=melborne
% export GH_PASSWORD=xxxxxxxx
% export GH_TOKEN=1234abcd5678efgh
また、プロジェクトルートの.envファイルに設定することもできます。
#.env
REPO=jekyll/jekyll
DIR=site
.envの環境変数は、GH_で始まるグローバル環境変数を上書きします。
GitHub APIにはアクセス制限があります。ベーシック認証（usernameとpassword）または個人用のAPIトークンでこれを引き上げることができるので、それらを設定するとよいでしょう。
簡単なチュートリアル
簡単なチュートリアルを通して、gh-diffの使い方を説明します。以下では、GitHubで管理されているmelborne/tildocのREADME.mdを取得し、この翻訳版README.ja.mdを作成します。gem install gh-diffでgh-diffを取得して作業を開始します。
環境変数の設定
任意のディレクトリを用意し(ex. tildoc-ja)、オプション入力の手間を避けるため、そのルートに.envファイルを用意してオプションをプリセットします。
REPO=melborne/tildoc
TOKEN=xxxxxxxxxREADME.mdの取得
gh-diff getコマンドを使って、GitHubからREADME.mdを取得し、ローカルに保存します。デフォルトで最新のmasterのものを取得します。
tildoc-ja% gh-diff get README.md --ref
Base revision: 6147df8378545a4807a2ed73c9e55f8d7204c14c[refs/heads/master]
# Tildoc
Add String#~ for removing leading margins of heredocs.
## Installation
Add this line to your application's Gemfile:
gem 'tildoc'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tildoc
## Usage
.
.
.--refオプションは、ファイルの先頭行にリファレンス情報を追加します。--refオプションを外してこれをファイルに保存します。
tildoc-ja% gh-diff get README.md > README.md取得ファイルとの差分
この時点でローカルに保存したREADME.mdに少し変更を加え、リモートと比較してみます。ローカルのREADME.mdに次の二行を追加します。
# Tildoc
Add String#~ for removing leading margins of heredocs.
+Tilde + Heredoc = Tildoc 😃
+
## Installation
Add this line to your application's Gemfile:gh-diff diffコマンドでリモートとの差分を取ります。ファイル名が同じ時は一つ省略できます。
tildoc-ja% gh-diff diff README.md
Diff found on README.md <-> README.md [6147df8:master]違いがある旨が出力されました。ここでファイル名に代えてディレクトリを渡すと、その直下のファイル群が比較の対象となります。
差分をプリントしたいときは、--no-name_onlyオプションを付けます。
tildoc-ja% gh-diff diff README.md --no-name_only
Base revision: 6147df8378545a4807a2ed73c9e55f8d7204c14c[refs/heads/master]
--- README.md
+++ README.md
Add String#~ for removing leading margins of heredocs.
-Tilde + Heredoc = Tildoc 😃
-
## Installation
Add this line to your application's Gemfile:差分を保存したいときは--saveオプションを付けます。デフォルトでルートにdiffディレクトリを作りそこにREADME.diffというファイル名で保存します。
tildoc-ja% gh-diff diff README.md --save
Diff saved at 'diff/./README.diff'
tildoc-ja% tree
.
├── README.md
└── diff
└── README.diff
1 directory, 2 filesちょっと表記がおかしいですが、差分が保存されました。
翻訳ドキュメントの作成
取得したREADME.mdに基いて、翻訳ドキュメントREADME.ja.mdを作ります。ここでは、gh-diffにも組み込まれている「togglate」というツールを使います。次のようにします。
tildoc-ja% togglate create README.md --translate=to:ja --no-embed-code > README.ja.mdtogglateの自動翻訳機能を使って（translateオプション）、日本語ドキュメントを自動生成しREADME.ja.mdに保存します。togglateは原文を各センテンス毎にHTMLコメントタグで挿入します。生成されたファイルは次のようになります。
＃のTildoc
<!--original
# Tildoc
-->
ヒアドキュメントのリーディング·マージンを除去するための文字列＃〜を追加します。
<!--original
Add String#~ for removing leading margins of heredocs.
-->
チルダヒアドキュメント= Tildoc😃
<!--original
Tilde + Heredoc = Tildoc 😃
-->
任職
<!--original
## Installation
-->
アプリケーションのGemfileに次の行を追加します。
<!--original
Add this line to your application's Gemfile:
-->
宝石 'tildoc'
<!--original
gem 'tildoc'
-->
してから実行します。
<!--original
And then execute:
-->
パッケージ
<!--original
$ bundle
-->
またはそれを自分でインストールします。
<!--original
Or install it yourself as:
-->
$逸品tildocをインストールする
<!--original
$ gem install tildoc
-->
.
.
.訳が微妙ですが、これで訳が完成したとします。
翻訳ドキュメント内原文とGitHub上のREADME.mdを比較
時が流れて、どうやらGitHub上のREADME.mdがアップデートされたようです。README.ja.mdに挿入した原文と、アップデートされたGitHub上のREADME.mdを比較することで、翻訳ドキュメントをこれに追随させます。
commentoutオプションで、README.ja.md内のHTMLコメントタグから原文を抽出し、これをGitHubのREADME.mdと比較します。
tildoc-ja% gh-diff diff README.ja.md README.md --commentout --no-name_only
Base revision: 6147df8378545a4807a2ed73c9e55f8d7204c14c[refs/heads/master]
--- README.ja.md
+++ README.md
Add String#~ for removing leading margins of heredocs.
-Tilde + Heredoc = Tildoc 😃
-
## Installation
Add this line to your application's Gemfile:
puts ATool.help
```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/tildoc/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull RequestContributingの項が追加されているのがわかります。
なお、最初に取得したREADME.mdとの比較をしたい場合は、--revision=6147dfとして対象リビジョンを指定します。これは最初に保存したREADME.diffに記録されているのでそれを参照します。
この差分をREADME.ja.mdに取り込んで対応する訳文を追加すれば、オリジナルに追随できたことになります。
以上です。
翻訳プロジェクトなどで活かしてもらえると、うれしいです。
関連記事：
Sinatraが、Jekyllが、オープンソース翻訳プロジェクトが、今静かに動き出している
(追記：2014-7-4) コメントのご指摘を受けて、Diffをdiffに直しました。
blog comments powered by Disqus
