git-submodule

Git サブモジュール

このスキルは、リポジトリにおけるGit サブモジュールの選択と運用ワークフローの基点として使用します。

目的は、すべての git submodule コマンドを一度に並べることではありません。目的は次のとおりです。

1. サブモジュールが適切な境界かどうかを判断する
2. 運用モードを1つ選ぶ
3. 固定コミット、detached HEAD、ホスティングプラットフォームでの影響を明示する
4. そのモードで次に安全なコマンドだけを提示する

まず references/decision-matrix.md を読んでください。 ポインターの更新、detached HEAD、またはサブモジュール内での編集が依頼に含まれる場合は、references/update-and-detached-head.md を読んでください。 CI／ブートストラップでの要件については、references/ci-and-automation.md を読んでください。 モード別のコマンド一式と GitHub Pages／URL の変化に関する制約については、references/mode-packets-and-hosted-constraints.md を読んでください。

ユーザーが主に必要としているものが次の場合は、該当するスキルを使用してください。

• ローカルブランチ／履歴の整理、リベース、競合の復旧、プッシュの安全性 → git-workflow
• Git の参照、tarball、ワークスペース、または先に公開するフローを使った Node パッケージの配布 → npm-git-install
• サブモジュールの仕組みを超えるリポジトリのブートストラップ／タスクランナーの自動化 → deployment-automation
• より広範な環境またはコンテナーのセットアップ → system-environment-setup

このスキルを使用する場合

• git submodule add で外部リポジトリをプロジェクトに追加する
• すでにサブモジュールを含むリポジトリをクローンまたは初期化する
• サブモジュールをスーパープロジェクトに記録されたコミットに戻して同期する
• サブモジュールを追跡対象のリモートブランチまで進め、新しいポインターをコミットする
• detached HEAD に戸惑わずにサブモジュール内で作業する
• サブモジュールを適切に削除する
• プライベートなサブモジュールを含め、サブモジュールを取得するよう GitHub Actions やその他の CI を設定する
• GitHub Pages でのパブリックサブモジュールの制限など、ホスティングプラットフォームの制約を確認する
• サブモジュール、サブツリー、ベンダーへの取り込み、パッケージ配布のどれが適切か判断する

このスキルを使用しない場合

• 主な問題が通常の Git での共同作業、リベース、または履歴の修復である
• 依存関係にはパッケージマネージャー／レジストリの成果物を使用するべきである
• タスクがサブモジュールの仕組みではなく、より広範なリポジトリのブートストラップ自動化に関するものである
• サブモジュールのチェックアウト／公開範囲の制約とは無関係に、ホストされたリポジトリの管理を依頼されている
• ユーザーが、1つのサブモジュールの状況に応じた次の安全な手順ではなく、膨大な Git チュートリアルを求めている

手順

ステップ 1：依頼を整理する

まず、依頼を次の形式でまとめます。

submodule_intake:
  current_goal: decide-boundary | add | bootstrap | sync-to-pinned-commit | advance-tracked-branch | edit-inside-submodule | remove | ci-checkout | hosted-constraint | unknown
  repo_role: superproject-consumer | submodule-maintainer | both | unknown
  dependency_shape: external-repo | vendor-copy | subtree-candidate | package-candidate | unknown
  submodule_state: absent | present-uninitialized | present-detached-head | present-on-branch | pointer-needs-update | unknown
  update_intent: none | match-recorded-commit | move-to-new-upstream-commit | develop-and-push-submodule | unknown
  ci_context: none | github-actions | other-ci | github-pages | unknown
  auth_context: public | private-ssh | private-token | unknown
  collaboration_risk: solo | shared | unknown
  confidence: high | medium | low

コンテキストが不完全な場合は、最も安全なデフォルトを明示してください。

ステップ 2：サブモジュールが適切なツールか判断する

コマンドを提示する前に、次の点に答えてください。

• このリポジトリ内に独立した上流の Git 履歴が必要ですか？
• 本当に必要なのは正確なコミットの固定ですか？
• チームは再帰的なクローン／ブートストラップと CI のチェックアウト設定を許容できますか？
• 依存関係は、サブツリー、ベンダーとして取り込んだスナップショット、または公開済みパッケージのほうに近いですか？

答えが「そうではない」場合は、サブモジュールを無理に使用せず、別の方法に切り替えてください。

ステップ 3：主モードを1つだけ選ぶ

今回の実行で主モードを1つ選びます。

1. 境界の判断
2. 追加してコミットを固定
3. ブートストラップしてクローン
4. 固定コミットに同期
5. 追跡対象ブランチを進める
6. サブモジュール内で編集
7. 削除してクリーンアップ
8. CI チェックアウト
9. ホスティング上の制約

GitHub Pages のパブリック限定サブモジュールや古いサブモジュール URL 形式などのプラットフォーム規則によってユーザーがブロックされている場合は、通常のローカル Git の使い方ではなく hosted-constraint を使用してください。

ステップ 4：オペレーターが把握しておくべき不変の事実を明示する

次の事実は、どのような回答でも必ず維持してください。

• スーパープロジェクトがサブモジュールを記録するのは「最新ブランチ」ではなく、コミットです。
• git submodule update は通常、記録されたコミットを復元するため、サブモジュールがデタッチ状態の HEAD になることがあります。
• .gitmodules は契約の一部です。update --remote を想定している場合、ブランチを追跡する意図はここに記述します。
• サブモジュールのコミットは、サブモジュールのパスをステージして、スーパープロジェクト側でコミットするまで、スーパープロジェクトに反映されません。
• リポジトリがサブモジュールに依存している場合、再帰的なブートストラップの手順はオンボーディングと自動化のドキュメントに記載します。
• ホスティングプラットフォームには、通常のローカル Git の使用では判明しない、可視性、URL、認証に関する制約が追加されることがあります。

ステップ 5：サブモジュールの概要を作成する

次の構成をそのまま返します。

# Git Submodule Brief

## Recommended mode
- Mode: boundary decision | add-and-pin | bootstrap-and-clone | sync-to-pinned-commit | advance-tracked-branch | edit-inside-submodule | remove-and-cleanup | ci-checkout | hosted-constraint
- Why this mode fits: ...

## Current state
- Superproject goal: ...
- Submodule state: ...
- Auth / CI / hosted context: ...
- Collaboration risk: solo | shared | unknown
- Confidence: high | medium | low

## Safest next move
1. ...
2. ...
3. ...

## Commands
```bash
...

注意事項

• ...
• ...

ポインター／ブランチに関する影響

• ...

関連する引き継ぎ先

• git-workflow：...の場合
• npm-git-install：...の場合
• deployment-automation：...の場合

### Step 6: Use the mode packets, not a giant improvised command dump
Pull the exact packet from [references/mode-packets-and-hosted-constraints.md](references/mode-packets-and-hosted-constraints.md).

Rules:
- `boundary decision` should compare submodule with subtree / vendoring / package delivery directly.
- `bootstrap-and-clone` and `sync-to-pinned-commit` must preserve the difference between **restore recorded state** and **upgrade pointer**.
- `advance-tracked-branch` must make branch intent explicit and commit the resulting pointer update in the superproject.
- `edit-inside-submodule` must avoid detached-`HEAD` commit loss.
- `ci-checkout` must make private-submodule auth explicit.
- `hosted-constraint` must call out public-only or URL-form restrictions instead of pretending hosted builds will authenticate like a local clone.

## Output format
Return a short operator-style **Git Submodule Brief**.

Required qualities:
- pick one workflow mode
- say whether submodule is actually the right tool
- make detached-`HEAD` / pointer consequences explicit
- include CI/auth or hosted-platform notes when relevant
- route away cleanly when the problem belongs to another skill

## Examples

### Example 1: bootstrap after clone
Input: "I cloned the repo and the vendor directory is empty. There's a `.gitmodules` file."
Output: choose `bootstrap-and-clone`, recommend `git submodule update --init --recursive`, explain that this restores the pinned contents rather than upgrading anything, and mention private-auth caveats if applicable.

### Example 2: update a tracked dependency
Input: "We track the main branch of a docs repo as a submodule and want the latest commit."
Output: choose `advance-tracked-branch`, set or confirm `submodule.<name>.branch`, run `git submodule update --remote <path>`, then commit the pointer update in the superproject.

### Example 3: choose boundary
Input: "Should this shared component repo be a submodule or subtree?"
Output: choose `boundary decision`, compare separate-history/pinning needs against clone simplicity, and route to subtree if consumers should not deal with recursive bootstrap.

### Example 4: hosted-platform constraint
Input: "Our GitHub Pages build uses a private docs-theme submodule and keeps failing."
Output: choose `hosted-constraint`, explain the public-`https://` GitHub Pages limitation, and route away from a private-submodule Pages design instead of pretending auth fixes it.

## Best practices
1. Start with the boundary decision, not the command list.
2. Distinguish **match pinned commit** from **advance upstream pointer**.
3. Treat detached `HEAD` as normal-but-important operator state, not as a mysterious Git bug.
4. Keep submodule mechanics separate from generic Git history repair.
5. Make CI checkout, hosted-platform limits, and auth part of the main workflow whenever submodules are involved.

## References
- [Git Book: Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
- [git-submodule documentation](https://git-scm.com/docs/git-submodule)
- [Atlassian: Git submodule](https://www.atlassian.com/git/tutorials/git-submodule)
- [Atlassian: Git subtree](https://www.atlassian.com/git/tutorials/git-subtree)
- [GitHub Actions checkout](https://github.com/actions/checkout#checkout-multiple-repos-private)
- [GitHub Pages submodule limitations](https://docs.github.com/en/pages/getting-started-with-github-pages/using-submodules-with-github-pages)