Pythonでゼロから最小限のGitクライアントを自作する:オブジェクトデータベースを完全理解

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

クイックスタート(5分)

昨年、私たちのチームは120の社内マイクロサービスにまたがるバージョン管理された監査ログを追跡する必要がありました。しかし、標準のGit CLIサブプロセスを実行すると顕著なオーバーヘッドが発生し、ログの書き込みごとに新しいプロセスを生成するため、スループットは毎秒およそ45回に制限されてしまいました。

そこで私たちは、シェルコマンドの呼び出しを、オブジェクトデータベースと直接やり取りする軽量な自社製Pythonエンジンに置き換えました。CLIの高レベルコマンド(Porcelain)を取り払えば、エレガントなコンテンツアドレス指定のKey-Valueストアが現れます。実際に動作するオブジェクト書き込み処理は、わずか30行未満のコードで構築できます。

すべてのGitオブジェクトは、[type] [size]\0[content]というシンプルなヘッダーから始まります。Gitはこの組み合わせをSHA-1でハッシュ化し、zlibを使ってDEFLATE圧縮します。以下は、Pythonの標準ライブラリのみを使用して有効なGitのBlobを書き込む方法です:

import hashlib
import os
import zlib

def write_blob(data: bytes, repo_root: str = ".git") -> str:
    # Gitオブジェクトのフォーマット: "blob <size>\0<payload>"
    header = f"blob {len(data)}\x00".encode("ascii")
    store = header + data
    sha = hashlib.sha1(store).hexdigest()
    
    # オブジェクトは .git/objects/<先頭2文字Hex>/<残り38文字Hex> に保存される
    obj_dir = os.path.join(repo_root, "objects", sha[:2])
    obj_path = os.path.join(obj_dir, sha[2:])
    
    os.makedirs(obj_dir, exist_ok=True)
    if not os.path.exists(obj_path):
        with open(obj_path, "wb") as f:
            f.write(zlib.compress(store))
    return sha

if __name__ == "__main__":
    payload = b"Hello, reproducible storage!\n"
    sha = write_blob(payload)
    print(f"Blobを作成しました: {sha}")

これをテストするには、空のリポジトリを初期化してスクリプトを実行します:

git init test-repo
cd test-repo
python3 ../write_blob.py
# 出力: Blobを作成しました: 7421375fdca039b5fae5ffeb68ad65190a4dfb67

git cat-file -p 7421375fdca039b5fae5ffeb68ad65190a4dfb67
# 出力: Hello, reproducible storage!

ネイティブのgitコマンドでオブジェクトを問題なく検査できます。これが機能するのは、作成したスクリプトがGitのディスク上のバイナリフォーマットに完全に準拠しているためです。

詳細解説:Blob、Tree、Commit

Gitは有向非巡回グラフ(DAG)を使用してリビジョン履歴を管理します。その基礎は、blob、tree、commit、tagという4つの主要なオブジェクトタイプで構成されています。コアとなるストレージの仕組みは、実質的に最初の3つに依存しています。

1. Blob:純粋なデータペイロード

Blobは、メタデータとは完全に切り離された生のファイルコンテンツを保存します。ディレクトリ名、更新日時、実行権限などの情報は一切保持しません。たとえば、まったく同一の12MBのバイナリファイルを5つの異なるディレクトリにコピーしたとします。Gitはそのファイルのペイロードをディスクに1回だけ書き込みます。同一のペイロードはまったく同じSHA-1ハッシュを共有するため、コンテンツの重複排除が自動的に行われるのです。

2. Tree:ディレクトリ構造と権限

Treeは、ディレクトリの階層構造やファイルモードを対応するハッシュにマッピングします。各Treeレコードは以下のバイナリ構造に従います:

[8進数ASCII表記のモード] [半角スペース] [ファイル名]\0[20バイトバイナリSHA-1]

重要な違いに注目してください。Treeレコードでは、ハッシュが40文字の16進数文字列ではなく、生の20バイトバイナリスライスとして保存されます。また、ディレクトリのモードは先頭にゼロを付けず、40000として保存される点にも留意してください。以下は、Treeオブジェクトを組み立てるPython関数です:

def create_tree_entry(mode: str, path: str, sha_hex: str) -> bytes:
    # 標準的なモード: "100644" (通常ファイル), "100755" (実行可能ファイル), "40000" (Tree/ディレクトリ)
    sha_bytes = bytes.fromhex(sha_hex)
    return f"{mode} {path}\x00".encode("utf-8") + sha_bytes

def write_tree(entries: list[tuple[str, str, str]], repo_root: str = ".git") -> str:
    # Gitではエントリが名前順にソートされている必要があります。ディレクトリは末尾に '/' が付いているものとしてソートされます
    def sort_key(entry):
        mode, path, _ = entry
        return path + "/" if mode == "40000" else path

    sorted_entries = sorted(entries, key=sort_key)
    payload = b"".join(create_tree_entry(m, p, s) for m, p, s in sorted_entries)
    header = f"tree {len(payload)}\x00".encode("ascii")
    store = header + payload
    sha = hashlib.sha1(store).hexdigest()
    
    obj_dir = os.path.join(repo_root, "objects", sha[:2])
    obj_path = os.path.join(obj_dir, sha[2:])
    os.makedirs(obj_dir, exist_ok=True)
    if not os.path.exists(obj_path):
        with open(obj_path, "wb") as f:
            f.write(zlib.compress(store))
    return sha

3. Commit:メタデータのラッパー

Commitは、スナップショットであるTreeを、作成者(author)、コミッターのタイムスタンプ、任意の親コミット(parent)、およびメッセージと結び付けます。ペイロードは構造化されたプレーンテキストです:

import time

def write_commit(tree_sha: str, parent_sha: str | None, message: str, repo_root: str = ".git") -> str:
    timestamp = int(time.time())
    timezone = "+0000"
    author_str = f"Engineer <[email protected]> {timestamp} {timezone}"
    
    lines = [f"tree {tree_sha}"]
    if parent_sha:
        lines.append(f"parent {parent_sha}")
    lines.append(f"author {author_str}")
    lines.append(f"committer {author_str}")
    lines.append("")
    lines.append(message.strip() + "\n")
    
    payload = "\n".join(lines).encode("utf-8")
    header = f"commit {len(payload)}\x00".encode("ascii")
    store = header + payload
    sha = hashlib.sha1(store).hexdigest()
    
    obj_dir = os.path.join(repo_root, "objects", sha[:2])
    os.makedirs(obj_dir, exist_ok=True)
    obj_path = os.path.join(obj_dir, sha[2:])
    if not os.path.exists(obj_path):
        with open(obj_path, "wb") as f:
            f.write(zlib.compress(store))
    return sha

応用編:参照の管理とグラフ走査

イミュータブル(不変)なオブジェクトはデータの完全性を保証します。しかし、それらのオブジェクト間を移動するには、ブランチやHEADといったミュータブル(可変)なポインタが必要です。

HEADとブランチ参照の更新

ブランチは複雑なデータ構造ではありません。40文字のコミットハッシュとそれに続く改行を含む、単純なテキストファイルにすぎません。また、HEADファイルには通常、現在アクティブなブランチファイルを指すシンボリック参照が含まれています:

def update_branch(branch_name: str, commit_sha: str, repo_root: str = ".git"):
    ref_path = os.path.join(repo_root, "refs", "heads", branch_name)
    os.makedirs(os.path.dirname(ref_path), exist_ok=True)
    with open(ref_path, "w") as f:
        f.write(f"{commit_sha}\n")

def set_symbolic_head(branch_name: str, repo_root: str = ".git"):
    head_path = os.path.join(repo_root, "HEAD")
    with open(head_path, "w") as f:
        f.write(f"ref: refs/heads/{branch_name}\n")

コミットグラフの走査

外部のGitバイナリを実行することなく、リビジョン履歴を遡ることができます。起点となるコミットを読み込み、そのparentフィールドを抽出して後方へ反復処理を行います:

def read_object(sha: str, repo_root: str = ".git") -> tuple[str, bytes]:
    path = os.path.join(repo_root, "objects", sha[:2], sha[2:])
    with open(path, "rb") as f:
        decompressed = zlib.decompress(f.read())
    header_end = decompressed.index(b"\x00")
    header = decompressed[:header_end].decode("ascii")
    obj_type, _ = header.split(" ")
    return obj_type, decompressed[header_end + 1:]

def log_history(start_commit_sha: str, repo_root: str = ".git"):
    curr = start_commit_sha
    while curr:
        _, payload = read_object(curr, repo_root)
        lines = payload.decode("utf-8", errors="replace").splitlines()
        parent = None
        message = []
        in_msg = False
        
        for line in lines:
            if in_msg:
                message.append(line)
            elif line.startswith("parent "):
                parent = line.split(" ", 1)[1]
            elif line == "":
                in_msg = True
                
        print(f"commit {curr}")
        print(f"    {chr(10).join(message)}\n")
        curr = parent

実践的なTips

並行処理が行われる環境下でGitリポジトリに直接書き込みを行うと、チュートリアルでは滅多に言及されない特有の課題が見えてきます:

  • アトミックなリネームを使用する:.git/objects/xx/yyへ直接ストリーム書き込みを行ってはいけません。並行して読み込みが発生した場合、書き込み途中の不完全なファイルを読み取ってしまい、corrupt loose objectエラーでクラッシュします。まず.git/objects/内に一時ファイルを作成して書き込み、その後os.replace()を使ってアトミックに置き換えてください。
  • 正規のTreeモードを遵守する:通常ファイルには100644、実行可能ファイルには100755を使用します。ディレクトリには先頭にゼロを付けない40000が必要です。040000を渡すと、git fsck --strictを実行した際にTreeが不正と判定され拒絶されます。
  • ディレクトリのinode枯渇に注意する:Linuxファイルシステム(ext4/xfs)では、ルーズオブジェクト(loose object)1つにつき1つのinodeを消費します。パック処理を行わずに一括インポートで50万個のオブジェクトを書き込むと、ディスク容量が残っていてもディスクのinodeが枯渇する恐れがあります。大規模なバッチ取り込みを実行する際は、定期的にgit repack -dやgit gc --prune=nowを実行してください。
  • Treeエントリを慎重にソートする:GitのTree比較では厳格なソート順が求められます。サブツリーのエントリは、パスの末尾に明示的なスラッシュが付いているかのようにソートする必要があります(例:foo/とfoo.txt)。標準的なPythonの文字列比較で名前をソートすると、不正な順序のTreeが生成され、Gitの検証チェックでエラーになる可能性があります。
Share: