textconvとは?バイナリの中身を読む仕組み

textconvって何をするもの?

textconvは、Gitの設定項目のひとつです。ひとことで言うと「そのままでは差分が読めないファイルを、いったん人間が読めるテキストに変換してから比較する」ための仕組みです。

Gitは基本的にテキストファイルの差分を得意としています。ソースコードを1行書き換えれば、その行だけが赤と緑で表示される。あれが気持ちいいわけです。ところが、Word文書やPDF、画像、実行ファイルのような「バイナリファイル」を変更すると、Gitはこう言うだけになります。

Binary files a/report.pdf and b/report.pdf differ

「違います」以上の情報がない。これでは何が変わったのか分かりません。textconvは、この状況を改善するための設定です。

身近な例えで言うと

外国語で書かれた契約書の新旧2つのバージョンを見比べる場面を想像してください。あなたはその言語が読めない。並べても「なんか違うっぽい」としか言えません。

ここで通訳を1人雇って、「両方とも日本語に訳してから並べてくれ」と頼んだらどうでしょう。訳文同士を見比べれば、どこが変わったのか一目で分かります。この通訳の役割をするのが textconv に登録するコマンドです。

大事なのは、通訳は見比べるためだけに訳している、という点です。原本の契約書そのものは書き換えられていません。textconvも同じで、リポジトリに保存されているファイルの中身には一切手を触れず、差分を表示するときだけ変換をかけます。

どういう流れで動くのか

変更後のファイルにも同じ変換がかかり、その結果同士が比較されます。つまりGitから見れば「テキストファイルの差分」を出しているのと変わらない状態になる、というのがポイントです。

設定の考え方

設定は2段階で考えると分かりやすいです。まず「変換コマンドに名前をつけて登録する」、次に「どの種類のファイルにその変換を使うかを指定する」。

登録側はGitの設定ファイル(git configで書き込むもの)に書きます。ざっくりこんな形です。

[diff "mytool"]
    textconv = 変換を実行するコマンド

そして、どのファイルに適用するかは .gitattributes というファイルで指定します。

*.拡張子 diff=mytool

この2つが揃って初めて、対象の拡張子のファイルで git diff を打ったときに変換が走ります。片方だけだと動かないので、うまくいかないときはまずここを疑ってみるといいです。

つまずきやすいところ

最初にハマりやすいのが、変換コマンドの出力先です。textconvに指定するコマンドは、ファイルのパスを引数で受け取って、変換結果を標準出力に出す必要があります。ファイルに書き出すタイプのツールをそのまま指定しても期待どおりには動きません。小さなシェルスクリプトを1枚かませて、標準出力に流し直してやるのが定番の対処です。

もうひとつ、.gitattributesはリポジトリに含めてチームで共有できますが、diff.mytool.textconvの設定自体は各自のマシンのGit設定に書く必要があります。「自分の環境では差分が読めるのに、同僚の環境では Binary files differ のまま」というのはだいたいこれが原因です。変換ツール自体がインストールされているかどうかも含め、チームで共有するならセットアップ手順をREADMEに書いておくと親切です。

使いどころのイメージ

典型的なのは、そのままでは読めないけれど中身は本質的にテキスト、というファイル群です。オフィス文書、PDF、一部の設定ファイルやアーカイブなどが該当します。逆に、写真のような本当に画像でしかないファイルは、テキスト化しても意味のある差分になりにくいので相性はよくありません。

「変換して読めるようになるか?」を先に手元で試してから設定するのが遠回りに見えて一番早い、というのが正直なところです。