ローカル方式の流れ
ローカル方式は、次の3段階で進む。
- クローン:
git cloneでリポジトリを手元に複製する(最初の1回だけ) - 更新:
git fetchで、前回以降に GitHub に追加された履歴を取り込む - 取得:
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 / %h | SHA(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 として保存する。標準ライブラリだけで動く。
"""ローカルクローンの 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"""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}")| 取りたいもの | GitPython | git log のプレースホルダー |
|---|---|---|
| SHA | c.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 パス で許可する |
日本語のメッセージが化ける、UnicodeDecodeError | subprocess.run に encoding="utf-8" を指定していない |
git が見つからない | Git がインストールされていない、または PATH が通っていない。インストール後にターミナルを開き直す |
✅ 次の記事では…
PART 06 からは Excel VBA に移る。まずは REST API を呼び、ボタン1つでコミット履歴をシートに展開するマクロを作る。