git-2025-features

📌 NOTE: Git 2.49 以降の機能（git-backfill、path-walk API、zlib-ng）の詳細については、git-2-49-features.md スキルを参照してください。

🚨 重要なガイドライン

Windows のファイルパス要件

必須：Windows のファイルパスには常にバックスラッシュを使用してください

Windows で Edit または Write ツールを使用する場合は、ファイルパスにスラッシュ（/）ではなく、バックスラッシュ（\）を必ず使用してください。

例：

• ❌ 誤り：D:/repos/project/file.tsx
• ✅ 正しい：D:\repos\project\file.tsx

これは次の項目に適用されます。

• Edit ツールの file_path パラメーター
• Write ツールの file_path パラメーター
• Windows システムでのすべてのファイル操作

ドキュメント作成のガイドライン

ユーザーから明示的に依頼されない限り、新しいドキュメントファイルを作成しないでください。

• 優先事項：新しいドキュメントを作成するよりも、既存の README.md ファイルを更新してください
• リポジトリの整理：ユーザーから別途依頼されない限り、リポジトリのルートは README.md のみとし、整理された状態を保ってください
• スタイル：ドキュメントは簡潔で、直接的かつプロフェッショナルなものにしてください。AI が生成したような語調は避けてください
• ユーザーの希望：ユーザーからドキュメントの作成を具体的に依頼された場合に限り、追加の .md ファイルを作成してください

---

Git 2025 の機能 - 高度な機能

Git 2.49（2025 年 3 月）- 最新

主な追加機能： git-backfill、path-walk API、zlib-ng によるパフォーマンス向上、デルタ圧縮の改善。

全機能の詳細については、git-2-49-features.md を参照してください。

Git 2.48～2.49 の機能

Reftables への移行（2.48 で完了）

概要： ルーズな ref ファイルと packed-refs を置き換える、新しい参照ストレージ形式です。

利点：

• ref 操作の高速化（50～80％の改善）
• アトミックな ref 更新
• ref が多数あるリポジトリでのスケーラビリティ向上
• reflog の完全な移行が可能（2.48 で完了）

移行：

# Check current ref storage format
git config core.refStorage

# Migrate to reftables
git refs migrate --ref-storage=reftables

# Verify migration
git fsck --full
git log --oneline -5

# Roll back if needed (before critical operations)
git refs migrate --ref-storage=files

使用する場面：

• ref が 10,000 個以上あるリポジトリ
• ブランチ操作の頻度が高い場合
• 多数の一時 ref を作成する CI/CD システム
• ブランチが多岐にわたるモノレポ

パフォーマンスの節目（2.48～2.49）

Git 2.48：

• メモリーリークの解消を達成
• 長時間実行される操作で安定したメモリー使用量

Git 2.49：

• zlib-ng の統合：圧縮が 20～30％高速化
• Path-walk API：デルタ圧縮が 50～70％改善
• パックファイルを最適化する新しい名前ハッシュアルゴリズム

次の操作で効果が自動的に得られます。

• 大規模リポジトリのクローン
• 長時間のリベースセッション
• 一括操作（filter-repo、GC、repack）

スパースチェックアウト（2.48 で強化）

概要： リポジトリ内のファイルの一部のみをチェックアウトします。

使用例：

• モノレポ（一つのサービスで作業する）
• 大規模リポジトリ（ディスク使用量を削減する）
• ビルドシステム（必要なファイルのみを取得する）

Cone モード（デフォルト - 推奨）：

# Clone with sparse-checkout
git clone --filter=blob:none --sparse <repo-url>
cd <repo>

# Initialize sparse-checkout in cone mode
git sparse-checkout init --cone

# Add directories to checkout
git sparse-checkout set src/api src/shared docs

# Add more directories
git sparse-checkout add tests/integration

# View current patterns
git sparse-checkout list

# Check what would be matched
git sparse-checkout check-rules src/api/users.ts

# Disable sparse-checkout
git sparse-checkout disable

高度なパターン（非 Cone モード）：

# Enable pattern mode
git sparse-checkout init --no-cone

# Add patterns (one per line)
git sparse-checkout set \
  "*.md" \
  "src/api/*" \
  "!src/api/legacy/*"

# Read patterns from file
git sparse-checkout set --stdin < patterns.txt

ルールの再適用：

# After merge/rebase that materialized unwanted files
git sparse-checkout reapply

部分クローン

概要： 最初にすべてのオブジェクトをダウンロードせずに、リポジトリをクローンします。

フィルター：

1. blob:none - すべての blob の取得を遅延する（最速、最小）
2. tree:0 - すべての tree と blob の取得を遅延する
3. blob:limit=1m - 1MB を超える blob の取得を遅延する

使用方法：

# Clone without blobs (fetch on demand)
git clone --filter=blob:none <repo-url>

# Clone without large files
git clone --filter=blob:limit=10m <repo-url>

# Combine with sparse-checkout
git clone --filter=blob:none --sparse <repo-url>
cd <repo>
git sparse-checkout set src/api

# Convert existing repository to partial clone
git config extensions.partialClone origin
git config remote.origin.promisor true
git fetch --filter=blob:none

# Prefetch all missing objects
git fetch --unshallow

部分クローンとスパースチェックアウトの併用：

# Ultimate efficiency: Only objects for specific directories
git clone --filter=blob:none --sparse <repo-url>
cd <repo>
git sparse-checkout set --cone src/api
git checkout main

# Result: Only have objects for src/api

promisor オブジェクトの確認：

# Verify partial clone status
git config extensions.partialClone

# See promisor packfiles
ls -lah .git/objects/pack/*.promisor

# Force fetch specific object
git rev-list --objects --missing=print HEAD | grep "^?"

Git ワークツリー

概要： 1 つのリポジトリから複数の作業ディレクトリを作成します。

利点：

• 複数のブランチで同時に作業できる
• 切り替え前に stash やコミットをする必要がない
• 並行して作業できる（コーディング中に PR をレビューするなど）
• .git を共有する（1 回の fetch ですべてが更新される）

基本操作：

# List worktrees
git worktree list

# Create worktree for existing branch
git worktree add ../project-feature feature-branch

# Create worktree with new branch
git worktree add -b new-feature ../project-new-feature

# Create worktree from remote branch
git worktree add ../project-fix origin/fix-bug

# Remove worktree
git worktree remove ../project-feature

# Clean up stale worktree references
git worktree prune

高度なパターン：

# Worktree for PR review while coding
git worktree add ../myproject-pr-123 origin/pull/123/head
cd ../myproject-pr-123
# Review PR in separate directory
cd -
# Continue coding in main worktree

# Worktree for hotfix
git worktree add --detach ../myproject-hotfix v1.2.3
cd ../myproject-hotfix
# Make hotfix
git switch -c hotfix/security-patch
git commit -am "fix: patch vulnerability"
git push -u origin hotfix/security-patch

# Worktree organization
mkdir -p ~/worktrees/myproject
git worktree add ~/worktrees/myproject/feature-a -b feature-a
git worktree add ~/worktrees/myproject/feature-b -b feature-b
git worktree add ~/worktrees/myproject/pr-review origin/pull/42/head

ベストプラクティス：

1. ディレクトリ構成を整理する：

~/projects/
  myproject/           # Main worktree
  myproject-feature/   # Feature worktree
  myproject-review/    # Review worktree

2. 定期的にクリーンアップする：

# Remove merged worktrees
git worktree list | grep feature | while read wt branch commit; do
  if git branch --merged | grep -q "$branch"; then
    git worktree remove "$wt"
  fi
done

3. 設定の共有：

• .git/config はすべてのワークツリーに適用されます
• .git/info/exclude はすべてのワークツリーに適用されます
• 各ワークツリーは独自の index と HEAD を持ちます

Scalar（大規模リポジトリ向けツール）

概要： 非常に大規模なリポジトリを最適化するツールです（Microsoft が開発）。

# Install scalar (comes with Git 2.47+)
scalar register <path>

# Clone with scalar optimizations
scalar clone --branch main <repo-url>

# Enables automatically:
# - Sparse-checkout (cone mode)
# - Partial clone (blob:none)
# - Multi-pack-index
# - Commit-graph
# - Background maintenance

# Unregister
scalar unregister <path>

# Delete repository
scalar delete <path>

Git Backfill（実験的）

概要： 部分クローンで不足しているオブジェクトを取得するバックグラウンドプロセスです。

# Fetch missing blobs in background
git backfill

# Configure batch size
git backfill --min-batch-size=1000

# Respect sparse-checkout patterns
git backfill --sparse

パフォーマンスの比較

従来のクローン：

git clone large-repo
# Size: 5GB, Time: 10 minutes

スパースチェックアウト：

git clone --sparse large-repo
git sparse-checkout set src/api
# Size: 500MB, Time: 3 minutes

部分クローン：

git clone --filter=blob:none large-repo
# Size: 100MB, Time: 1 minute

部分クローン＋スパースチェックアウト：

git clone --filter=blob:none --sparse large-repo
git sparse-checkout set src/api
# Size: 50MB, Time: 30 seconds

各機能の使いどころ

スパースチェックアウト：

• ✓ モノレポ
• ✓ 特定のサービス／モジュールでの作業
• ✓ ディスク容量が限られている場合
• ✗ コードベース全体が頻繁に必要な場合

部分クローン：

• ✓ CI/CD パイプライン
• ✓ 大規模リポジトリ
• ✓ 良好なネットワーク接続
• ✗ 頻繁にオフラインで作業する場合

ワークツリー：

• ✓ 並行開発
• ✓ 作業中の PR レビュー
• ✓ 複数ブランチのテスト
• ✗ ディスク容量が少ない場合

すべてを組み合わせる場合：

• ✓ 巨大なモノレポ（Google 規模）
• ✓ 複数のタスクを同時に進める場合
• ✓ ローカルストレージを最小限に抑える場合
• ✓ 高速なネットワーク接続

トラブルシューティング

スパースチェックアウトが機能しない場合：

# Verify configuration
git config core.sparseCheckout
git config core.sparseCheckoutCone

# Re-apply patterns
git sparse-checkout reapply

# Check patterns
git sparse-checkout list

部分クローンでオブジェクトが見つからない場合：

# Fetch specific object
git fetch origin <commit>

# Fetch all missing
git fetch --unshallow

# Verify promisor config
git config extensions.partialClone

ワークツリーの問題：

# Locked worktree
git worktree unlock <path>

# Corrupted worktree
git worktree remove --force <path>
git worktree prune

# Branch already checked out
git checkout --ignore-other-worktrees <branch>

移行ガイド

従来のワークフローから最適化されたワークフローへの移行：

# 1. Current large clone
cd large-project
du -sh .git  # 5GB

# 2. Create optimized new clone
cd ..
git clone --filter=blob:none --sparse large-project-new
cd large-project-new
git sparse-checkout set src/api src/shared

# 3. Verify size
du -sh .git  # 50MB

# 4. Switch workflow
cd ../large-project-new

# 5. Delete old clone when comfortable
rm -rf ../large-project

リソース

• Git の部分クローンに関するドキュメント
• Git スパースチェックアウトガイド
• Git ワークツリーのベストプラクティス
• Scalar のドキュメント