show-changes
Installation
SKILL.md
スキルの目的
変更前と変更後の差分を、ブラウザで開く1つの HTML のページにする。ページを見る人(レビューや承認をする人。依頼したユーザー自身のこともある)が、何がどれだけ変わったか(全体)と、どう変わったか(中身)を、リポジトリやフォルダをまたいで1か所で確かめられるようにする。ページは変更を見せるためのもので、変更の良し悪しは判断しない。呼び出し元は、このスキルを頼んだユーザー、またはこのスキルを呼んだエージェントだ。
ページは同梱の scripts/build.py で作る。Python 3.9 以上(python3 などのコマンド)がある環境では build.py を実行してページを作り、無い環境では、ページを作れないことを呼び出し元に伝える。ページを作る前に、呼び方と引数を記載した references/usage.md を読む。スキルの中のパス(scripts/・references/)は、このスキルのフォルダからの相対パスで記述してある。
比較対象の指定
- 見る人が確かめたい変更に合わせて、比べる対象の種類を選ぶ。git で管理している変更なら2つのコミット、git で管理していないファイルの前後(変更前に控えた複製と今のもの、2つの版のフォルダなど)なら2つのフォルダ、ほかのツールが作った差分ならその unified diff を比べる。種類は1つのページの中で混ぜられる。
- ブランチの変更を見せるなら、取り込み先のブランチとの分岐点からブランチの先までを比べる(
--merge-base)。取り込み先のブランチに後から入った変更が、ページに混ざらない。 - git の2つのコミットで比べられるのは、コミットされた変更だけだ。作業中の変更をコミットするかはユーザーが判断する。コミットしていない作業中の変更を見せるなら、
git diff HEADの出力を unified diff として渡すか(git にまだ追加していない新しいファイルは入らない)、変更前の複製と今のものを2つのフォルダとして比べる。2つのフォルダの比較は、git が無視するファイル(依存物・ビルドの出力・接続情報のファイルなど)も比べるので、比べるフォルダには見せたいファイルだけを入れる。 - unified diff の対象は差分に記載された行の範囲しか持たない。ファイルの全文を見せたいときは、ほかの種類の対象にする。
- ページの題とデータの版(
--data-version。ページのヘッダーにそのまま出る文字列)は、見る人が何を見ているかを後から言えるように付ける。題には何の変更か、データの版には比べた状態(コミット・日付・版の名前)が分かるものを入れる。
全文表示の選択
全文を入れると、見る人は変わった行の前後だけでなく、ファイル全体の流れの中で変更を読める。その代わり、ページは変わったファイルの大きさの分だけ大きくなる。依頼から、見る人が前後の流れまで読む必要があると読めるとき(文書の書き直し、設定ファイルの一部の変更など)に全文を入れ、変更の量や箇所を見るだけなら差分だけにする。どちらとも読めなければ差分だけにし、全文を入れたページも作れることを渡すときに添える。