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 または GraphQLGitHub 固有の情報は API でしか取れない
未プッシュのコミットも含めて確認したいgit logAPI は GitHub にプッシュ済みのものしか見えない
ターミナルでさっと確認したいGitHub CLI(PART 04)認証済みのコマンド1行で済む
Git を入れていない人にもツールを配りたいREST API(VBA・GAS)受け取る側の準備がトークンの設定だけで済む

取得できる項目の対応表

同じ情報でも、手法によって名前が違う。REST API は JSON のパス、GraphQL は history の nodes に書く項目、git log は --pretty=format: のプレースホルダーで示す。

項目REST APIGraphQLgit log
SHAshaoid%H
短縮 SHA(先頭7文字を切り出す)abbreviatedOid%h
作者の名前commit.author.nameauthor { name }%an
作者のメールアドレスcommit.author.emailauthor { email }%ae
作者日時commit.author.dateauthoredDate%aI
コミッターの名前commit.committer.namecommitter { name }%cn
コミッター日時commit.committer.datecommittedDate%cI
メッセージの1行目(commit.message を改行で分ける)messageHeadline%s
メッセージの全文commit.messagemessage%B
親コミットparents[].shaparents(first: 2) { nodes { oid } }%P
追加・削除行数詳細 API の stats.additions・stats.deletionsadditions・deletions--numstat(合計だけなら --shortstat)
変更ファイル数詳細 API の files の件数changedFilesIfAvailable--numstat の行数
変更ファイルの一覧と種別詳細 API の files[].filename・files[].status—(REST API を使う)--name-status
GitHub のユーザー名author.loginauthor { user { login } }—
コミットのページの URLhtml_urlurl—
署名の検証結果commit.verification.verifiedsignature { isValid }%G?(手元に公開鍵が必要)
関連するプルリクエストGET /repos/{owner}/{repo}/commits/{sha}/pullsassociatedPullRequests(first: 1) { nodes { number title } }—

「詳細 API」は、コミット1件を取得する GET /repos/{owner}/{repo}/commits/{sha} を指す。PyGithub と GitPython の属性名は、それぞれ PART 04 と PART 05 の表にまとめている。

絞り込み条件の対応表

条件REST API(PyGithub も同名)GraphQL の historygit logGitPython の iter_commits
ブランチ・起点sha=developref(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-mergesno_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 していない、または起点が HEADgit 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、という使い分けを覚えておけば、言語が変わっても迷わない。

→ シリーズ一覧に戻る