# 子模块

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 条目

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）。带有方案（`https://...`）的 URL 会抛出 `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";
```