Saltar al contenido

Submódulos

Ver como Markdown Editar en GitHub Documentación de bfe242f

Git Los submódulos insertan un repositorio dentro de otro. En el árbol principal, un submódulo se representa como una entrada gitlink (modo 160000) que apunta a una confirmación específica del repositorio del submódulo. El URL y la ruta del submódulo se declaran en el archivo .gitmodules.

Conceptos

En el árbol del repositorio principal:

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

La entrada gitlink registra qué confirmación del submódulo debe extraerse. El repositorio real del submódulo se encuentra en .git/modules/<name>/.

SubmoduleManager

PHP
use Pitmaster\Submodule\SubmoduleManager;

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

Enumerar submódulos

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";
    }
}

Objeto de valor de submódulo

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)

Analizar .gitmodules

El archivo .gitmodules declara la configuración del submódulo:

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";
}

El analizador admite:

  • Encabezados de sección: [submodule "<name>"]
  • Pares clave-valor: path = ..., url = ..., branch = ...
  • Comentarios (líneas que empiezan con #)
  • Espacios en blanco e indentación

Se omiten las entradas que no incluyen tanto path como url. Los valores no se desentrecomillan.

Las entradas gitlink son entradas del árbol con modo 160000. Apuntan a una confirmación (no a un árbol ni a un blob) del repositorio del submódulo.

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

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

Detección de TreeEntry

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

Inicializar submódulos

PHP
$manager->init();

Para cada submódulo declarado en .gitmodules, esta función:

  1. Crea un directorio .git/modules/<name>/ vacío
  2. Crea el directorio de la ruta del submódulo si no existe
  3. Registra submodule.<name>.active = true y submodule.<name>.url en .git/config

No obtiene ni extrae nada, y tampoco escribe el archivo .git del submódulo.

Actualizar submódulos

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

Para cada submódulo fijado en el árbol indicado, update() copia el directorio git del repositorio de origen en .git/modules/<name>/, reemplaza los archivos de trabajo del submódulo por los del origen, escribe el archivo .git que apunta al directorio del módulo, establece core.worktree y separa HEAD en la confirmación fijada.

El URL del submódulo debe ser una ruta local: absoluta o relativa al árbol de trabajo principal (git resuelve las URL relativas con respecto al URL remoto del principal). Un URL con esquema (https://...) genera RuntimeException('Submodule update currently supports only local paths: ...').

Después de una actualización, puedes abrir cada submódulo como un repositorio independiente:

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

Comprobar las confirmaciones fijadas

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

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

El método pinnedCommit() recorre la jerarquía del árbol para encontrar la entrada gitlink en la ruta indicada y devuelve el hash de la confirmación de destino.

Estado del submódulo

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";
}

Campos de estado:

  • name: nombre del submódulo
  • path: ruta en el árbol de trabajo
  • expected: hash de la confirmación fijada en el árbol principal (null si no existe)
  • actual: HEAD actual del submódulo (null si no está inicializado)
  • dirty: true cuando se conocen ambas confirmaciones y son distintas. No se comprueban los cambios dentro del árbol de trabajo del submódulo.

Estructura de directorios

Código
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

Flujo de trabajo con submódulos

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";