完成イメージと準備

この回で作るスクリプトは、リポジトリ名を渡すとコミット履歴を新しい順に表示する。

実行例
> python commits_rest.py VBA-tools/VBA-JSON --max 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
--- 8 件

必要なライブラリは requests だけだ。

ターミナル
pip install requests

公開リポジトリが対象なら、トークンがなくても動く。PART 02 の手順で環境変数 GITHUB_TOKEN を設定してあれば、自動的にトークンを使う。

コミット一覧のエンドポイント

コミットの一覧は、次の URL に GET リクエストを送って取得する。

エンドポイント
GET https://api.github.com/repos/{owner}/{repo}/commits

クエリパラメーターで、取得する範囲を指定できる。すべて省略可能だ。

パラメーター意味例
sha起点にするブランチ名・タグ名・コミットの SHA。省略するとデフォルトブランチdevelop
pathこのパス(ファイルまたはフォルダー)を変更したコミットだけJsonConverter.bas
author作者。GitHub のユーザー名またはメールアドレスtimhall
sinceこの日時以降。ISO 8601 形式2018-01-01T00:00:00+09:00
untilこの日時以前。ISO 8601 形式2018-12-31T23:59:59+09:00
per_page1ページの件数。既定は30、最大は100100
pageページ番号。既定は12

レスポンスは、コミットを1件1要素とした配列だ。お題に必要な部分だけを抜き出すと、次のような構造になっている。

レスポンス(1件分・抜粋)
{
  "sha": "06b6c45a2e8086a7a761f00bead7460852d6b602",
  "commit": {
    "author":    { "name": "Tim Hall", "email": "...", "date": "2019-01-28T16:19:54Z" },
    "committer": { "name": "Tim Hall", "email": "...", "date": "2019-01-28T16:19:54Z" },
    "message": "Update license",
    "verification": { "verified": false, "reason": "unsigned" }
  },
  "html_url": "https://github.com/VBA-tools/VBA-JSON/commit/06b6c45a...",
  "author":    { "login": "timhall", "id": 1211148 },
  "committer": { "login": "timhall", "id": 1211148 },
  "parents": [ { "sha": "1e49ba826b979d1851029dc965ecb6a3ead2a32c" } ]
}

紛らわしいのは、author が2か所にあることだ。

  • commit.author:Git に記録されている名前・メールアドレス・日時。必ず入っている
  • 外側の author:そのメールアドレスに結び付いた GitHub アカウント。結び付くアカウントがなければ null になる

お題の「作者」と「日時」には、必ず値が入っている commit.author を使う。

スクリプト全体

次のコードを commits_rest.py として保存する。

Python(commits_rest.py)
"""GitHub REST API でコミット履歴を取得して表示する"""
import argparse
import os
import time
from datetime import datetime, timedelta, timezone

import requests

API = "https://api.github.com"
API_VERSION = "2022-11-28"
JST = timezone(timedelta(hours=9))


def make_session() -> requests.Session:
    s = requests.Session()
    s.headers.update({
        "Accept": "application/vnd.github+json",
        "X-GitHub-Api-Version": API_VERSION,
        "User-Agent": "commit-history-sample",
    })
    token = os.environ.get("GITHUB_TOKEN")
    if token:  # 公開リポジトリならトークンなしでも動く(1時間60回まで)
        s.headers["Authorization"] = f"Bearer {token}"
    return s


def get(session: requests.Session, url: str, params: dict | None = None) -> requests.Response:
    """1回のリクエスト。レート制限に当たったら短時間だけ待って再試行する"""
    for _ in range(3):
        r = session.get(url, params=params, timeout=30)
        if r.status_code in (403, 429):
            if r.headers.get("Retry-After"):                      # セカンダリレート制限
                wait = int(r.headers["Retry-After"])
            elif r.headers.get("X-RateLimit-Remaining") == "0":   # プライマリレート制限
                wait = int(r.headers["X-RateLimit-Reset"]) - int(time.time()) + 1
            else:
                wait = None
            if wait is not None:
                if wait > 120:
                    reset = datetime.now(JST) + timedelta(seconds=wait)
                    raise SystemExit(f"レート制限に達した。{reset:%H:%M} 以降に再実行する")
                time.sleep(max(wait, 1))
                continue
        if r.status_code == 404:
            raise SystemExit("404: リポジトリ名が違うか、非公開リポジトリを読む権限がない")
        r.raise_for_status()
        return r
    raise SystemExit("再試行の上限に達した")


def list_commits(session: requests.Session, repo: str, **filters):
    """コミットを新しい順に1件ずつ返す(ページネーション対応)"""
    url = f"{API}/repos/{repo}/commits"
    params = {"per_page": 100, **{k: v for k, v in filters.items() if v}}
    while url:
        r = get(session, url, params)
        yield from r.json()
        url = r.links.get("next", {}).get("url")   # Link ヘッダーの rel="next"
        params = None                               # next の URL は条件を含んでいる


def get_stats(session: requests.Session, repo: str, sha: str) -> tuple[int, int, int]:
    """コミット1件の変更ファイル数・追加行数・削除行数(1件につき1リクエスト)"""
    d = get(session, f"{API}/repos/{repo}/commits/{sha}").json()
    return len(d["files"]), d["stats"]["additions"], d["stats"]["deletions"]


def to_row(c: dict) -> tuple[str, str, str, str]:
    a = c["commit"]["author"]
    when = datetime.fromisoformat(a["date"].replace("Z", "+00:00")).astimezone(JST)
    subject = (c["commit"]["message"].splitlines() or [""])[0]
    return when.strftime("%Y-%m-%d %H:%M"), a["name"], c["sha"][:7], subject


def main() -> None:
    p = argparse.ArgumentParser(description="コミット履歴を表示する")
    p.add_argument("repo", help="OWNER/REPO 形式(例: VBA-tools/VBA-JSON)")
    p.add_argument("--branch", help="ブランチ名・タグ名・SHA(省略時はデフォルトブランチ)")
    p.add_argument("--since", help="この日時以降(例: 2018-01-01T00:00:00+09:00)")
    p.add_argument("--until", help="この日時以前")
    p.add_argument("--author", help="GitHub のユーザー名またはメールアドレス")
    p.add_argument("--path", help="このパスを変更したコミットだけ")
    p.add_argument("--max", type=int, default=0, help="表示する最大件数(0 は全件)")
    p.add_argument("--stats", action="store_true", help="変更ファイル数と行数も表示する")
    args = p.parse_args()

    session = make_session()
    commits = list_commits(session, args.repo, sha=args.branch, since=args.since,
                           until=args.until, author=args.author, path=args.path)
    count = 0
    for c in commits:
        when, name, sha, subject = to_row(c)
        line = f"{when}  {name:<12.12}  {sha}  "
        if args.stats:
            files, add, dele = get_stats(session, args.repo, c["sha"])
            line += f"{files:>3} files  +{add:<5} -{dele:<5} "
        print(line + subject)
        count += 1
        if args.max and count >= args.max:
            break
    print(f"--- {count} 件")


if __name__ == "__main__":
    main()

コードのポイント

ヘッダーは Session にまとめる

requests.Session にヘッダーを設定しておくと、以降のリクエストすべてに付く。接続も使い回されるので、ページをたどるときに速い。付けているヘッダーは4つだ。

ヘッダー役割
Accept: application/vnd.github+jsonGitHub の JSON 形式で受け取る(公式が推奨している指定)
X-GitHub-Api-VersionAPI のバージョンを固定する(PART 02)
User-AgentGitHub の API は User-Agent のないリクエストを拒否する。requests は既定値を付けるが、何のプログラムかわかる名前にしておく
Authorization: Bearer トークン認証。環境変数にトークンがあるときだけ付ける

ページネーションは Link ヘッダーをたどる

コミットが100件を超えるリポジトリでは、1回のリクエストで全件は返らない。続きがあるとき、レスポンスの Link ヘッダーに次のページの URL が入る。

Link ヘッダーの例
link: <https://api.github.com/repositories/25739947/commits?per_page=30&page=2>; rel="next",
      <https://api.github.com/repositories/25739947/commits?per_page=30&page=3>; rel="last"

requests はこのヘッダーを解析して r.links に入れてくれるので、rel="next" の URL がなくなるまで繰り返せばよい。ページ番号を自分で数える方法より確実で、他の一覧系 API にも同じ書き方が使える。list_commits はジェネレーターにしてあるので、--max 8 のように途中で打ち切ると、それ以降のページは取得しない。

日時は UTC で返る

commit.author.date は 2019-01-28T16:19:54Z のように UTC で返る(末尾の Z が UTC を表す)。日本時間にするには9時間進める必要があり、to_row では astimezone(JST) で変換している。変換を忘れると、日付が1日ずれるコミットが出てくる。

並び順は「日時の降順」とは限らない

一覧は、起点のコミットから親をたどった順に返る。ブランチを長く育ててからマージした場合などは、古い日時のコミットが新しい日時のコミットより前に出ることがある。日時順に並べたいときは、取得したあとで並べ替える。

レート制限に当たったときの動き

get では、403・429 が返ったときにヘッダーを見て、待ち時間が2分以内なら待って再試行し、それより長ければ再開できる時刻を表示して終了する。トークンなしで上限(1時間60回)に達した場合は後者になる。

条件を絞って取得する

オプションを付けると、エンドポイントのパラメーターにそのまま渡る。たとえば「2018年以降に JsonConverter.bas を変更したコミット」は次のように取得する。

実行例
> python commits_rest.py VBA-tools/VBA-JSON --path JsonConverter.bas --since 2018-01-01T00:00:00+09:00

since と until にタイムゾーンを付けずに 2018-01-01T00:00:00Z と書くと UTC として扱われる。日本時間で区切りたいときは、例のように +09:00 を付ける。

発展:変更ファイル数と行数を付ける

一覧のレスポンスには、変更したファイルや行数は入っていない。これらは、コミット1件を取得する別のエンドポイントで得られる。

エンドポイント
GET https://api.github.com/repos/{owner}/{repo}/commits/{sha}

レスポンスには、一覧と同じ項目に加えて stats(追加・削除・合計の行数)と files(変更したファイルの配列)が入る。--stats を付けると、get_stats がコミットごとにこのエンドポイントを呼ぶ。

実行例
> python commits_rest.py VBA-tools/VBA-JSON --path JsonConverter.bas --since 2018-01-01T00:00:00+09:00 --stats
2019-01-29 01:05  Tim Hall      1e49ba8    2 files  +1     -1     v2.3.1
2019-01-29 01:04  Tim Hall      e0f1a77    2 files  +16    -5     Update vba-utc to v1.0.6
2018-06-07 23:52  Tim Hall      946f126    2 files  +1     -1     v2.3.0
2018-06-07 22:12  Tim Hall      bc913ff    1 files  +5     -6     Cleanup
2018-06-07 22:06  Tim Hall      cf4e164    2 files  +95    -100   Inline clsStringAppend
2018-01-27 03:13  philip_swann  17ceebe    4 files  +308   -141   json_BufferAppend replaced with clsStringAppend
2018-04-26 22:01  Tim Hall      0af3e4d    2 files  +1     -1     v2.2.4
2018-04-26 22:01  Tim Hall      f94b88e    1 files  +6     -6     Update VBA-UTC to v1.0.5
--- 8 件

6行目のコミット(1月27日)が、4月26日のコミットより前に出ている。先ほど説明した「日時の降順とは限らない」の実例だ。

⚠️ コミットの数だけリクエストが増える

この例は一覧1回+詳細8回で、合計9回のリクエストになる。89件すべてに --stats を付けると90回となり、トークンなしの上限(1時間60回)を超える。件数が多いときは、条件で絞るか、トークンを使うか、行数を一度に取れる GraphQL(PART 04)やローカル方式(PART 05)を選ぶ。

なお、1件のコミットで変更ファイルが非常に多い場合、files は1回のレスポンスに最大300件までしか入らない。その場合も stats の行数はコミット全体の値になっている。

CSV に出力する

結果を Excel で開きたいときは、CSV に書き出す。main の表示部分を次のように置き換える。

Python(CSV 出力の例)
import csv

with open("commits.csv", "w", newline="", encoding="utf-8-sig") as f:
    w = csv.writer(f)
    w.writerow(["日時", "作者", "SHA", "メッセージ"])
    for c in list_commits(make_session(), "VBA-tools/VBA-JSON"):
        w.writerow(to_row(c))

文字コードを utf-8-sig(BOM 付き UTF-8)にしておくと、Excel でダブルクリックして開いても日本語が化けない。

プライベートリポジトリの場合

🔒 この回のコードで変わる点

  • コードの変更は不要。環境変数 GITHUB_TOKEN に、対象リポジトリの Contents: Read-only を付けたトークン(PART 02)を設定するだけでよい
  • トークンがない、または権限が足りないと 404 が返る。このスクリプトは「リポジトリ名が違うか、権限がない」と表示して終了する
  • GitHub Enterprise Server を使っている場合は、定数 API を https://ホスト名/api/v3 に変える

つまずきやすい点

症状原因と対処
401 Bad credentialsトークンの値が違う、または期限切れ。環境変数を設定したあと、ターミナルを開き直したかも確認する
404 Not Found所有者名/リポジトリ名 の打ち間違い、または非公開リポジトリで権限がない
403 で「rate limit exceeded」レート制限。トークンを設定すると上限が 5,000回になる
409 Conflictリポジトリが空(コミットが1件もない)
30件しか取れないper_page を指定しておらず、ページもたどっていない。この回の list_commits を使う
社内ネットワークで接続できないプロキシが必要。環境変数 HTTPS_PROXY に http://proxy.example.co.jp:8080 の形式で設定すると requests が使う

✅ 次の記事では…

PART 04 では、同じお題を PyGithub・GraphQL・GitHub CLI で実装する。ライブラリを使うとどこまで短くなるか、GraphQL で変更行数を一度に取るとどうなるかを比べる。

→ PART 04 — PyGithub・GraphQL・GitHub CLIで取得する へ