サブモジュール

Markdownとして表示 GitHubで編集ドキュメント: bfe242f

Gitサブモジュールを使うと、あるリポジトリ内に別のリポジトリを埋め込めます。親のツリーでは、サブモジュールはgitlinkエントリー（モード160000）として表され、サブモジュールリポジトリ内の特定のコミットを参照します。サブモジュールのURLとパスは.gitmodulesファイルで宣言されます。

概念

親リポジトリのツリーでは、次のようになります。

コード

100644 blob abc123...  README.md
040000 tree def456...  src/
160000 commit 789012... lib/external    <-- gitlink entry (submodule)

gitlinkエントリーには、サブモジュールでチェックアウトするコミットが記録されます。実際のサブモジュールリポジトリは.git/modules/<name>/にあります。

SubmoduleManager

PHP

use Pitmaster\Submodule\SubmoduleManager;

$manager = new SubmoduleManager(
    $repo->objectDatabase(),
    $repo->workDir(),
    $repo->gitDir(),
);

サブモジュールの一覧表示

PHP

$submodules = $manager->list();

foreach ($submodules as $sub) {
    echo "{$sub->name}: {$sub->url} at {$sub->path}\n";
    if ($sub->branch !== null) {
        echo "  tracks branch: {$sub->branch}\n";
    }
}

Submodule値オブジェクト

PHP

use Pitmaster\Submodule\Submodule;

$sub->name;     // Submodule name (from .gitmodules section header)
$sub->path;     // Path in the working tree
$sub->url;      // Remote URL
$sub->branch;   // Tracked branch (nullable)

.gitmodulesの解析

.gitmodulesファイルにはサブモジュールの設定が宣言されています。

Ini

[submodule "lib/external"]
    path = lib/external
    url = https://github.com/vendor/lib.git
    branch = main

[submodule "tools/helper"]
    path = tools/helper
    url = https://github.com/vendor/helper.git

PHP

$content = file_get_contents('.gitmodules');
$submodules = SubmoduleManager::parseGitmodules($content);

foreach ($submodules as $sub) {
    echo "{$sub->name} -> {$sub->url}\n";
}

パーサーは次の形式に対応しています。

セクションヘッダー: [submodule "<name>"]
キーと値のペア: path = ...、url = ...、branch = ...
コメント（#で始まる行）
空白とインデント

pathとurlの両方がないエントリーはスキップされます。値の引用符は除去されません。

Gitlinkエントリー

Gitlinkエントリーはモード160000のツリーエントリーです。サブモジュールリポジトリ内のコミットを参照します（ツリーやblobは参照しません）。

PHP

$tree = $repo->readObject($treeHash);

foreach ($tree->entries as $entry) {
    if ($entry->isGitlink()) {
        echo "Submodule at {$entry->name}: commit {$entry->hash->hex}\n";
    }
}

TreeEntryの検出

PHP

$entry->isGitlink();  // true if mode is '160000'
$entry->mode;         // '160000'

サブモジュールの初期化

PHP

$manager->init();

.gitmodulesで宣言された各サブモジュールについて、次の処理を行います。

空の.git/modules/<name>/ディレクトリを作成する
存在しない場合はサブモジュールのパス用ディレクトリを作成する
submodule.<name>.active = trueとsubmodule.<name>.urlを.git/configに記録する

フェッチもチェックアウトも行わず、サブモジュールの.gitファイルも書き込みません。

サブモジュールの更新

PHP

$manager->update($repo->head()->tree);

指定されたツリーで固定されている各サブモジュールについて、update()はソースリポジトリのgitディレクトリを.git/modules/<name>/にコピーし、サブモジュールの作業ファイルをソースの内容に置き換え、モジュールディレクトリを指す.gitファイルを書き込み、core.worktreeを設定して、固定されたコミットでHEADをデタッチします。

サブモジュールのURLはローカルパスである必要があります。絶対パス、または親の作業ツリーからの相対パスを指定してください（gitでは相対URLを親のリモートURLに対して解決します）。スキームを含むURL（https://...）を指定するとRuntimeException('Submodule update currently supports only local paths: ...')がスローされます。

更新後は、各サブモジュールを独立したリポジトリとして開けます。

PHP

$subRepo = Pitmaster::open($repo->workDir() . '/lib/external');

固定されたコミットの確認

PHP

$headCommit = $repo->head();
$pinnedId = $manager->pinnedCommit('lib/external', $headCommit->tree);

if ($pinnedId !== null) {
    echo "lib/external is pinned to commit {$pinnedId->hex}\n";
}

pinnedCommit()メソッドはツリー階層をたどり、指定パスのgitlinkエントリーを見つけて、参照先のコミットハッシュを返します。

サブモジュールのステータス

PHP

$headCommit = $repo->head();
$statuses = $manager->status($headCommit->tree);

foreach ($statuses as $status) {
    $expected = $status['expected'] ?? 'not pinned';
    $actual = $status['actual'] ?? 'not initialized';
    $dirty = $status['dirty'] ? ' (dirty)' : '';

    echo "{$status['name']}: expected={$expected}, actual={$actual}{$dirty}\n";
}

ステータスのフィールド:

name: サブモジュール名
path: 作業ツリー内のパス
expected: 親ツリーで固定されたコミットハッシュ（存在しない場合はnull）
actual: サブモジュールの現在のHEAD（未初期化の場合はnull）
dirty: 両方のコミットが判明していて異なる場合はtrue。サブモジュールの作業ツリー内の変更は確認されません。

ディレクトリ構成

コード

project/
  .git/
    modules/
      lib/
        external/          # Submodule's actual git directory (.git/modules/<name>)
        HEAD
        objects/
        refs/
        ...
  .gitmodules              # Submodule declarations
  lib/
    external/
      .git                 # File: "gitdir: ../../.git/modules/lib/external"
      src/
      README.md
  src/
  README.md

サブモジュールのワークフロー

PHP

// 1. Open the parent repo
$repo = Pitmaster::open('/path/to/project');

// 2. List submodules
$manager = new SubmoduleManager(
    $repo->objectDatabase(),
    $repo->workDir(),
    $repo->gitDir(),
);

$submodules = $manager->list();

// 3. Populate the submodules pinned at HEAD (local source paths only)
$manager->update($repo->head()->tree);

// 4. Check status
$statuses = $manager->status($repo->head()->tree);

// 5. Open a submodule as its own repo
$subRepo = Pitmaster::open($repo->workDir() . '/lib/external');
$subHead = $subRepo->head();
echo "Submodule HEAD: {$subHead->id->hex}\n";