6つの手法を比較する
このシリーズで扱った手法を、同じ観点で並べる。上の4つが GitHub に直接アクセスする API 方式、下の2つがローカルクローンを操作するローカル方式だ。
| 手法 | 準備 | トークン | 回数の制限 | 変更行数 | 使った言語 |
|---|---|---|---|---|---|
| REST API (PART 03・06・08) | なし(VBA は VBA-JSON) | 公開は任意 非公開は必須 | 1時間 60回/5,000回 | コミットごとに1リクエスト | Python・VBA・GAS |
| PyGithub (PART 04) | pip install | 同上 | 同上 | 同上(属性に触れると取得) | Python |
| GraphQL API (PART 04・08) | なし | 常に必須 | 1時間 5,000ポイント | 一覧と同時に取れる | Python・GAS |
| GitHub CLI (PART 04) | gh のインストールとサインイン | CLI が管理 | REST/GraphQL と同じ | 呼ぶ API による | コマンド・Python |
| git log (PART 05・07) | Git のインストールとクローン | 不要(clone・fetch 時のみ認証) | なし | 1回のコマンドで全件 | Python・VBA |
| GitPython (PART 05) | 上に加えて pip install | 同上 | なし | コミットごとに Git を1回実行 | Python |
API 方式とローカル方式の違いは、突き詰めると「どこにある履歴を読むか」だ。API 方式は GitHub 上の履歴を必要な分だけ取りに行き、ローカル方式は履歴全体を先に手元へ持ってきてから読む。少しだけ見たいなら前者、何度も・全体を見たいなら後者が効率的になる。
目的別の選び方
| やりたいこと | おすすめ | 理由 |
|---|---|---|
| 直近のコミットを一覧にして報告書に貼る | REST API(PART 03・PART 06) | クローン不要で、すぐ始められる |
| スプレッドシートを毎朝自動で更新して共有する | GAS + REST API(PART 08) | PC を起動しておく必要がない |
| 履歴全体から作者別・ファイル別の変更行数を集計する | git log(PART 05・PART 07) | 回数の制限がなく、--numstat で一度に取れる |
| クローンせずに変更行数も取りたい | GraphQL(PART 04) | 100件分を1リクエストで取れる |
| 複数のリポジトリを横断して調べる | REST API または PyGithub | リポジトリの数だけクローンしなくて済む |
| コミットとプルリクエストを結び付けたい | REST API または GraphQL | GitHub 固有の情報は API でしか取れない |
| 未プッシュのコミットも含めて確認したい | git log | API は GitHub にプッシュ済みのものしか見えない |
| ターミナルでさっと確認したい | GitHub CLI(PART 04) | 認証済みのコマンド1行で済む |
| Git を入れていない人にもツールを配りたい | REST API(VBA・GAS) | 受け取る側の準備がトークンの設定だけで済む |
取得できる項目の対応表
同じ情報でも、手法によって名前が違う。REST API は JSON のパス、GraphQL は history の nodes に書く項目、git log は --pretty=format: のプレースホルダーで示す。
| 項目 | REST API | GraphQL | git log |
|---|---|---|---|
| SHA | sha | oid | %H |
| 短縮 SHA | (先頭7文字を切り出す) | abbreviatedOid | %h |
| 作者の名前 | commit.author.name | author { name } | %an |
| 作者のメールアドレス | commit.author.email | author { email } | %ae |
| 作者日時 | commit.author.date | authoredDate | %aI |
| コミッターの名前 | commit.committer.name | committer { name } | %cn |
| コミッター日時 | commit.committer.date | committedDate | %cI |
| メッセージの1行目 | (commit.message を改行で分ける) | messageHeadline | %s |
| メッセージの全文 | commit.message | message | %B |
| 親コミット | parents[].sha | parents(first: 2) { nodes { oid } } | %P |
| 追加・削除行数 | 詳細 API の stats.additions・stats.deletions | additions・deletions | --numstat(合計だけなら --shortstat) |
| 変更ファイル数 | 詳細 API の files の件数 | changedFilesIfAvailable | --numstat の行数 |
| 変更ファイルの一覧と種別 | 詳細 API の files[].filename・files[].status | —(REST API を使う) | --name-status |
| GitHub のユーザー名 | author.login | author { user { login } } | — |
| コミットのページの URL | html_url | url | — |
| 署名の検証結果 | commit.verification.verified | signature { isValid } | %G?(手元に公開鍵が必要) |
| 関連するプルリクエスト | GET /repos/{owner}/{repo}/commits/{sha}/pulls | associatedPullRequests(first: 1) { nodes { number title } } | — |
「詳細 API」は、コミット1件を取得する GET /repos/{owner}/{repo}/commits/{sha} を指す。PyGithub と GitPython の属性名は、それぞれ PART 04 と PART 05 の表にまとめている。
絞り込み条件の対応表
| 条件 | REST API(PyGithub も同名) | GraphQL の history | git log | GitPython の iter_commits |
|---|---|---|---|---|
| ブランチ・起点 | sha=develop | ref(qualifiedName: "refs/heads/develop") | git log origin/develop | 第1引数 "origin/develop" |
| 期間 | since=・until= | since:・until: | --since=・--until= | since=・until= |
| 作者 | author=(ユーザー名かメールアドレス) | author: {emails: ["…"]} | --author=(名前・メールアドレスの部分一致) | author= |
| パス | path= | path: | -- パス | paths= |
| 件数 | per_page= と打ち切り | first:(最大100) | --max-count= | max_count= |
| マージコミットを除く | —(parents が2つ以上のものを自分で除く) | —(同左) | --no-merges | no_merges=True |
| 2つの時点の間 | GET /repos/{owner}/{repo}/compare/v1.0...v2.0 | — | git log v1.0..v2.0 | 第1引数 "v1.0..v2.0" |
最後の行は、「前回のリリースから今回までに入ったコミット」を出すときに使う。REST API の compare は、ドットが3つ(...)である点に注意する。
手法によって結果が食い違う点
同じリポジトリでも、手法を変えると数字が合わないことがある。不具合ではなく、数え方の違いによるものだ。集計に使う前に、どの定義で数えるかを決めておく。
| 点 | API 方式 | ローカル方式 |
|---|---|---|
| 日時のタイムゾーン | 常に UTC で返る | コミットした人のタイムゾーンで記録されている。%aI で受けて変換するか、format-local で PC のタイムゾーンにそろえる |
| マージコミットの変更行数 | マージで取り込まれた差分を返す | git log --numstat は 0 として扱う。GitPython は1つ目の親との差分を返す |
| パスで絞ったときの変更行数 | コミット全体の値 | そのパスの分だけの値 |
| 作者での絞り込み | GitHub のユーザー名で絞れる | Git に記録された名前とメールアドレスで絞る。同じ人が複数の名前でコミットしていると別人に見える |
| 見えている範囲 | GitHub にプッシュ済みの履歴 | 最後に fetch した時点の履歴と、未プッシュのコミット。浅いクローンでは途中まで |
| 並び順 | どちらも、起点から親をたどった順が基本で、日時の降順とは限らない。日時順にしたいときは取得後に並べ替える | |
なお、「作者日時」と「コミッター日時」も別のものだ。作者日時は最初にコミットを作った日時、コミッター日時はリベースやチェリーピックなどでコミットを作り直した日時を表す。「いつ書かれたか」を見たいなら作者日時、「いつブランチに入ったか」に近いのはコミッター日時である。
エラーの逆引き
API 方式
| 症状 | 原因 | 対処 |
|---|---|---|
401 Bad credentials | トークンの値が違う、期限切れ、失効済み | 再発行して設定し直す。環境変数を変えたあとはアプリを開き直す |
403/429 で x-ratelimit-remaining: 0 | レート制限 | x-ratelimit-reset の時刻まで待つ。トークンを設定する(PART 02) |
403/429 で retry-after がある | セカンダリレート制限(短時間に集中しすぎ) | 指定された秒数だけ待つ。並列で呼ばない |
403 で「Resource not accessible by personal access token」 | トークンに必要な権限がない | Contents: Read-only を付ける |
404 Not Found | 名前の打ち間違い、または非公開リポジトリで権限がない | 名前を確認し、トークンの Repository access に対象が入っているか確認する |
409 Conflict | リポジトリが空 | コミットが1件もない場合は0件として扱う |
422 | パラメーターの値が不正(日時の形式など) | since・until を ISO 8601 形式にする |
| 30件しか取れない | per_page の既定値で、ページもたどっていない | per_page=100 にして Link ヘッダーの rel="next" をたどる |
| GraphQL でステータスは 200 なのに結果がない | 本文の errors にエラーが入っている | errors を必ず確認する(PART 04) |
| 日付が1日ずれる | UTC のまま表示している | 日本時間に変換する(9時間進める) |
ローカル方式
| 症状 | 原因 | 対処 |
|---|---|---|
git が見つからない | 未インストール、または PATH が通っていない | インストール後、ターミナルや Excel を開き直す |
not a git repository | 指定したフォルダーがクローンではない | .git フォルダーがある場所を指定する |
unknown revision(終了コード 128) | 起点のブランチ名が存在しない | git branch -a で名前を確認する |
detected dubious ownership | フォルダーの所有者が実行ユーザーと違う | 信頼できる場所なら safe.directory に追加する。ネットワークドライブは避ける |
| 新しいコミットが出ない | fetch していない、または起点が HEAD | git fetch して origin/ブランチ名 を起点にする |
| 履歴が途中までしかない | 浅いクローン | git fetch --unshallow |
| 日本語が化ける | 出力を CP932 として読んでいる | Python は encoding="utf-8"、VBA は一時ファイルを UTF-8 で読む |
| fetch で止まる | 認証の入力待ち | 先に手動で一度 fetch して資格情報を保存する |
トークンの扱いのまとめ
- fine-grained トークンを使い、対象のリポジトリと権限(Contents: Read-only)を最小にする
- 有効期限を設定する
- コード・ブック・スプレッドシートのセルに直接書かない(環境変数、スクリプト プロパティを使う)
- ツールを配るときは、各自が自分のトークンを設定する形にする
- トークンを入れたスプレッドシートの編集権限を絞る
- リポジトリの URL にトークンを埋め込まない
- 漏れた可能性があれば、すぐに失効させて再発行する
次の一歩
コミット履歴が取れるようになれば、同じ書き方で他の情報にも広げられる。
- 他の一覧を取得する:プルリクエスト(
/repos/{owner}/{repo}/pulls)、Issue(/issues)、リリース(/releases)も、ヘッダーとページネーションの書き方は同じだ - 課題管理と突き合わせる:コミットメッセージからチケット番号を正規表現で抜き出し、課題の一覧と照合する。Backlog の課題を取得する方法は Backlog 情報取得シリーズ で解説している
- 結果を通知する:前日のコミット一覧を毎朝チャットに投稿する。Google Chat への投稿方法は Bot 自動投稿シリーズ を参照してほしい
✅ シリーズのまとめ
GitHub をプログラムから操作する方法は、「GitHub に聞く」API 方式と「手元のクローンに聞く」ローカル方式の2系統に分かれる。少しだけ見るなら API、全体を何度も見るならローカル、変更行数をクローンなしで取りたいなら GraphQL、という使い分けを覚えておけば、言語が変わっても迷わない。