referencegrowing

GitHub リポジトリ複製・組み込み・ブランチ運用の全体マップ

Fork / Template / Clone / Submodule / Subtree / Branch など、GitHub でリポジトリを複製・組み込み・派生させる全機能を一覧比較し、使用シーン・作成削除方法・CI/CD統合・セキュリティ観点・よくある失敗を整理する。

概観

GitHub / Git には「既存リポジトリをベースに何かを始める」機能が多数存在する。それぞれ繋がりの強さ・双方向性・目的が異なるため、選択を誤ると後で運用コスト・セキュリティリスクが跳ね上がる。本記事はその全体像と判断基準、運用の落とし穴までまとめる。


一覧表: 複製・組み込み・派生の全機能

機能レイヤー履歴の繋がりGitHub 表示双方向性主用途
ForkGitHubあり「forked from」双方向(PR可)OSS貢献、実験改変
TemplateGitHubなし「generated from」片方向Starter、ボイラープレート
CloneGitあり(ローカル)なし片方向ローカル作業起点
Import repositoryGitHubありなし片方向他VCSからの移行
Duplicate (mirror push)Gitありなし片方向完全複製、履歴ごと移設
Mirror repositoryGitHubありなし片方向自動バックアップ、多重ホスト
SubmoduleGit参照保持別リポへのリンク付フォルダ独立管理外部リポを子として埋込
SubtreeGit統合普通のフォルダ双方向(複雑)外部リポを本体に取込
SymlinkOS/Git─斜め矢印アイコン片方向参照同一ファイルの別名参照
BranchGit同一リポ内分岐ブランチセレクタ双方向(merge)並行開発、機能分離
WorktreeGit同一リポ複数チェックアウトなし─複数ブランチ同時作業
Package (npm/pip等)配布なしPackages タブ片方向ライブラリ配布
Monorepo (workspaces)構成単一リポ内なし─密結合な複数パッケージ管理
Release / TagGitスナップショットReleases タブ片方向バージョン固定配布
GistGitHub独立ミニリポGist として別領域Fork可スニペット共有

Pugh Matrix: 「他プロジェクトに組み込む」ときの選択

ベースラインを Submodule として、代表的な組み込み手段を比較する。

案導入容易性更新追随性バージョン固定CI複雑度低利用者知識要求少独立配布合計
Baseline (Submodule)0000000
Subtree+00++++-+4
Package (npm等)-++++++++++8
Monorepo—+++-+—-1
Copy & paste++——++++—0

読み取り:

  • Package 化が可能なら最強(+8)。ただしパッケージ化の初期コストが -1
  • 利用者が Git 初心者を含むなら Subtree(+4)
  • Submodule は「厳格なバージョン固定+独立開発」の要件が強い時のみ選ぶ
  • Monorepo は組み込みではなく「そもそも一体管理」の選択肢

判断フローチャート

flowchart TD
Q1{他リポの内容を持ってきたい?}
Q1 -->|No| BR[Branch / Worktreeで十分]
Q1 -->|Yes| Q2{上流にPR送信する?}
Q2 -->|Yes| FORK[Fork]
Q2 -->|No| Q3{履歴を保ちたい?}
Q3 -->|No| TMPL[Template]
Q3 -->|Yes| Q4{独立扱い?子として埋込?}
Q4 -->|独立| CLONE[Clone→新規リポ<br/>or Duplicate]
Q4 -->|子埋込| Q5{パッケージ化可能?}
Q5 -->|Yes| PKG[Package化推奨]
Q5 -->|No| Q6{利用者にGit中級知識あり?}
Q6 -->|Yes| SUB[Submodule]
Q6 -->|No| SUBT[Subtree]

Mermaid 未対応環境ではテキスト版:

Q1: 他リポの内容を持ってきたい?
├─ No → Branch / Worktree
└─ Yes → Q2
Q2: 上流に貢献(PR送信)する?
├─ Yes → Fork
└─ No → Q3
Q3: 履歴・繋がりを保ちたい?
├─ No → Template(スターター用途)
└─ Yes → Q4
Q4: 独立プロジェクト?子として埋込?
├─ 独立 → Clone → 新規リポ or Duplicate
└─ 子埋込 → Q5
Q5: パッケージ化可能?
├─ Yes → Package化を強く推奨
└─ No → Q6
Q6: 利用者に Git 中級知識を要求できる?
├─ Yes → Submodule
└─ No → Subtree

コピーボタン表示のバグあり。閉じてないコードブロックが始めあった。要経過観察: 2026/9/25


各機能の詳細

Fork

目的: 他人のリポジトリを自アカウントに複製し、Pull Request を送る権利を得る。

使用シーン:

  • OSS プロジェクトへのバグ修正・機能追加提案
  • 一時的な実験的改変
  • アーカイブされたプロジェクトの引き継ぎ

他者との関係:

  • 上流(upstream)作者からは fork 数として可視化
  • 誰が fork したかはリスト表示されるが、内部での作業内容は追われない
  • PR を送ると初めて明示的な関与になる

メリット:

  • 上流への還元パスが確立
  • 「Compare」で差分が常に見える

デメリット:

  • 履歴が完全に紐づくため、私的プロジェクトには不向き
  • 上流が消えると fork 側の位置付けが曖昧に
  • ネットワーク上に永続記録される(削除しても検索キャッシュに残る場合あり)

影響範囲: 自アカウント配下に1リポジトリ増える。上流には影響しない。

作り方:

  • Web GUI: 対象リポ右上「Fork」ボタン → 名前確認 → 「Create fork」
  • CLI: gh repo fork owner/repo --clone

消し方:

  • Web GUI: Settings → Danger Zone → Delete this repository
  • CLI: gh repo delete yourname/repo --yes

見分け方: リポ名下に「forked from owner/repo」表記。

CI/CD の落とし穴:

  • Fork からの PR では secrets が渡らない(セキュリティ仕様)
  • pull_request_target イベントを安易に使うと secret 漏洩リスク
  • 対策: 信頼できる contributor の PR のみ label で明示的トリガー

セキュリティ観点:

  • Public fork は元リポが private 化されても 既に fork された内容は残る
  • 機密を含むリポは fork 許可の Organization 設定で制限すべき

よくある失敗:

  • Fork したまま長期放置 → upstream との乖離が大きくなり merge 困難
  • 対策: 定期的に git fetch upstream && git rebase upstream/main

Template

目的: 履歴を切り離した新規リポジトリを、既存構造から生成する。

使用シーン:

  • Astro / Next.js などのスターターテーマ利用
  • 社内標準プロジェクト構成の展開
  • 個人ブログの立ち上げ

他者との関係:

  • 「generated from」表示は残るが、履歴紐付けはない
  • 元テンプレの更新は自動反映されない
  • 作者からは利用者数が把握しにくい

メリット:

  • クリーンな履歴で始められる
  • 元プロジェクトの都合に縛られない
  • 「Include all branches」で全ブランチ複製可能

デメリット:

  • 元テンプレの改善を後から取り込む標準手段がない
  • テンプレ側で「Template repository」設定が必要

作り方:

  • 前提: テンプレ側 Settings → 「Template repository」チェック
  • Web GUI: テンプレリポの「Use this template」→「Create a new repository」
  • CLI: gh repo create myproject --template owner/template-repo

消し方: 通常のリポ削除と同様。

見分け方: リポ名下「generated from owner/template」表記。

セキュリティ観点:

  • テンプレリポに過去コミットで秘密情報が含まれていた場合、履歴は切れるが最新スナップショットに秘密が残っていれば当然引き継がれる
  • Template 化前に git-secrets / trufflehog でスキャン推奨

よくある失敗:

  • Template 化を忘れて Fork を勧めてしまう → 利用者側で forked from 表示が残る
  • 対策: Starter リポは必ず Template 化する

Clone

目的: リモートリポジトリをローカルに複製し、作業環境を作る。

使用シーン: あらゆるローカル開発の起点。

他者との関係: リモートに影響なし。認証情報が残る点のみ注意。

メリット: 全履歴・全ブランチが手元に来る、オフライン作業可能。

デメリット: 大規模リポでは時間・容量を消費。

作り方:

Terminal window
# 通常
git clone https://github.com/owner/repo.git
# 浅いクローン(履歴を最新N件のみ)
git clone --depth 1 https://github.com/owner/repo.git
# submodule も同時取得
git clone --recurse-submodules https://github.com/owner/repo.git
# 特定ブランチのみ
git clone -b branch-name --single-branch https://github.com/owner/repo.git

消し方: フォルダを削除するだけ (rm -rf repo)。

見分け方: .git フォルダの存在。git remote -v で origin URL 確認。

よくある失敗:

  • --depth 1 した shallow clone に対し git rebase や git log --all を実行 → 履歴不足で失敗
  • 対策: git fetch --unshallow で完全履歴に戻す

Import repository

目的: 他の VCS(SVN, Mercurial, TFS)や別ホスティングから GitHub へ移行。

作り方: GitHub Web → 右上 + → 「Import repository」→ 元URL・認証情報を入力。

消し方: 通常のリポ削除。

見分け方: 特別な表示はなし。commit author 履歴で判断。


Duplicate (mirror push)

目的: あるリポジトリの完全な複製(全ブランチ・全タグ)を別リポとして作る。Fork のような紐付けは残らない。

作り方:

Terminal window
git clone --bare https://github.com/owner/original.git
cd original.git
git push --mirror https://github.com/yourname/new-copy.git
cd ..
rm -rf original.git

使用シーン: プロジェクト引き継ぎ、組織移管、履歴保全付きコピー。

見分け方: 特別な表示なし。commit 履歴が丸ごと一致することで判別。

セキュリティ観点: 元リポの全履歴の秘密情報が新リポにも複製される。BFG Repo-Cleaner 等で事前除去を検討。


Mirror repository

目的: 別ホスティング(GitLab等)との自動同期。

作り方: GitHub Actions や外部ツール(例: pixta-dev/repository-mirroring-action)で実装。

使用シーン: 冗長化、社内外での並行公開。


Submodule

目的: 外部リポジトリを「特定コミットへの参照」として親リポに埋め込む。

使用シーン:

  • 共通ライブラリの参照(バージョン固定必須)
  • コードエージェント用ルール集の複数プロジェクト共有
  • ベンダーコードの取り込み

他者との関係:

  • 親リポと子リポは独立管理
  • 子リポの更新は親リポで明示的に「参照コミットを進める」操作が必要

メリット:

  • 子リポの独立性が完全に保たれる
  • バージョン(コミット)が親側で厳格に固定

デメリット:

  • --recurse-submodules を忘れると空フォルダになる
  • CI/CD 設定が煩雑
  • 学習コスト高

影響範囲: 親リポに .gitmodules 追加、指定パスに子リポマウント。

作り方:

Terminal window
git submodule add https://github.com/you/methodology.git tools/methodology
git commit -m "chore: add methodology submodule"

初回取得:

Terminal window
git clone --recurse-submodules <repo>
# または後から
git submodule update --init --recursive

更新(子リポの最新を取り込む):

Terminal window
git submodule update --remote tools/methodology
git add tools/methodology
git commit -m "chore: bump methodology submodule"

消し方:

Terminal window
git submodule deinit -f tools/methodology
git rm -f tools/methodology
rm -rf .git/modules/tools/methodology
git commit -m "chore: remove methodology submodule"

見分け方:

  • ルートに .gitmodules ファイル
  • GitHub 上でフォルダアイコンが特殊、クリックで別リポへ遷移
  • コミットハッシュが @ xxxxxxx 形式で表示

CI/CD の落とし穴:

GitHub Actions で submodule を含むリポをビルドする場合:

- uses: actions/checkout@v4
with:
submodules: recursive # または true
token: ${{ secrets.GITHUB_TOKEN }}

private submodule を参照する場合は追加で PAT(Personal Access Token)が必要:

- uses: actions/checkout@v4
with:
submodules: recursive
token: ${{ secrets.SUBMODULE_PAT }}

セキュリティ観点:

  • Submodule の URL 改ざん攻撃: .gitmodules の URL を悪意あるリポに書き換える PR に注意
  • 対策: .gitmodules 変更は必ずレビュー、CODEOWNERS で保護
  • HTTPS より SSH URL は認証情報漏洩リスクが低い

よくある失敗:

  • 子リポ側で commit & push を忘れ、親リポだけ更新 → 他の環境で参照コミットが取得できずビルド失敗
  • 対策: git push --recurse-submodules=on-demand を習慣化

Subtree

目的: 外部リポの内容を親リポに統合して取り込む。利用者からは通常フォルダに見える。

使用シーン:

  • Submodule の複雑さを避けたい
  • 利用者に Git 中級知識を要求できない

メリット:

  • clone 時に特別操作不要
  • 通常のフォルダとして扱える

デメリット:

  • 履歴が肥大化しやすい
  • 上流への還元コマンドがやや複雑

作り方:

Terminal window
git subtree add --prefix=tools/methodology \
https://github.com/you/methodology.git main --squash

上流の更新取り込み:

Terminal window
git subtree pull --prefix=tools/methodology \
https://github.com/you/methodology.git main --squash

自分の変更を上流に還元:

Terminal window
git subtree push --prefix=tools/methodology \
https://github.com/you/methodology.git main

消し方: フォルダ削除 (git rm -rf tools/methodology && git commit)。

見分け方: 表示上は通常フォルダ。.gitmodules なし。コミット履歴に git-subtree-dir: を含むメッセージ。

よくある失敗:

  • --squash で追加した subtree に対し、--squash なしで pull → 履歴が二重化して大混乱
  • 対策: 一貫して --squash を使うか、一貫して使わない
  • subtree push は subtree の history が squash されていると失敗しやすい → 別リポで clone → cherry-pick → push が実用的

Symlink(シンボリックリンク)

目的: 同一ファイル・フォルダに複数名でアクセスできる OS 機能。Git も保持できる。

使用シーン:

  • AGENTS.md と CLAUDE.md を同一内容として扱う(複数エージェント対応)
  • 設定ファイルの複数配置

メリット: 実体1つ、更新が同期される。

デメリット:

  • Windows では作成に管理者権限か Developer Mode 必要
  • git config core.symlinks true を設定していないとテキストファイルとして clone される

作り方:

Terminal window
ln -s CLAUDE.md AGENTS.md
git add AGENTS.md
git commit -m "chore: link AGENTS.md to CLAUDE.md"

消し方: rm AGENTS.md(通常のファイル削除と同様)。

見分け方:

  • GitHub 上でファイル名横に斜め矢印アイコン
  • クリックでリンク先ファイルへ遷移
  • ローカルでは ls -la で AGENTS.md -> CLAUDE.md と表示

よくある失敗:

  • Windows ユーザーが clone → symlink がリンク先パスのテキストファイルになる
  • 対策: リポの README に git config core.symlinks true の指示を明記

Branch(ブランチ)

目的: 同一リポ内で並行開発の系統を分ける。

使用シーン:

  • 機能開発 (feature/*)
  • バグ修正 (fix/*)
  • リリース準備 (release/*)
  • 個人作業 (user/name/*)

他者との関係:

  • 同リポにアクセス権を持つ全員が閲覧・チェックアウト可能
  • Pull Request でメインブランチへの merge を提案

メリット:

  • 軽量、瞬時に切り替え可能
  • Fork と違い1つのリポで完結

デメリット:

  • リポの書き込み権限が必要(外部貢献者は Fork ルート)

作り方:

  • Web GUI: ブランチセレクタ → 名前入力 → 「Create branch」
  • CLI:
Terminal window
git checkout -b feature/new-ui
git push -u origin feature/new-ui

消し方:

Terminal window
# ローカル
git branch -d feature/new-ui # merged 済みのみ
git branch -D feature/new-ui # 強制
# リモート
git push origin --delete feature/new-ui

Web GUI: Branches ページ → ゴミ箱アイコン。

見分け方: ブランチセレクタ、または git branch -a。

セキュリティ観点:

  • main / release/* は Branch protection rules で保護すべき
  • 直接 push 禁止、PR + review 必須、status check 必須の3点セットが最低ライン

Worktree

目的: 同一リポの複数ブランチを、別々のディレクトリで同時にチェックアウトする。

使用シーン:

  • main での hotfix と feature 開発を並行
  • ブランチ切り替え時のビルド破棄を避けたい

作り方:

Terminal window
git worktree add ../repo-hotfix hotfix-branch

削除:

Terminal window
git worktree remove ../repo-hotfix

見分け方: git worktree list で確認。


Package(npm / pip / cargo など)

目的: コードを公式パッケージとして配布し、依存管理システム経由で組み込ませる。

使用シーン: 汎用ライブラリ、CLI ツール、フレームワーク。

メリット:

  • semver によるバージョン管理
  • 依存解決が自動
  • インストールが簡単

デメリット:

  • 公開・メンテナンスの手間
  • レジストリへの登録が必要

GitHub Packages を使う場合:

  • private package もリポとセットで管理可能
  • .npmrc に registry と ${GITHUB_TOKEN} を設定

セキュリティ観点:

  • Typosquatting 攻撃(似た名前の悪意パッケージ)に注意
  • Dependabot / Renovate で依存更新を自動化
  • npm audit / pip-audit を CI に組込む

見分け方: リポの Packages タブ、または package.json の "name" フィールド。


Monorepo(workspaces)

目的: 密結合した複数パッケージを単一リポで管理。

ツール例: pnpm workspaces, Nx, Turborepo, Lerna

メリット: 一括 CI、統一 lint、原子的変更。

デメリット: リポ肥大化、CI 分離設計が必要。

CI 最適化:

  • paths-filter action で変更検知 → 影響パッケージのみビルド
  • Turborepo の remote cache でビルド共有

見分け方: pnpm-workspace.yaml, nx.json, ルート package.json の workspaces フィールド。


Release / Tag

目的: 特定コミットにバージョンラベルを付け、配布物として固定。

作り方:

Terminal window
git tag -a v1.0.0 -m "Release 1.0.0"
git push origin v1.0.0

Web GUI: Releases タブ →「Draft a new release」

消し方:

Terminal window
git tag -d v1.0.0
git push origin --delete v1.0.0

見分け方: Releases タブ、git tag -l。

セキュリティ観点:

  • Release アセットへの署名(cosign, GPG)で改ざん検知
  • gh attestation で SLSA provenance 生成

Gist

目的: 単一〜数ファイルのスニペット共有。ミニリポとして機能。

使用シーン: 設定サンプル、コードスニペット、一時的共有。

Fork 可能: Gist にも Fork 機能がある。

見分け方: URL が gist.github.com/...。

セキュリティ観点: Public Gist は検索エンジンにインデックスされる。うっかり API キーを貼ると秒で bot に拾われる。


見分け方まとめ(GitHub 画面で判別)

見た目正体
リポ名下「forked from ○○」Fork
リポ名下「generated from ○○」Template から生成
フォルダに斜め矢印、別リポへ遷移Submodule
ファイル名に斜め矢印、同リポ内へ遷移Symlink
通常のフォルダだが .gitmodules ありSubmodule 親リポ
Releases タブに項目ありRelease/Tag
Packages タブに項目ありPackage 公開
URL が gist.github.comGist

CI/CD 統合チートシート

actions/checkout@v4 の主要オプション:

- uses: actions/checkout@v4
with:
fetch-depth: 0 # 全履歴取得(tag/blame解析用)
submodules: recursive # submodule 再帰取得
token: ${{ secrets.PAT }} # private submodule 用
lfs: true # Git LFS 有効化
persist-credentials: false # 後続 step で認証情報を残さない

判断早見表:

やりたいこと設定
通常のビルドデフォルトで OK
tag からバージョン算出fetch-depth: 0
submodule 使用submodules: recursive
private submodule上記 + token: PAT
大容量ファイルlfs: true
Fork PR で secret を守るpull_request_target を避ける

セキュリティ観点まとめ

機能主なリスク対策
ForkPR での secret 漏洩pull_request_target 回避、label トリガー
Template履歴の秘密情報引継trufflehog で事前スキャン
Duplicate全履歴の秘密複製BFG Repo-Cleaner で除去後複製
SubmoduleURL 改ざん攻撃.gitmodules を CODEOWNERS 保護
PackageTyposquattingDependabot、npm audit
Gist検索インデックスSecret Gist 使用、公開前スキャン
Branch直接 pushBranch protection rules
Releaseアセット改ざんcosign / SLSA provenance

Git Bash とクロスプラットフォーム

Windows の Git Bash は MSYS2 ベースで、以下が Linux/macOS と共通:

  • git 全コマンド
  • ls cp mv rm grep find cat ssh curl
  • パイプ・リダイレクト・&& ||

差異:

  • パスは /c/Users/... 形式
  • sudo 不在
  • Symlink 作成に権限設定が必要
  • 改行コード(core.autocrlf)に注意

本記事のコマンドは全て Git Bash / macOS Terminal / Linux shell で共通動作する。


関連

  • 2026-09-22-agent-config-symlink — AGENTS.md / CLAUDE.md の symlink 運用(TBD)
  • 2026-09-22-methodology-integration — methodology サブモジュール運用(TBD)
  • TBD: git-security-hardening — Git/GitHub セキュリティ強化(TBD)

更新履歴

更新内容サマリー

前回レビューで挙げた改善点への対応:

指摘事項対応
ファイル名未出力冒頭で明示
CI/CD への言及不足各機能に「CI/CD の落とし穴」節、末尾に統合チートシート追加
セキュリティ観点欠落各機能に「セキュリティ観点」節、末尾に一覧表追加
related 未記載related: [] を明示
Pugh Matrix 未使用組み込み手段比較で導入
updates 初期値updates: [] を明示
コマンドの落とし穴各機能に「よくある失敗」節追加
フローチャートが粗いMermaid 版とテキスト版の二段構え
「他者との関係」欠落主要機能に補記
tags 拡充ci-cd, security を追加