研究コードを Git で管理する:結果を作った変更履歴を残す
小さな研究プロジェクトを Git に記録し、表を作ったコミットを特定します。ステージング、差分確認、履歴の読み方を実際に試せます。
結果の数値とコードの版を結び付ける
Git は、選んだファイルの状態をコミットとして記録するバージョン管理ツールです。研究では「平均が 25.0 分になった」という数値だけでなく、どのデータとコードからその数値を作ったかを残すために使います。コミット ID と入力データの版が分かれば、後から同じ手順をたどれます。
この章では、前章と同じ 4 件の架空データを使います。Git の履歴を作り、分析を実行し、README の説明だけを変更して、その差分を確認します。Git が初めてでも、フォルダを移動してコマンドを実行できれば取り組めます。Git と Python 3 を準備してください。GitHub のアカウントやインターネットへの公開は不要です。
コミットは手元に保存される記録です。別の場所へのバックアップや共同研究者への共有は別途必要です。また、履歴があるだけで研究設計や分析の妥当性が証明されるわけではありません。
記録するファイルと再生成するファイルを分ける
学習用プロジェクト一式をダウンロードし、空の作業場所に展開します。ターミナルで展開された study-sessions/ フォルダへ移動してください。この章のコマンドは、すべてその直下で実行します。ZIP 内の README は英語・中国語・韓国語です。日本語の説明書は別ファイルとして読めます。
| 記録するもの | この例での理由 |
|---|---|
README*.md とデータ辞書 | 目的、列の意味、実行方法を説明するため。 |
analysis/analyze.py | 結果を作る計算手順を特定するため。 |
data/sessions.csv | 小さな架空データであり、この練習では共有できるため。 |
expected/means.csv | 実行結果を照合する基準を残すため。 |
実研究のデータは、容量、利用条件、個人情報の有無を確認してから扱います。公開できないデータは追加せず、権限のある人が入手する方法とデータの版を説明書に書いてください。
この ZIP の .gitignore は次のパスを除外します。環境や結果を削除する設定ではなく、未追跡ファイルを追加候補から外す設定です。すでに記録済みのファイルや古いコミットの内容は消えません。
.venv/
__pycache__/
results/
最初のコミットを作る
まず Git のインストールを確認し、このフォルダの履歴を初期化します。すでに別の研究で使っているリポジトリではなく、今回展開した練習用フォルダで実行しましょう。
git --version
git init
git status --short
初めて Git を使う場合は、コミットに記録する名前とメールアドレスを設定します。以下は練習用の例です。自分の記録に使う値へ置き換えてください。--local はこのリポジトリだけに適用されます。
git config --local user.name "Research Learner"
git config --local user.email "learner@example.org"
次に、対象を選び、記録予定の差分を読み、コミットします。data/ には ZIP 内の各言語のデータ辞書も含まれます。関係のないファイルを追加した場合は、先に対象を見直してください。
git add README.md README.zh.md README.ko.md .gitignore data/ analysis/ expected/
git diff --cached
git commit -m "Add study-session data and mean-duration analysis"
git status --short
git add は次のコミットに入れる状態をステージング領域へ選びます。git diff --cached は選んだ差分を表示し、git commit がその状態を記録します。上記の ZIP だけを展開した練習なら、最後の git status --short に出力がない状態が目安です。別のファイルを追加していた場合は、その一覧を読み、なぜ残っているか確認します。
分析を実行し、結果を作ったコミットを控える
python analysis/analyze.py
git status --short
git rev-parse HEAD
git log --oneline -5
環境によって python は python3 または py -3 に置き換えます。results/means.csv と expected/means.csv を比較してください。期待する内容は次のとおりです。
condition,mean_minutes
background-noise,20.0
quiet,25.0
生成された results/ は無視されるので、この実習では分析後も作業ツリーに変更は表示されません。git rev-parse HEAD が返す完全なコミット ID と、入力の data/sessions.csv、実行コマンド、確認した結果を、実行メモや報告書の付録に残します。
コードに未コミットの変更があるまま実行した場合、HEAD の ID だけではその実行状態を示せません。差分を確認して必要な変更をコミットし、意図した状態で再実行しましょう。実データを Git 外に置く場合は、入力データの版やチェックサムも別に記録します。
後から当時のスクリプトを読むには、次の <commit-id> を保存した ID に置き換えます。これはファイルを表示するコマンドで、現在の作業ファイルは書き換えません。
git show <commit-id>:analysis/analyze.py
練習:説明だけの変更を見分ける
README.md をテキストエディタで開き、「この 4 件は学習用の架空データで、音の効果を示す実験結果ではない」という意味の 1 文を末尾に追加して保存します。分析スクリプトやデータは変更しません。
git diff -- README.md
git add README.md
git diff --cached
git commit -m "Explain the origin of the synthetic data"
git log -2 --oneline
履歴には少なくとも 2 つのコミットが現れ、最新の差分は README の説明だけになっているはずです。git add の後にもう一度ファイルを編集した場合、その追加編集は自動的にはステージされません。差分を読み直してからコミットします。
確認するポイントを見る
最新コミットの差分は git show --stat HEAD と git show HEAD -- README.md で確認できます。データと計算を変更していないので、再実行しても平均は 20.0 分と 25.0 分のままです。共同研究者に「数値を変えずに説明を改善した変更」だと伝えられれば、この練習は完了です。
次に残す記録を確認する
- 結果を作ったコードのコミット ID がある。
- 入力データの場所と版が分かる。
- 実行前に未コミットの変更を確認した。
- 期待結果と実行結果を照合した。
- 必要な人が履歴と入力を入手できる。
前章のデータ整理と説明書も合わせて確認してください。次に必要なのは、Python や依存関係の版を伝える環境の記録です。次章で Python 環境の記録を実践します。
参考資料とライセンス
本章は The Turing Way Community の著作物(Copyright © The Turing Way Community、CC BY 4.0)を基に構成しています。Miss Formula が英語版を編集基準として日本語で説明を再構成し、計算例と練習問題を追加しました。原典の図やデータは転載していません。