MarkItDownでGitHubのExcel差分が見やすくなった話

CEOの@uen0yamaです。

MarkItDownを使って、Excelファイルのコミット時にはMarkdownもセットで登録するよう構成したら、Pull RequestのExcelレビューがとてもスムーズになりました。

背景

みなさんはGitHubに*.xlsxとか*.docxとか突っ込んでますか？
*.docxの方は、わりとMarkdown形式に置き換わっているケースが多いのですが、*.xlsxはまだまだ現役なんですよね。
何らかの規則に基づいた表などは、まだまだMarkdownのテーブルでは機能不足なので、Excelに頼るケースが多いです。

Excelの変更についてのPull Requestレビューでは、どこを修正したの？　が、依頼者の自己申告だったりしています。
（WinMergeとかで差分抽出もできますが、手順が必要でめんどくさい）

この運用方法、なーんか危なっかしいなー、と思っていたところに現れたのがMarkItDownでした！

設定方法

1. PythonとMarkItDownをインストールする

公式サイトとか参考に、PCにインストールしておきます。

2. quotepathを無効にする

Excelファイルを使っているあなたは、きっとファイル名に日本語を使う人ですよね。
私もそうです。
後述するpre-commitでは、quotepathが有効な状態（デフォルトは有効）だと、ファイル名に日本語があると失敗してしまうので無効にしておきます。

git config --local core.quotepath false

3. pre-commitを設定する

プロジェクトフォルダーの、.git/hooks以下にpre-commitファイルを作成し、下記の内容を貼り付けます。

#!/bin/sh

# 変更されたファイルのリストを取得
changed_files=$(git diff --cached --name-only | tr -d '"')

# 変更されたファイルの中に拡張子がxlsxのものがあるか確認
for file in $changed_files; do
  if [[ ${file##*.} == "xlsx" ]]; then
    # 同じファイル名で拡張子がmdのファイル名を作成
    md_file="${file%.xlsx}.md"
    # コマンドを実行
    markitdown "$file" > "$md_file"
    # Shift-JISからUTF-8（BOMなし）に変換
    iconv -f sjis -c "$md_file" > "$md_file.utf8"
    mv "$md_file.utf8" "$md_file"
    # .mdファイルをステージングに追加
    git add "$md_file"
  fi
done

これで設定は完了です！

使い方

とくに何も気にせず、Excelファイルを更新してコミットするだけで、対となるMarkdownファイルも登録されます。
Pull Requestのレビュー時は、最初にMarkdownの差分を見て、変化のあった箇所をExcelで確認する流れになり、レビュー漏れが無くなってイイ感じです！

注意点

あくまでも差分をMarkdownで抽出しているので、当然ながらExcelで列の追加／削除を行うと、全体に変更が発生したことになります。
そういうのは、列を追加／削除するだけのコミット／Pull Requestを分けるようにして使いましょう。

MarkItDownは、他にも様々な活用方法がありそうなので、引き続き遊んでいきます！