ローカル方式の流れ

ローカル方式は、次の3段階で進む。

  1. クローン:git clone でリポジトリを手元に複製する(最初の1回だけ)
  2. 更新:git fetch で、前回以降に GitHub に追加された履歴を取り込む
  3. 取得:git log を実行し、出力を解析する(通信しない)

通信が必要なのは 1 と 2 だけだ。3 は何度実行しても GitHub に負荷をかけず、回数の制限もない。準備として、Git がインストールされていることを確認する。

ターミナル
git --version

履歴を取るためのクローン

普通にクローンしてもよいが、履歴を見るだけなら、作業ツリー(ファイルの実体)は要らない。次のオプションを付けると、クローンが速くなり、ディスクも節約できる。

ターミナル
git clone --filter=blob:none --no-checkout https://github.com/VBA-tools/VBA-JSON.git C:\work\VBA-JSON
オプション意味
--filter=blob:noneコミットとフォルダー構成の情報だけを取得し、ファイルの中身は必要になったときに取りに行く(ブロブレスクローン)
--no-checkout作業ツリーにファイルを展開しない

日時・作者・メッセージの一覧だけなら、この状態で通信なしに取得できる。変更行数(--numstat)を取るときは、差分の計算にファイルの中身が必要になるので、初回だけ不足分を自動でダウンロードする。

⚠️ --depth を付けたクローンでは履歴が途中までしか取れない

git clone --depth 1 のような浅いクローン(シャロークローン)は、指定した件数より古い履歴を持っていない。CI が作ったクローンはこの形になっていることが多い。全履歴が必要なら git fetch --unshallow で取り直す。

HEAD と origin/HEAD の違い

git log は、起点を指定しなければ HEAD(手元でチェックアウトしているブランチ)の履歴を表示する。ここに落とし穴がある。git fetch は手元のブランチを動かさないので、fetch しただけでは HEAD の履歴は古いままだ。

起点の指定見える履歴
HEAD(省略時)手元のブランチの履歴。未プッシュのコミットも含む。git pull するまで更新されない
origin/main など最後に fetch した時点の、GitHub 上のブランチの履歴
origin/HEADクローンした時点での、GitHub 上のデフォルトブランチ

「GitHub にある最新の履歴」が欲しいときは、git fetch してから origin/ブランチ名 を起点にする。作業ツリーに触れないので、作業中のクローンに対して実行しても、編集中のファイルに影響しない。この回のスクリプトは origin/HEAD を既定の起点にしている。

git log の出力を解析しやすくする

git log の既定の出力は人が読むためのもので、プログラムで解析するには向かない。--pretty=format: で、欲しい項目だけを決まった区切りで出力させる。

プレースホルダー意味例
%H / %hSHA(40桁)/短縮形06b6c45a2e80… / 06b6c45
%an / %ae作者の名前/メールアドレスTim Hall
%aI作者日時(ISO 8601 形式・タイムゾーン付き)2019-01-28T11:19:54-05:00
%cn / %cIコミッターの名前/コミッター日時
%sメッセージの1行目Update license
%bメッセージの2行目以降(本文)
%P親コミットの SHA(マージコミットは2つ以上)
%x1f など16進数で指定した1文字%x09 はタブ

区切り文字には、メッセージの中に現れない文字を選ぶ。カンマやタブは件名に含まれることがあるので、この回では制御文字の 0x1f(項目の区切り) と 0x1e(レコードの区切り) を使う。どちらも、もともとデータの区切りを表すために用意された文字だ。

日時は、コミットした人のタイムゾーンで記録されている。上の例の -05:00 は米国東部時間だ。API が常に UTC で返すのとは違うので、%aI でタイムゾーン付きの形式を受け取り、Python 側で日本時間に変換する。

スクリプト全体

次のコードを commits_local.py として保存する。標準ライブラリだけで動く。

Python(commits_local.py)
"""ローカルクローンの git log からコミット履歴を取得して表示する"""
import argparse
import os
import subprocess
from datetime import datetime, timedelta, timezone

JST = timezone(timedelta(hours=9))
# %x1e = レコード区切り、%x1f = 項目区切り(メッセージに現れない制御文字)
FORMAT = "%x1e%H%x1f%an%x1f%aI%x1f%s%x1f"


def git(repo_dir: str, *args: str) -> str:
    r = subprocess.run(
        ["git", "-C", repo_dir, "-c", "core.quotepath=false", *args],
        capture_output=True, text=True, encoding="utf-8", errors="replace",
    )
    if r.returncode != 0:
        raise SystemExit(f"git {args[0]} が失敗した: {r.stderr.strip()}")
    return r.stdout


def ensure_clone(url: str, repo_dir: str) -> None:
    """クローンがなければ作り、あれば最新の履歴を取り込む"""
    if not os.path.isdir(os.path.join(repo_dir, ".git")):
        subprocess.run(["git", "clone", "--filter=blob:none", "--no-checkout", url, repo_dir],
                       check=True)
    else:
        git(repo_dir, "fetch", "--prune")


def list_commits(repo_dir: str, rev: str = "origin/HEAD", *, since=None, until=None,
                 author=None, path=None, max_count=0, stats=False):
    """コミットを新しい順に dict で返す"""
    args = ["log", f"--pretty=format:{FORMAT}"]
    if stats:
        args.append("--numstat")
    if max_count:
        args.append(f"--max-count={max_count}")
    if since:
        args.append(f"--since={since}")
    if until:
        args.append(f"--until={until}")
    if author:
        args.append(f"--author={author}")
    args.append(rev)
    if path:
        args += ["--", path]

    for record in git(repo_dir, *args).split("\x1e")[1:]:
        sha, name, date, subject, rest = record.split("\x1f")
        commit = {
            "sha": sha,
            "author": name,
            "date": datetime.fromisoformat(date).astimezone(JST),
            "subject": subject,
            "files": 0, "additions": 0, "deletions": 0,
        }
        for line in rest.splitlines():           # --numstat の行:追加<TAB>削除<TAB>パス
            if not line.strip():
                continue
            add, dele, _path = line.split("\t", 2)
            commit["files"] += 1
            if add != "-":                       # バイナリファイルは "-" になる
                commit["additions"] += int(add)
                commit["deletions"] += int(dele)
        yield commit


def main() -> None:
    p = argparse.ArgumentParser(description="ローカルクローンのコミット履歴を表示する")
    p.add_argument("repo_dir", help="クローン先のフォルダー")
    p.add_argument("--url", help="指定するとクローンの作成・更新(fetch)を先に行う")
    p.add_argument("--rev", default="origin/HEAD", help="ブランチ名など(既定: origin/HEAD)")
    p.add_argument("--since")
    p.add_argument("--until")
    p.add_argument("--author")
    p.add_argument("--path")
    p.add_argument("--max", type=int, default=0)
    p.add_argument("--stats", action="store_true")
    args = p.parse_args()

    if args.url:
        ensure_clone(args.url, args.repo_dir)

    count = 0
    for c in list_commits(args.repo_dir, args.rev, since=args.since, until=args.until,
                          author=args.author, path=args.path, max_count=args.max,
                          stats=args.stats):
        line = f"{c['date']:%Y-%m-%d %H:%M}  {c['author']:<12.12}  {c['sha'][:7]}  "
        if args.stats:
            line += f"{c['files']:>3} files  +{c['additions']:<5} -{c['deletions']:<5} "
        print(line + c["subject"])
        count += 1
    print(f"--- {count} 件")


if __name__ == "__main__":
    main()

--url を付けると、クローンがなければ作成し、あれば fetch してから履歴を表示する。

実行例
> python commits_local.py C:\work\VBA-JSON --url https://github.com/VBA-tools/VBA-JSON.git --max 8
Cloning into 'C:\work\VBA-JSON'...
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 件

PART 03 の API 方式とまったく同じ結果になる。2回目以降は --url を外せば、通信せずに一瞬で終わる。

コードのポイント

コマンドはリストで渡す

subprocess.run には、コマンドを文字列ではなくリストで渡している。シェルを経由しないので、フォルダー名に空白や日本語が含まれていても引用符で悩まずに済み、外部から受け取った値を引数にしても、別のコマンドとして実行される心配がない。

-C で対象のフォルダーを指定する

git -C フォルダー と書くと、そのフォルダーに移動したのと同じ状態でコマンドが実行される。Python 側で os.chdir する必要がない。

文字コードを UTF-8 に固定する

Windows の Python は、子プロセスの出力を既定で CP932(Shift_JIS)として読もうとする。Git の出力は UTF-8 なので、encoding="utf-8" を指定しないと、日本語のコミットメッセージで文字化けやエラーが起きる。-c core.quotepath=false は、--numstat で日本語のファイル名が "\346\227\245…" のように表示されるのを防ぐ設定だ。

レコードの区切りを先頭に置く

書式の先頭に %x1e を置いているのは、--numstat の出力が各コミットの後ろに続くからだ。先頭で区切っておけば、「次の区切りまで」がそのコミットの情報になり、--numstat の有無にかかわらず同じ処理で解析できる。

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

--stats を付けると、git log に --numstat が加わる。API 方式ではコミットの数だけリクエストが必要だったが、ローカル方式ではコマンド1回で全コミットの値が返る。

実行例
> python commits_local.py C:\work\VBA-JSON --stats --max 5
2019-01-29 01:19  Tim Hall      06b6c45    1 files  +1     -1     Update license
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-08-31 05:16  Tim Hall      652ad8c    1 files  +4     -0     Update README.md
2018-06-07 23:52  Tim Hall      946f126    2 files  +1     -1     v2.3.0
--- 5 件

絞り込みのオプションも使える。ただし、意味が API とは少し違うものがある。

オプションgit log での意味API との違い
--since・--until日時で絞る。2018-01-01 のほか "2 weeks ago" のような書き方もできるタイムゾーンを省略すると、実行した PC のタイムゾーンで解釈される
--author「名前 <メールアドレス>」に対する部分一致(正規表現)GitHub のユーザー名では絞れない
--path(-- パス)そのパスを変更したコミットだけ--numstat の集計もそのパスの分だけになる(API はコミット全体の値を返す)

また、マージコミットは、git log --numstat では変更なし(0ファイル)として表示される。API はマージで取り込まれた差分を返すので、マージコミットの行数は手法によって一致しない。集計に使うときは、どちらの数え方にするかを決めておく。

GitPython で取得する

GitPython は、Git のリポジトリを Python のオブジェクトとして扱えるライブラリだ。内部では Git コマンドを実行しているので、Git のインストールは必要である。

ターミナル
pip install GitPython
Python(commits_gitpython.py)
"""GitPython でローカルクローンのコミット履歴を取得して表示する"""
from datetime import timedelta, timezone

from git import Repo

JST = timezone(timedelta(hours=9))

repo = Repo(r"C:\work\VBA-JSON")            # クローン済みのフォルダー
repo.remotes.origin.fetch(prune=True)       # 最新の履歴を取り込む

for c in repo.iter_commits("origin/HEAD", max_count=8):
    when = c.authored_datetime.astimezone(JST)
    total = c.stats.total                   # {'files': n, 'insertions': n, 'deletions': n, 'lines': n}
    print(f"{when:%Y-%m-%d %H:%M}  {c.author.name:<12.12}  {c.hexsha[:7]}  "
          f"{total['files']:>3} files  +{total['insertions']:<5} -{total['deletions']:<5} {c.summary}")
取りたいものGitPythongit log のプレースホルダー
SHAc.hexsha%H
作者名・メールアドレスc.author.name・c.author.email%an・%ae
作者日時・コミッター日時c.authored_datetime・c.committed_datetime%aI・%cI
メッセージの1行目・全文c.summary・c.message%s・%B
親コミットc.parents%P
変更行数・ファイルごとの内訳c.stats.total・c.stats.files--numstat

絞り込みは repo.iter_commits("origin/HEAD", since="2018-01-01", paths="JsonConverter.bas", author="Tim") のように、git log のオプションをキーワード引数で渡す。

注意点は速度だ。c.stats は、コミット1件ごとに Git コマンドを1回実行する。数百件なら気にならないが、数万件の履歴で行数を集計するなら、git log --numstat を1回実行する commits_local.py の方がずっと速い。なお GitPython は、マージコミットの行数を1つ目の親との差分として返すので、この点も git log --numstat と一致しない。

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

🔒 認証が必要なのはクローンと fetch だけ

クローン済みの履歴を読む(git log)だけなら、認証は要らない。git clone と git fetch のときに、次のどちらかで認証する。

  • HTTPS:Git for Windows に付属する Git Credential Manager が、初回にブラウザーでのサインインを求め、以降は資格情報を Windows に保存する。一度手動で git fetch を実行してサインインを済ませておけば、スクリプトからは認証なしで動く
  • SSH:SSH の鍵を作り、公開鍵を GitHub に登録して、git@github.com:所有者名/リポジトリ名.git の形式の URL でクローンする

タスクスケジューラなど、人がいない場面で fetch を動かすときは、サインインの画面が出ると処理が止まってしまう。事前に同じユーザーで一度 fetch しておくか、SSH を使う。URL に https://トークン@github.com/… のようにトークンを埋め込む方法は、.git/config にトークンが平文で残るので避ける。

つまずきやすい点

症状原因と対処
fetch したのに新しいコミットが出ない起点が HEAD になっている。origin/main などリモートのブランチを起点にする
unknown revision 'origin/HEAD'git init と git remote add で作ったリポジトリには origin/HEAD がない。--rev origin/main のようにブランチ名を指定するか、git remote set-head origin -a を実行する
履歴が数件しかない浅いクローン(--depth)。git fetch --unshallow を実行する
detected dubious ownershipフォルダーの所有者が実行ユーザーと違う(ネットワークドライブや他人が作ったフォルダー)。信頼できる場所なら git config --global --add safe.directory パス で許可する
日本語のメッセージが化ける、UnicodeDecodeErrorsubprocess.run に encoding="utf-8" を指定していない
git が見つからないGit がインストールされていない、または PATH が通っていない。インストール後にターミナルを開き直す

✅ 次の記事では…

PART 06 からは Excel VBA に移る。まずは REST API を呼び、ボタン1つでコミット履歴をシートに展開するマクロを作る。

→ PART 06 — Excel VBAでREST APIを呼ぶ へ