mastering-git-cli

Git CLI スキル（2025年版）

モダンな開発向けの本番環境対応 Git ワークフローと自動化。

互換性： Git 2.38 以降を推奨します。SHA-256 と Reftable を完全にサポートするには Git 2.51 以降が必要です。

トリガー

このスキルは次の場合に有効になります：

• git コマンドとバージョン管理に関する質問
• マージコンフリクト、リベース操作、チェリーピックの判断
• ワークツリーのセットアップとサブモジュールの管理
• ブランチ戦略とリポジトリのトラブルシューティング
• 大規模リポジトリの最適化（Scalar、スパースチェックアウト、blobless クローン）
• CI/CD の Git 統合とパフォーマンス調整

クイックスタート

よく使われるパターン

# Clone and start working (use switch, not checkout)
git clone <url> && cd <repo>
git switch -c feature-x

# Commit workflow
git add -A && git commit -m "feat: description"
git push -u origin feature-x

# Merge feature to main
git switch main && git pull
git merge --no-ff feature-x
git push

# Large repo? Use partial clone
git clone --filter=blob:none <url>

モダンな Git 設定（2025年のデフォルト）

# Core workflow
git config --global pull.rebase true
git config --global push.autoSetupRemote true
git config --global merge.conflictStyle zdiff3
git config --global diff.algorithm histogram
git config --global rerere.enabled true
git config --global rebase.autoStash true

# Performance (essential for large repos)
git config --global core.fsmonitor true
git config --global fetch.prune true
git config --global feature.manyFiles true

# SSH signing (simpler than GPG)
git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

# Enable background maintenance
git maintenance start

判断ツリー

マージ、リベース、チェリーピックの使い分け

Need to integrate changes?
│
├─ All commits from a branch?
│  ├─ Shared branch (pushed/collaborative) → MERGE
│  └─ Local-only branch → REBASE (cleaner) or MERGE
│
└─ Specific commits only?
   └─ CHERRY-PICK
      ├─ Hotfix to release branch → cherry-pick -x
      └─ Backport to old version → cherry-pick -x

⚠️ AVOID: Rebasing shared/pushed branches (rewrites history others depend on)

ワークツリー、ブランチ、スタッシュの使い分け

Need to switch context?
│
├─ Quick switch, will return soon → STASH
├─ Parallel work on same files → Not possible
├─ Parallel work on different features?
│  ├─ Short-lived (minutes) → STASH or COMMIT WIP
│  └─ Long-running or parallel builds → WORKTREE
│
└─ Multiple agents working simultaneously → WORKTREE (essential)

サブモジュール、サブツリー、モノレポの使い分け

External code dependency?
│
├─ Need to modify and contribute back → SUBMODULE
├─ Just embedding, no upstream → SUBTREE
├─ Tight coupling, single team → MONOREPO
└─ Standard library/package → PACKAGE MANAGER

リセット、リバート、リストアの使い分け

Undo something?
│
├─ Discard file changes (not staged) → git restore <file>
├─ Unstage files → git restore --staged <file>
├─ Undo commits (not pushed)?
│  ├─ Keep changes staged → git reset --soft HEAD~1
│  ├─ Keep changes unstaged → git reset HEAD~1
│  └─ Discard everything → git reset --hard HEAD~1
│
└─ Undo commits (already pushed) → git revert <sha>

クローン戦略（大規模リポジトリ）

How to clone?
│
├─ Small repo (<500MB) → Full clone (default)
├─ Large repo, developer workstation
│  └─ BLOBLESS clone → git clone --filter=blob:none <url>
├─ Large repo, CI build
│  ├─ Need only HEAD → SHALLOW → git clone --depth 1
│  └─ Need history → TREELESS → git clone --filter=tree:0
│
└─ Monorepo, specific directories only
   └─ SCALAR + SPARSE → scalar clone <url>, then sparse-checkout

⚠️ AVOID: Shallow clone for development (breaks blame, log, push)

checkout と switch/restore の使い分け

Which command?
│
├─ Changing branches → git switch <branch>
├─ Creating branch → git switch -c <new-branch>
├─ Discarding file changes → git restore <file>
├─ Unstaging files → git restore --staged <file>
│
└─ git checkout → Legacy (avoid in new scripts)

簡単に使えるマージ手順

feature を main に統合する

git checkout main
git merge --no-ff feature    # Always creates merge commit

最新の main で feature を更新する

git checkout feature
git merge main               # Safe for shared branches
# OR
git rebase main              # Only if branch not shared

すべてのコンフリクトを theirs で解決する

git checkout --theirs .
git add .
git commit

すべてのコンフリクトを ours で解決する

git checkout --ours .
git add .
git commit

失敗したマージを中止する

git merge --abort

プッシュ済みのマージを取り消す

git revert -m 1 <merge-sha>
git push

複数のブランチを一度にマージする

git merge feature-a feature-b feature-c  # Octopus merge (no conflicts allowed)

スクリプトの使用方法

エージェント用ワークツリーのセットアップ

並行してエージェント開発を行うために、分離されたワークツリーを作成します：

scripts/setup-agent-worktrees.sh [num_agents] [base_branch]
# Example: scripts/setup-agent-worktrees.sh 3 main
# Creates: ../agent-1, ../agent-2, ../agent-3, ../integration
# Output: "Created 3 agent worktrees from main"

ユースケース： 3 つの Claude エージェントを異なる機能で並行して実行し、それぞれに分離された作業ディレクトリを割り当てます。

エージェント用ワークツリーのクリーンアップ

すべてのエージェント用ワークツリーを削除し、必要に応じてブランチも削除します：

scripts/cleanup-agent-worktrees.sh [--delete-branches] [--force]
# Example: scripts/cleanup-agent-worktrees.sh --delete-branches
# Removes worktrees and their associated branches

サブモジュールのステータスレポート

すべてのサブモジュールの読みやすいステータスを取得します：

scripts/submodule-report.sh
# Output: Table showing submodule path, branch, commit, and sync status

Git のヘルスチェック

よくあるリポジトリの問題を診断します：

scripts/git-health-check.sh [--verbose]
# Checks: dangling objects, broken refs, large files, stale branches

リファレンスの案内

作業内容に応じて、適切なリファレンスファイルを確認してください。

作業	リファレンスファイル
Git の内部構造、オブジェクトモデル、DAG を理解する	references/foundations.md
Git を設定し、2025 年のデフォルトをセットアップする	references/foundations.md
clone、commit、log、branch の基本	references/daily-usage.md
worktree を作成・管理する	references/worktrees.md
並列エージェントのワークフローをセットアップする	references/worktrees.md
マージ戦略を選択する	references/merge-operations.md
マージの競合を解決する	references/merge-operations.md
競合解決に rerere を使用する	references/merge-operations.md
サブモジュールを追加・更新・管理する	references/submodules.md
マルチリポジトリのプロジェクトアーキテクチャ	references/submodules.md
reset、revert、restore の操作	references/advanced-operations.md
インタラクティブ rebase、squash	references/advanced-operations.md
stash、タグ、フック	references/advanced-operations.md
失われたコミットやブランチを復元する	references/recovery.md
よくあるエラーのトラブルシューティング	references/recovery.md
コマンドのチートシート	references/recovery.md
SHA-256、Reftable、SSH 署名	references/git-2025-features.md
git switch/restore、range-diff	references/git-2025-features.md
Git メンテナンス、bisect run	references/git-2025-features.md
マージキュー、pre-commit フレームワーク	references/git-2025-features.md
部分クローン／blobless クローン、Scalar	references/large-repos.md
モノレポ向けのスパースチェックアウト	references/large-repos.md
ベアリポジトリ＋worktree の構成	references/large-repos.md
CI/CD の Git 最適化	references/large-repos.md

重要な知識

-X ours と -s ours の落とし穴

# -X ours: Prefer our changes ONLY IN CONFLICTS
git merge -X ours feature
# ↑ Merges all non-conflicting changes from feature

# -s ours: IGNORE EVERYTHING from other branch
git merge -s ours feature
# ↑ Keeps our tree exactly, just records the merge

競合スタイルの推奨

git config --global merge.conflictStyle zdiff3

競合箇所にベースバージョンを表示して、解決を分かりやすくします。

<<<<<<< HEAD
our version
||||||| merged common ancestor
original version
=======
their version
>>>>>>> feature

ブランチは 1 つの worktree にしか存在できない

ブランチをチェックアウトできる worktree は 1 つだけです。別の場所で作業するには、次のようにします。

git worktree add -b feature-copy ../feature-copy feature  # Create copy

サブモジュールはデフォルトで detached HEAD になる

git submodule update の後、変更を加える前に必ずブランチをチェックアウトしてください。

cd submodule-dir
git checkout main  # Then make changes

2025 年の簡単な操作

バグを導入したコミットを自動的に見つける

# Create test script: exit 0 = good, exit 1 = bad
echo '#!/bin/bash
npm test -- --grep="broken feature"' > test.sh
chmod +x test.sh

git bisect start HEAD v1.0.0
git bisect run ./test.sh
git bisect reset

rebase された PR を比較する（実際に変更された内容）

git range-diff main..feature@{1} main..feature

モノレポ：必要なものだけをチェックアウトする

git clone --filter=blob:none <url>
cd repo
git sparse-checkout init --cone
git sparse-checkout set backend/api frontend/app

パフォーマンス最適化をセットアップする

scalar register                 # Enable all optimizations
# OR manually:
git maintenance start          # Background maintenance
git config core.fsmonitor true # Filesystem watcher

SSH 署名のセットアップ（GPG より簡単）

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true

reftable に移行する（ブランチが 1 万以上の場合）

git refs migrate --ref-format=reftable

アンチパターン（避けるべきこと）

ファイル操作に checkout を使わない

# Bad: ambiguous, can lose data
git checkout file.txt

# Good: explicit intent
git restore file.txt

開発用に shallow clone を使わない

# Bad: breaks blame, log, push
git clone --depth 1 <url>

# Good: blobless preserves history
git clone --filter=blob:none <url>

--force-with-lease を省略しない

# Bad: can overwrite teammates' work
git push --force

# Good: fails if remote has new commits
git push --force-with-lease

git gc を手動で実行しない

# Bad: blocks, runs everything at once
git gc

# Good: scheduled, incremental
git maintenance start

共有ブランチを rebase しない

# Bad: rewrites history others depend on
git rebase main  # on a pushed branch

# Good: merge instead for shared branches
git merge main

シークレットや生成ファイルをコミットしない

# Bad: committing sensitive or generated files
git add .env node_modules/

# Good: ensure .gitignore is set first
echo -e ".env\nnode_modules/" >> .gitignore
git add .gitignore

マージの競合を無視しない

# Bad: accepting all changes blindly
git checkout --theirs .  # without reviewing

# Good: review each conflict
git mergetool  # or manual review with zdiff3