Перейти до вмісту

Підмодулі

Переглянути як 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";
    }
}

Об’єкт значення підмодуля

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 — це записи дерева з режимом 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, виконується таке:

  1. Створюється порожній каталог .git/modules/<name>/
  2. Створюється каталог шляху підмодуля, якщо його ще немає
  3. У .git/config записуються submodule.<name>.active = true та submodule.<name>.url

Ця операція нічого не завантажує й не отримує, а також не записує файл .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";