なぜプログラムから操作するのか
GitHub の画面でもコミット履歴は見られる。それでもプログラムから取得したくなるのは、次のような場面だ。
- 定期的な報告:週次・月次の作業報告に、期間内のコミット一覧を貼る
- 集計:作者別・ファイル別の変更回数や変更行数を数える
- 突き合わせ:課題管理ツールのチケット番号と、コミットメッセージを照合する
- 監査・リリース管理:前回リリースから今回までに何が入ったかを一覧にする
どれも「同じ形式の一覧を、繰り返し作る」作業で、手作業では写し間違いが起きやすい。一度スクリプトにしておけば、条件を変えて何度でも同じ形式で出せる。
このシリーズは情報の取得(読み取り)だけを扱う。コミットの作成やプッシュのような書き込みは行わないので、試している途中でリポジトリを壊す心配はない。
2つの系統:GitHub に聞くか、手元のクローンに聞くか
コミット履歴を取得する方法は、大きく2つの系統に分かれる。
図1: GitHub に直接アクセスする方法と、ローカルクローンを操作する方法
A. GitHub に直接アクセスする(API 方式)
GitHub が公開している API に HTTPS でリクエストを送り、JSON で結果を受け取る。手元にリポジトリを置く必要がなく、HTTP 通信ができる言語ならどれでも使える。入口は4つある。
| 入口 | 概要 | 扱う回 |
|---|---|---|
| REST API | URL ごとに決まった形の JSON が返る。最も基本的で、どの言語からも呼べる | PART 03・06・08 |
| ライブラリ(PyGithub など) | REST API を包んだもの。ページネーションや認証をライブラリが処理してくれる | PART 04 |
| GraphQL API | 欲しい項目を問い合わせ文で指定する。1回のリクエストで必要な項目だけを取れる | PART 04 |
GitHub CLI(gh) | GitHub 公式のコマンド。認証を CLI に任せて、コマンド1行で API を呼べる | PART 04 |
B. ローカルクローンを操作する(ローカル方式)
git clone で手元に複製したリポジトリに対して、git log などの Git コマンドを実行する。履歴はすべて手元の .git フォルダーに入っているので、取得のたびに通信する必要がない。プログラムからは、Git コマンドを子プロセスとして実行して出力を読むか、GitPython のようなライブラリを使う。
💡 Git と GitHub は別のもの
Git は手元で動くバージョン管理ツール、GitHub は Git のリポジトリを預かる Web サービスだ。ローカル方式は Git の機能だけを使うので、GitHub 以外(GitLab、Backlog の Git など)のリポジトリにもそのまま使える。API 方式は GitHub 固有の機能である。
手法と言語の対応
このシリーズで扱う3つの言語と、手法の対応は次のとおりだ。
| 手法 | Python | Excel VBA | Google Apps Script(GAS) |
|---|---|---|---|
| REST API を直接呼ぶ | ○ requests(PART 03) | ○ WinHttpRequest(PART 06) | ○ UrlFetchApp(PART 08) |
| ライブラリ・GraphQL・GitHub CLI | ○ PyGithub ほか(PART 04) | △ GraphQL は呼べるが利点が小さい | △ GraphQL は呼べる(PART 08 で補足) |
| ローカルクローンを操作する | ○ git log・GitPython(PART 05) | ○ git log を実行(PART 07) | × できない |
GAS でローカル方式が使えないのは、GAS のプログラムが Google のサーバー上で動くからだ。手元の PC のフォルダーにも Git コマンドにも手が届かないので、API 方式だけになる。逆に言えば、GAS は PC を起動していなくても定期実行できる。
取れる情報の違い
2つの系統は「どこにある履歴を見ているか」が違う。この違いが、取れる情報と制約の違いになる。
| 観点 | A. API 方式 | B. ローカル方式 |
|---|---|---|
| 見ている履歴 | GitHub にプッシュ済みの履歴 | 手元のクローンにある履歴(git fetch した時点まで。未プッシュのコミットも含む) |
| 事前準備 | なし(公開リポジトリ)/トークン(非公開リポジトリ) | Git のインストールとクローン |
| 通信 | 取得のたびに必要 | クローンと更新のときだけ。取得そのものはオフラインでできる |
| 回数の制限 | あり(レート制限。PART 02) | なし |
| 変更ファイル・変更行数 | コミット1件ごとに追加のリクエストが必要(GraphQL なら行数は一度に取れる) | git log --numstat で一度に取れる |
| GitHub 固有の情報 | 取れる(GitHub のユーザー名、プルリクエストとの関連、署名の検証結果など) | 取れない(Git に記録された名前とメールアドレスだけ) |
| ディスク | 使わない | リポジトリの大きさの分だけ使う |
たとえば今回のお題で使う公開リポジトリ(89コミット)で、全コミットの変更行数まで取ろうとすると、REST API では一覧の取得に加えてコミットごとに1回、合計90回のリクエストが必要になる。トークンなしの上限(1時間60回)を超えてしまう。ローカル方式なら、クローン済みであればコマンド1回で終わる。
どれを選ぶか
迷ったときは、次の順で考えるとよい。
- PC を起動せずに定期実行したい、結果を Google スプレッドシートで共有したい → GAS + REST API(PART 08)
- 対象のリポジトリをすでにクローンしている、または履歴全体を何度も集計する → ローカル方式(Python は PART 05、Excel は PART 07)
- クローンせずに直近の数十〜数百件を見たい、複数のリポジトリを横断したい → REST API(Python は PART 03、Excel は PART 06)
- プルリクエストなど GitHub 固有の情報も合わせて取りたい → API 方式。項目が多いなら GraphQL、手早く書くなら PyGithub(PART 04)
- コマンド1行で確認したい → GitHub CLI(PART 04)
言語は、結果をどこで使うかで決める。Excel の帳票に貼るなら VBA、スプレッドシートで共有するなら GAS、集計や他のツールとの連携まで広げるなら Python が扱いやすい。手法ごとの詳しい比較は PART 09 にまとめている。
このシリーズのお題
比較しやすいように、PART 03 以降はすべて同じお題を実装する。
📝 お題
対象リポジトリのコミット履歴を新しい順に取得し、日時(日本時間)・作者・短縮SHA・メッセージの1行目 を一覧にする。
発展として、コミットごとの 変更ファイル数・追加行数・削除行数 を付ける。
サンプルの対象には、公開リポジトリ VBA-tools/VBA-JSON を使う。PART 06 で実際に使うライブラリのリポジトリで、コミット数が89件と小さく、最後のコミットから時間が経っているため、いつ実行しても同じ結果になる。完成イメージは次のとおりだ。
2019-01-29 01:19 Tim Hall 06b6c45 Update license
2019-01-29 01:05 Tim Hall 1e49ba8 v2.3.1
2019-01-29 01:04 Tim Hall e0f1a77 Update vba-utc to v1.0.6
2018-08-31 05:16 Tim Hall 652ad8c Update README.md
2018-06-07 23:52 Tim Hall 946f126 v2.3.0
2018-06-07 23:49 Tim Hall 284dc72 Merge pull request #101 from VBA-tools/append
2018-06-07 23:48 Tim Hall 45aff20 Fix failing test on Mac
2018-06-07 22:12 Tim Hall bc913ff Cleanup自分のリポジトリで試す場合は、VBA-tools/VBA-JSON の部分を 所有者名/リポジトリ名 に置き換えればよい。
🔒 プライベートリポジトリの場合
このシリーズのサンプルは公開リポジトリを対象にしているが、業務で扱うのは非公開(プライベート)リポジトリであることが多い。違いは認証だけで、取得のコードは変わらない。
- API 方式:そのリポジトリを読む権限を持ったアクセストークンが必須になる(PART 02)
- ローカル方式:クローンと更新(
git clone・git fetch)のときに認証が必要になる。クローン済みの履歴を読むだけなら認証は要らない
各回に「プライベートリポジトリの場合」の囲みを入れて、その回で変わる点を説明する。
シリーズの構成
| 回 | 内容 | 系統 |
|---|---|---|
| PART 01 | 全体像と手法の選び方(この回) | — |
| PART 02 | 準備:アクセストークンの発行・保管とレート制限 | — |
| PART 03 | Python で REST API を呼ぶ(requests) | A |
| PART 04 | PyGithub・GraphQL・GitHub CLI で取得する | A |
| PART 05 | Python でローカルクローンを操作する(git log・GitPython) | B |
| PART 06 | Excel VBA で REST API を呼ぶ | A |
| PART 07 | Excel VBA でローカルクローンを操作する | B |
| PART 08 | Google Apps Script で REST API を呼ぶ | A |
| PART 09 | まとめ:手法の比較と取得できる項目一覧 | — |
使う言語が決まっているなら、PART 02 を読んだあとは該当する回だけを読めばよい。各回は単独で動くコードを載せている。
✅ 次の記事では…
PART 02 では、API 方式の準備としてアクセストークンを発行し、安全に保管する方法と、レート制限の仕組みを確認する。