【Git】submodule完全ガイド｜内部構造・detached HEAD回避・CI/CD認証・Dependabot自動バンプ・ベストプラクティス15則

Q1: そのコードは公開可能？
   YES → npm/pip/cargoで配布（パッケージ化）
   NO  → Q2

Q2: 同じ組織内のコード？
   YES → monorepo（Turborepo / Nx / pnpm workspace）
   NO  → Q3

Q3: 参照先の履歴を取り込みたい？
   YES → subtree（履歴統合、cloneしやすい）
   NO  → submodule（特定コミット固定、軽量）

親リポジトリ/
├── .gitmodules            ← URL/path設定（追跡対象）
├── libs/
│   └── lib/               ← サブモジュールの作業ツリー
│       └── .git           ← ファイル（.git/modules/libs/libへのポインタ）
├── .git/
│   ├── config             ← url上書き（個人用）
│   └── modules/           ← サブモジュールの実態（.git配下）
│       └── libs/lib/      ← ここに HEAD, refs, objectsが入る

そして親のindex/treeには:
  gitlink: libs/lib → コミットSHA (160000 モード)
  = "このパスは<他リポ>のこのコミットを指す"という情報のみ記録

# 標準：HEADを参照して固定
git submodule add https://github.com/example/lib.git libs/lib

# 特定ブランチを追跡する設定付き
git submodule add -b main https://github.com/example/lib.git libs/lib

# 浅いクローンで追加（CIで履歴が不要な場合）
git submodule add --depth 1 https://github.com/example/lib.git libs/lib

# ブランチ設定は後からも変更可能（.gitmodulesを編集＋sync）
git config -f .gitmodules submodule.libs/lib.branch main
git submodule sync libs/lib

# 追加の最後にcommitするのを忘れない
git add .gitmodules libs/lib
git commit -m "chore: add submodule libs/lib"

# 一番簡単：cloneと同時に再帰取得
git clone --recurse-submodules https://github.com/org/app.git

# 短縮（--recurseは同義の省略）
git clone --recurse https://github.com/org/app.git

# 既にclone済みなら初期化＋取得
git submodule update --init --recursive

# 浅いクローン（履歴節約、CI向き）
git clone --recurse-submodules --shallow-submodules https://github.com/org/app.git

# 親と子の両方を--depth 1
git clone --depth 1 --recurse-submodules --shallow-submodules https://github.com/org/app.git

# 特定のsubmoduleだけ取得
git submodule update --init libs/lib

# 並列取得でクローン高速化
git submodule update --init --recursive --jobs 8

# グローバル設定（すべてのリポで有効）
git config --global submodule.recurse true

# これで以下のコマンドが自動的に--recursive相当になる:
# - git pull
# - git checkout
# - git reset
# - git switch
# - git rebase

# クローン時は別オプション（これだけは都度必要）
git config --global clone.recurseSubmodules true

# .gitmodules にbranch設定
[submodule "libs/lib"]
  path = libs/lib
  url = https://github.com/example/lib.git
  branch = main

# submodule側で追随最新を取得（親のSHAは更新される）
git submodule update --remote --recursive

# 更新内容を親にコミット（"新しいSHAを指せ"という差分）
git add libs/lib
git commit -m "chore: bump libs/lib to latest main"

# ① submoduleへ移動（またはgit -Cで省略）
cd libs/lib

# ② submodule内で通常のGit操作
git checkout main       # ← detached HEAD回避！（超重要）
git pull origin main

# （あるいは特定のバージョンタグに固定）
git fetch --tags
git checkout v2.0.0

cd ../..

# ③ 親にはポインタ（gitlink）変更が出る
git status
# modified:   libs/lib (new commits)

# ④ 親側に参照SHAをコミット
git add libs/lib
git commit -m "chore: bump libs/lib to v2.0.0"

# ⑤ push（submoduleもpush済みか確認済みなら）
git push

# submodule内で常にブランチへ移動
cd libs/lib
git checkout main   # または trunk, develop

# 作業してcommit→push
echo "change" >> file.txt
git add file.txt
git commit -m "feat: 新機能"
git push origin main

# submoduleが未pushだとwarn or fail
git config push.recurseSubmodules check

# さらに親push時に自動でsubmoduleもpush
git config push.recurseSubmodules on-demand

# 失敗を無視（非推奨）
git config push.recurseSubmodules no

# 現在のsubmodule状態を一覧
git submodule status
#  a1b2c3d libs/lib (v2.0.0)
# +d4e5f6c libs/lib2 (heads/main)   ← "+"は未コミット変更あり
# -9a8b7c6 libs/lib3                 ← "-"は未初期化
# Uxxxxxxx libs/lib4                 ← "U"はマージ競合

# 親との差分サマリー（追加・削除コミット数）
git submodule summary

# 特定submoduleだけ
git submodule summary libs/lib

# git diff でsubmoduleの詳細を表示する設定
git config --global diff.submodule log
git diff
# Submodule libs/lib a1b2c3d..d4e5f6c:
#   > feat: 新機能
#   > fix: バグ修正

# 全submoduleで最新のmainに追随
git submodule foreach 'git checkout main && git pull'

# 再帰的に（ネストしたsubmodule含む）
git submodule foreach --recursive 'git fetch --tags'

# 全submoduleの現在ブランチを表示
git submodule foreach 'echo "$name: $(git branch --show-current)"'

# 全submoduleでクリーンアップ
git submodule foreach --recursive 'git clean -fdx'

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout with submodules
        uses: actions/checkout@v4
        with:
          submodules: recursive      # または true（1階層のみ）
          fetch-depth: 0             # タグ・履歴を全取得（必要な時）

      - name: Build
        run: npm ci && npm run build

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout with private submodules
        uses: actions/checkout@v4
        with:
          submodules: recursive
          token: ${{ secrets.SUBMODULE_PAT }}
          # SUBMODULE_PATは repo:read スコープ付きのPAT
          # Settingsの Secrets に事前登録

# 1. ssh-keygenでキー生成
ssh-keygen -t ed25519 -C "ci-submodule-key" -f submodule_deploy_key -N ""

# 2. submodule側のGitHub Settings → Deploy keys に公開鍵を追加

# 3. 親リポのSecrets に SSH_PRIVATE_KEY として秘密鍵を登録

# 4. ワークフローでSSH認証を設定
- uses: webfactory/ssh-agent@v0.9.0
  with:
    ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

- uses: actions/checkout@v4
  with:
    submodules: recursive

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - name: Shallow submodule
        run: |
          git config submodule.recurse true
          git submodule update --init --recursive --depth 1

version: 2
updates:
  - package-ecosystem: "gitsubmodule"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
    labels:
      - "dependencies"
      - "submodule"
    reviewers:
      - "your-org/maintainers"
    commit-message:
      prefix: "chore"
      include: "scope"

# ① deinit で初期化解除
git submodule deinit -f libs/lib

# ② git rm で作業ツリーと.gitmodulesから削除
git rm -f libs/lib

# ③ .git/modules/libs/lib のゴミを削除（最も忘れがち）
rm -rf .git/modules/libs/lib

# ④ コミット
git commit -m "chore: remove submodule libs/lib"

# ① 作業ツリーを新しいパスへmove
git mv libs/lib vendor/lib

# ② .gitmodulesを編集（pathエントリを修正）
# (通常はgit mvが自動で直してくれる)

# ③ .git/modules/ の内部パスを更新
git submodule sync

# ④ コミット
git add .gitmodules vendor/lib
git commit -m "chore: rename submodule libs/lib to vendor/lib"

## Submodule運用ルール

### clone
- `git clone --recurse-submodules <url>` を標準とする
- 既にclone済みなら `git submodule update --init --recursive`

### グローバル設定（各自1回）
- `git config --global submodule.recurse true`
- `git config --global push.recurseSubmodules check`
- `git config --global diff.submodule log`

### submodule内での作業
- 作業前に必ず `git checkout <branch>`（detached HEAD禁止）
- submodule内でcommit → push
- 親で `git add <path>` → commit → push

### 更新の責任
- submoduleを触ったPRは必ず親のポインタ更新もセットでmerge
- 本番リリース用は必ずタグ指定（SHA直指定も可）

### 禁止
- 本番CI/CDで `submodule update --remote` を実行
- 3階層以上のネスト
- submoduleを `rm -rf` で直接削除（.git/modules/残骸問題）