なぜプログラムから操作するのか

GitHub の画面でもコミット履歴は見られる。それでもプログラムから取得したくなるのは、次のような場面だ。

  • 定期的な報告:週次・月次の作業報告に、期間内のコミット一覧を貼る
  • 集計:作者別・ファイル別の変更回数や変更行数を数える
  • 突き合わせ:課題管理ツールのチケット番号と、コミットメッセージを照合する
  • 監査・リリース管理:前回リリースから今回までに何が入ったかを一覧にする

どれも「同じ形式の一覧を、繰り返し作る」作業で、手作業では写し間違いが起きやすい。一度スクリプトにしておけば、条件を変えて何度でも同じ形式で出せる。

このシリーズは情報の取得(読み取り)だけを扱う。コミットの作成やプッシュのような書き込みは行わないので、試している途中でリポジトリを壊す心配はない。

2つの系統:GitHub に聞くか、手元のクローンに聞くか

コミット履歴を取得する方法は、大きく2つの系統に分かれる。

GitHubに直接アクセスする方法(REST API・GraphQL・ライブラリ・GitHub CLI)と、ローカルクローンをgit logで操作する方法の構成図

図1: GitHub に直接アクセスする方法と、ローカルクローンを操作する方法

A. GitHub に直接アクセスする(API 方式)

GitHub が公開している API に HTTPS でリクエストを送り、JSON で結果を受け取る。手元にリポジトリを置く必要がなく、HTTP 通信ができる言語ならどれでも使える。入口は4つある。

入口概要扱う回
REST APIURL ごとに決まった形の 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つの言語と、手法の対応は次のとおりだ。

手法PythonExcel VBAGoogle 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回で終わる。

どれを選ぶか

迷ったときは、次の順で考えるとよい。

  1. PC を起動せずに定期実行したい、結果を Google スプレッドシートで共有したい → GAS + REST API(PART 08)
  2. 対象のリポジトリをすでにクローンしている、または履歴全体を何度も集計する → ローカル方式(Python は PART 05、Excel は PART 07)
  3. クローンせずに直近の数十〜数百件を見たい、複数のリポジトリを横断したい → REST API(Python は PART 03、Excel は PART 06)
  4. プルリクエストなど GitHub 固有の情報も合わせて取りたい → API 方式。項目が多いなら GraphQL、手早く書くなら PyGithub(PART 04)
  5. コマンド1行で確認したい → GitHub CLI(PART 04)

言語は、結果をどこで使うかで決める。Excel の帳票に貼るなら VBA、スプレッドシートで共有するなら GAS、集計や他のツールとの連携まで広げるなら Python が扱いやすい。手法ごとの詳しい比較は PART 09 にまとめている。

このシリーズのお題

比較しやすいように、PART 03 以降はすべて同じお題を実装する。

📝 お題

対象リポジトリのコミット履歴を新しい順に取得し、日時(日本時間)・作者・短縮SHA・メッセージの1行目 を一覧にする。

発展として、コミットごとの 変更ファイル数・追加行数・削除行数 を付ける。

サンプルの対象には、公開リポジトリ VBA-tools/VBA-JSON を使う。PART 06 で実際に使うライブラリのリポジトリで、コミット数が89件と小さく、最後のコミットから時間が経っているため、いつ実行しても同じ結果になる。完成イメージは次のとおりだ。

出力イメージ(新しい順に8件)
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 03Python で REST API を呼ぶ(requests)A
PART 04PyGithub・GraphQL・GitHub CLI で取得するA
PART 05Python でローカルクローンを操作する(git log・GitPython)B
PART 06Excel VBA で REST API を呼ぶA
PART 07Excel VBA でローカルクローンを操作するB
PART 08Google Apps Script で REST API を呼ぶA
PART 09まとめ:手法の比較と取得できる項目一覧—

使う言語が決まっているなら、PART 02 を読んだあとは該当する回だけを読めばよい。各回は単独で動くコードを載せている。

✅ 次の記事では…

PART 02 では、API 方式の準備としてアクセストークンを発行し、安全に保管する方法と、レート制限の仕組みを確認する。

→ PART 02 — 準備:アクセストークンの発行・保管とレート制限へ