git-repository

Git リポジトリ管理スキル

このスキルでは、リポジトリ管理戦略、ブランチモデル、リポジトリ構成のパターン、大規模なチームやコードベースに合わせて Git をスケールする方法について、包括的なガイダンスを提供します。

使用するタイミング

次の場合にこのスキルを有効にします：

• 新しいリポジトリ構成を設定するとき
• ブランチ戦略を選択するとき
• モノレポとポリレポを管理するとき
• 複数のプロジェクトを含むリポジトリを整理するとき
• サブモジュールまたはサブツリー戦略を実装するとき
• 大規模なチームに合わせて Git をスケールするとき
• リポジトリ構成を移行するとき
• チームのワークフローを確立するとき

ブランチ戦略

Git Flow

ブランチ構成：

• main（または master） - 本番リリース専用
• develop - 次回リリースに向けた統合ブランチ
• feature/* - 機能開発用ブランチ
• release/* - リリース準備用ブランチ
• hotfix/* - 本番環境の緊急修正用ブランチ

ワークフロー：

# Feature Development
git checkout develop
git checkout -b feature/user-authentication
# Work on feature...
git commit -m "feat: add JWT authentication"
git checkout develop
git merge --no-ff feature/user-authentication
git branch -d feature/user-authentication

# Release Preparation
git checkout develop
git checkout -b release/v1.2.0
# Bump version, update changelog, final testing...
git commit -m "chore: prepare release v1.2.0"

# Deploy Release
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release version 1.2.0"
git checkout develop
git merge --no-ff release/v1.2.0
git branch -d release/v1.2.0
git push origin main develop --tags

# Hotfix
git checkout main
git checkout -b hotfix/security-patch
git commit -m "fix: patch security vulnerability"
git checkout main
git merge --no-ff hotfix/security-patch
git tag -a v1.2.1 -m "Hotfix v1.2.1"
git checkout develop
git merge --no-ff hotfix/security-patch
git branch -d hotfix/security-patch
git push origin main develop --tags

最適な用途：

• リリーススケジュールが決まっている場合
• 複数の本番バージョンがある場合
• QA プロセスを伴う大規模なチーム
• メンテナンス期間のある製品
• エンタープライズソフトウェア

デメリット：

• ワークフローが複雑
• ブランチの存続期間が長い
• マージコンフリクトが発生する可能性
• 統合が遅れる

GitHub Flow

ブランチ構成：

• main - 本番環境に対応したコード（常にデプロイ可能）
• feature/* - すべての機能・修正用ブランチ

ワークフロー：

# Create Feature Branch
git checkout main
git pull origin main
git checkout -b feature/add-api-logging

# Develop Feature
git commit -m "feat: add structured logging middleware"
git push -u origin feature/add-api-logging

# Open Pull Request on GitHub
# Review, discuss, CI passes

# Merge and Deploy
# Merge PR on GitHub
# Automatic deployment from main

# Cleanup
git checkout main
git pull origin main
git branch -d feature/add-api-logging

最適な用途：

• 継続的デプロイ
• 小規模から中規模のチーム
• Web アプリケーション
• 迅速な反復開発
• クラウドネイティブアプリケーション

デメリット：

• 堅牢な CI/CD が必要
• リリース前のステージングがない
• Git Flow より構造が緩やか

トランクベース開発

ブランチ構成：

• main（または trunk） - 唯一の信頼できる情報源
• 短期間の機能ブランチ（2 日未満、任意）
• 未完成の作業にはフィーチャーフラグを使用

ワークフロー：

# Direct Commit to Main (Small Changes)
git checkout main
git pull origin main
# Make small change...
git commit -m "fix: correct validation logic"
git push origin main

# Short-Lived Branch (Larger Changes)
git checkout -b optimize-query
# Work for < 1 day
git commit -m "perf: optimize database query"
git push -u origin optimize-query
# Immediate PR, quick review, merge same day

# Feature Flags for Incomplete Features
git checkout main
git commit -m "feat: add payment gateway (behind feature flag)"
# Feature disabled in production until complete
git push origin main

最適な用途：

• 開発速度の速いチーム
• 継続的インテグレーション
• 自動テスト
• フィーチャーフラグの基盤
• DevOps 文化

デメリット：

• 規律が必要
• 網羅的なテストが必要
• フィーチャーフラグの管理が必要
• デプロイ頻度が高い

リリースブランチ戦略

ブランチ構成：

• main - 現在の開発
• release/v* - 長期間維持するリリースブランチ
• feature/* - 機能ブランチ

ワークフロー：

# Create Release Branch
git checkout -b release/v1.0 main
git push -u origin release/v1.0

# Continue Development on Main
git checkout main
# Work on v2.0 features...

# Backport Fixes to Release
git checkout release/v1.0
git cherry-pick abc123  # Fix from main
git push origin release/v1.0
git tag -a v1.0.5 -m "Patch release v1.0.5"
git push origin v1.0.5

# Multiple Release Maintenance
git checkout release/v0.9
git cherry-pick def456
git tag -a v0.9.8 -m "Security patch v0.9.8"

最適な用途：

• 複数の製品バージョン
• 長期サポート対象のリリース
• エンタープライズ顧客
• 規制対象の業界

デメリット：

• メンテナンスの負担
• チェリーピックが複雑
• コードベースが分岐する

フィーチャーブランチワークフロー

ブランチ構成：

• main - 安定した本番コード
• feature/* - main から作成する機能ブランチ
• bugfix/* - バグ修正用ブランチ

ワークフロー：

# Feature Development
git checkout main
git checkout -b feature/payment-integration

# Long-Running Feature (Sync with Main)
git fetch origin
git rebase origin/main
# Or merge
git merge origin/main

# Complete Feature
git push origin feature/payment-integration
# Create pull request
# After review and approval, merge to main

最適な用途：

• 中規模のチーム
• コードレビューのプロセス
• 機能の並行開発
• マージ前の品質ゲート

リポジトリ構成

モノレポ

構成：

monorepo/
├── .git/
├── services/
│   ├── api/
│   ├── web/
│   └── worker/
├── packages/
│   ├── shared-utils/
│   ├── ui-components/
│   └── api-client/
├── tools/
│   ├── build-tools/
│   └── scripts/
└── docs/

メリット：

• 唯一の信頼できる情報源
• 共有コードの可視性
• プロジェクト間の変更を一括で反映
• バージョン管理の統一
• 依存関係管理の簡素化
• ツールの統一

デメリット：

• リポジトリのサイズが大きい
• クローン／フェッチが遅い
• CI/CD が複雑
• アクセス制御が難しい
• ツール要件が厳しい

実装：

# Initialize Monorepo
git init
mkdir -p services/api services/web packages/shared-utils

# Workspace Setup (Node.js example)
cat > package.json << EOF
{
  "name": "monorepo",
  "private": true,
  "workspaces": [
    "services/*",
    "packages/*"
  ]
}
EOF

# Sparse Checkout (Partial Clone)
git clone --filter=blob:none --no-checkout <url>
cd repo
git sparse-checkout init --cone
git sparse-checkout set services/api packages/shared-utils
git checkout main

# Build Only Changed Packages
git diff --name-only HEAD~1 | grep "^services/api" && cd services/api && npm run build

ツール：

• Bazel - 大規模なモノレポ向けのビルドシステム
• Nx - モノレポ向けのビルドシステム（Node.js）
• Lerna - JavaScript モノレポ管理ツール
• Turborepo - 高性能ビルドシステム
• Git-subtree - 外部リポジトリをマージ

ポリレポ

構成：

organization/
├── api-service/       (separate repo)
├── web-app/           (separate repo)
├── mobile-app/        (separate repo)
├── shared-utils/      (separate repo)
└── documentation/     (separate repo)

メリット：

• 所有権の境界が明確
• 独立したバージョン管理
• リポジトリのサイズが小さい
• きめ細かなアクセス制御
• 柔軟な CI/CD
• チームの自律性

デメリット：

• 依存関係のバージョンが競合する
• リポジトリをまたぐ変更が複雑
• ツールや設定が重複する
• リポジトリをまたぐリファクタリングが難しい

実装：

# Template Repository
git clone [email protected]:org/template-service.git new-service
cd new-service
rm -rf .git
git init
git remote add origin [email protected]:org/new-service.git

# Shared Configuration
# Use git submodules or packages
git submodule add [email protected]:org/shared-config.git config

モノレポとポリレポの意思決定マトリックス

要素	モノレポ	ポリレポ
チームの規模	大規模チーム	小規模で自律的なチーム
コード共有	高いコード再利用率	限定的な共有
デプロイ	協調的なリリース	独立したデプロイ
アクセス制御	粗粒度	細粒度
リポジトリのサイズ	非常に大きい	小規模から中規模
CI/CD の複雑さ	高い	低から中程度
ツール要件	専用ツール	標準的な git ツール
リファクタリング	プロジェクト横断で容易	リポジトリ横断では複雑

サブモジュールの管理

基本的なサブモジュール

# Add Submodule
git submodule add https://github.com/org/shared-lib.git libs/shared

# Clone with Submodules
git clone --recurse-submodules <url>

# Initialize After Clone
git submodule init
git submodule update

# Update Submodule
cd libs/shared
git pull origin main
cd ../..
git add libs/shared
git commit -m "chore: update shared library"

# Update All Submodules
git submodule update --remote --merge

# Remove Submodule
git submodule deinit libs/shared
git rm libs/shared
rm -rf .git/modules/libs/shared

サブモジュールの戦略

バージョン固定戦略：

# Submodule points to specific commit
# Manual updates with testing
git submodule update --remote libs/shared
# Test changes...
git add libs/shared
git commit -m "chore: update shared-lib to v1.2.3"

自動更新戦略：

# CI automatically updates submodules
# .github/workflows/update-submodules.yml
name: Update Submodules
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly
jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
      - run: git submodule update --remote
      - run: git commit -am "chore: update submodules"
      - run: git push

入れ子のサブモジュール

# Add Nested Submodule
cd libs/framework
git submodule add https://github.com/org/utils.git utils

# Update Recursively
git submodule update --init --recursive

# Run Command in All Submodules
git submodule foreach 'git checkout main'
git submodule foreach 'git pull'
git submodule foreach --recursive 'echo $name: $(git rev-parse HEAD)'

サブツリーの管理

Git サブツリーとサブモジュールの比較

サブツリーのメリット：

• コントリビューターにとってよりシンプルです
• 別途クローンする手順が不要です
• メインリポジトリの履歴の一部になります
• 壊れた参照が発生しません

サブツリーのデメリット：

• 更新がより複雑です
• メインの履歴が煩雑になります
• リポジトリのサイズが大きくなります

サブツリーの操作

# Add Subtree
git subtree add --prefix=libs/shared https://github.com/org/shared.git main --squash

# Update Subtree
git subtree pull --prefix=libs/shared https://github.com/org/shared.git main --squash

# Push Changes Back to Subtree
git subtree push --prefix=libs/shared https://github.com/org/shared.git feature-branch

# Split Subtree (Extract to New Repo)
git subtree split --prefix=libs/shared -b shared-lib-branch
git push [email protected]:org/new-shared-lib.git shared-lib-branch:main

サブツリーのワークフロー

# Setup Remote for Easier Management
git remote add shared-lib https://github.com/org/shared.git

# Add Subtree with Remote
git subtree add --prefix=libs/shared shared-lib main --squash

# Pull Updates
git fetch shared-lib
git subtree pull --prefix=libs/shared shared-lib main --squash

# Contribute Back
git subtree push --prefix=libs/shared shared-lib feature-branch

リポジトリテンプレート

GitHub テンプレートリポジトリ

# Create Template Structure
mkdir -p .github/workflows
cat > .github/workflows/ci.yml << EOF
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: make test
EOF

# Template Files
touch .gitignore README.md LICENSE CONTRIBUTING.md
mkdir -p docs src tests

# Mark as Template on GitHub Settings
# Use template to create new repositories

Cookiecutter テンプレート

# Install Cookiecutter
pip install cookiecutter

# Create from Template
cookiecutter https://github.com/org/project-template.git

# Template Structure
project-template/
├── cookiecutter.json
└── {{cookiecutter.project_name}}/
    ├── .git/
    ├── src/
    ├── tests/
    └── README.md

大規模リポジトリの管理

部分クローン

# Blobless Clone (No file contents initially)
git clone --filter=blob:none <url>

# Treeless Clone (Even more minimal)
git clone --filter=tree:0 <url>

# Shallow Clone (Limited History)
git clone --depth 1 <url>

# Shallow Clone with Single Branch
git clone --depth 1 --single-branch --branch main <url>

スパースチェックアウト

# Enable Sparse Checkout
git sparse-checkout init --cone

# Specify Directories
git sparse-checkout set src/api src/shared

# Add More Directories
git sparse-checkout add docs

# List Current Sparse Checkout
git sparse-checkout list

# Disable Sparse Checkout
git sparse-checkout disable

Git LFS（大容量ファイルストレージ）

# Install Git LFS
git lfs install

# Track Large Files
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "data/**"

# Track Files in .gitattributes
cat .gitattributes
# *.psd filter=lfs diff=lfs merge=lfs -text

# Clone with LFS
git clone <url>
cd repo
git lfs pull

# Migrate Existing Files to LFS
git lfs migrate import --include="*.zip"

リポジトリの分割

サブディレクトリを新しいリポジトリに抽出

# Using git filter-repo (recommended)
git filter-repo --path services/api --path-rename services/api:

# Result: New repo with only services/api content and history

# Using git subtree
git subtree split --prefix=services/api -b api-service
mkdir ../api-service
cd ../api-service
git init
git pull ../original-repo api-service

複数のリポジトリを統合

# Add Remote
git remote add project-b ../project-b

# Fetch History
git fetch project-b

# Merge with Unrelated Histories
git merge --allow-unrelated-histories project-b/main

# Move Files to Subdirectory
mkdir project-b
git mv * project-b/
git commit -m "chore: organize project-b into subdirectory"

リポジトリの保守

定期的な保守タスク

# Optimize Repository
git gc --aggressive

# Prune Unreachable Objects
git prune --expire now

# Verify Integrity
git fsck --full

# Repack Repository
git repack -a -d --depth=250 --window=250

# Update Server Info (for dumb HTTP)
git update-server-info

自動化スクリプト

#!/bin/bash
# repo-maintenance.sh

echo "Starting repository maintenance..."

# Fetch all branches
git fetch --all --prune

# Clean up stale branches
git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -r git branch -D

# Garbage collection
git gc --auto

# Verify integrity
git fsck --full --strict

echo "Maintenance complete!"

定期的な保守

# .github/workflows/maintenance.yml
name: Repository Maintenance
on:
  schedule:
    - cron: '0 2 * * 0'  # Weekly at 2 AM Sunday
jobs:
  maintain:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - name: Run Maintenance
        run: |
          git gc --aggressive
          git prune --expire now
          git fsck --full

アクセス制御と権限

ブランチ保護ルール

# Example Configuration
protected_branches:
  main:
    required_pull_request_reviews:
      required_approving_review_count: 2
      dismiss_stale_reviews: true
      require_code_owner_reviews: true
    required_status_checks:
      strict: true
      contexts:
        - continuous-integration
        - security-scan
    enforce_admins: true
    restrictions:
      users: []
      teams: [core-team]

CODEOWNERS ファイル

# .github/CODEOWNERS

# Global owners
*                    @org/core-team

# Service owners
/services/api/       @org/backend-team
/services/web/       @org/frontend-team
/services/mobile/    @org/mobile-team

# Specific files
/docs/               @org/documentation-team
/.github/            @org/devops-team
/security/           @org/security-team @org/lead-architect

# Require multiple reviews
/packages/shared/    @org/core-team @org/architecture-team

移行戦略

SVN から Git へ

# Create Authors File
svn log --quiet | grep "^r" | awk '{print $3}' | sort -u > authors.txt

# Edit authors.txt:
# john = John Doe <[email protected]>

# Convert Repository
git svn clone <svn-url> --authors-file=authors.txt --stdlayout repo

# Convert Tags and Branches
cd repo
git for-each-ref --format="%(refname:short)" refs/remotes/tags | \
  cut -d / -f 3 | xargs -I {} git tag {} refs/remotes/tags/{}

# Push to Git
git remote add origin <git-url>
git push -u origin --all
git push origin --tags

Mercurial から Git へ

# Using hg-git
hg bookmark -r default main
hg push git+ssh://[email protected]/org/repo.git

# Using fast-export
git clone https://github.com/frej/fast-export.git
mkdir git-repo && cd git-repo
git init
../fast-export/hg-fast-export.sh -r ../hg-repo
git checkout HEAD

ベストプラクティス

1. 適切な戦略を選択する： ブランチモデルをチームの規模とデプロイ頻度に合わせます
2. ワークフローを文書化する： チームのドキュメントを最新の状態に保ちます
3. 保守を自動化する： リポジトリの健全性を定期的にチェックします
4. ブランチ保護を使用する： コードレビューと CI を必須にします
5. 所有者を明確にする： すべての領域でコードオーナーを定義します
6. 定期的に整理する： 古いブランチやマージ済みの機能を削除します
7. リポジトリのサイズを監視する： 大容量ファイルには LFS を使用します
8. リポジトリテンプレートを使用する： 新しいプロジェクトの構成を標準化します
9. アクセス制御を行う： 最小権限の原則を適用します
10. 移行を計画する： 本番環境に移行する前に、移行を十分にテストします

リソース

その他のリポジトリ管理リソースは assets/ ディレクトリにあります：

• templates/ - リポジトリ構成のテンプレート
• scripts/ - 自動化および保守スクリプト
• workflows/ - CI/CD ワークフローの例

以下については references/ ディレクトリを参照してください：

• ブランチ戦略の比較ガイド
• モノレポツールのドキュメント
• エンタープライズ向け Git パターン
• リポジトリのスケーリング戦略