version-control

Git によるバージョン管理

このスキルを使うと、AI エージェントはリポジトリの初期化やアトミックコミットの作成から、ブランチ戦略の運用、マージコンフリクトの解決、フックによる自動化の設定まで、Git に基づく幅広いバージョン管理タスクを実行できます。日常的なワークフローに加え、チームでのプロフェッショナルなコラボレーションに必要な高度な操作も扱います。

ワークフロー

1. リポジトリの状態を確認する：git status、git log --oneline -10、git branch -a を実行し、現在のブランチ、未コミットの変更、最近の履歴、利用可能なリモートを確認します。この情報をもとに、安全に実行できる操作を判断します。

2. 変更をステージしてコミットする：関連する変更をまとめてアトミックコミットにします。コミットメッセージは、簡潔な要約行（50 文字以内）で始め、変更内容が複雑な場合は空行に続けて説明本文を記述します。プロジェクトにコミット規約（Conventional Commits、Angular style など）がある場合は、それに従います。

3. ブランチを管理する：適切なベースから、機能、バグ修正、リリース用のブランチを作成します。feat/short-description、fix/issue-123、release/1.2.0 など、一貫した命名規則を使います。ブランチ一覧をすっきり保つため、マージ後に古いブランチを削除します。

4. リモートと同期する：最新の状態を保つため、定期的にフェッチとプルを行います。機能ブランチを初めてプッシュするときは -u フラグを付けます。マージ前に、ベースブランチを機能ブランチにリベースまたはマージして、分離された環境で早めにコンフリクトを解決します。

5. コンフリクトを解決する：コンフリクトが発生したら、競合しているファイルを確認し、変更の双方を把握したうえで、適切な解決方法を選ぶ（または双方を組み合わせる）必要があります。git add でファイルを解決済みとしてマークし、マージまたはリベースを完了します。解決後は必ずテストを実行し、正しく動作することを確認します。

6. フックと CI で自動化する：Git フック（リントやフォーマット用の pre-commit、メッセージ検証用の commit-msg、テスト実行用の pre-push）を設定し、ビルド成果物、環境ファイル、OS のメタデータが .gitignore の対象になっていることを確認します。CI パイプラインと連携し、プッシュのたびに品質ゲートを適用します。

対応技術

• Git（CLI、libgit2）
• プラットフォーム：GitHub、GitLab、Bitbucket、Azure DevOps
• CLI ツール：gh（GitHub CLI）、glab（GitLab CLI）
• フック用フレームワーク：Husky、pre-commit、Lefthook
• ブランチモデル：GitFlow、GitHub Flow、トランクベース開発

使用方法

必要な操作を平易な言葉で説明し、Git の操作をエージェントに依頼します。例：

• 「新しい認証モジュール用の機能ブランチを作成して、ステージ済みの変更をコミットしてください。」
• 「src/config.ts のマージコンフリクトを解決して、マージを完了してください。」
• 「仮想環境を含む Python プロジェクト用の .gitignore を設定してください。」
• 「ブランチを main にリベースして、整理した履歴を強制プッシュしてください。」

エージェントは破壊的な操作の前にリポジトリの状態を確認し、履歴を書き換える reset --hard、push --force、rebase などのコマンドを実行する前に、必ずあなたに確認します。

例

例 1 — マージコンフリクトの解決

シナリオ：feat/user-profile ブランチで作業しており、main をマージしようとしたところ、src/utils/format.ts でコンフリクトが発生しています。

# Attempt the merge
git merge main
# Output: CONFLICT (content): Merge conflict in src/utils/format.ts

# Inspect the conflict markers
git diff --name-only --diff-filter=U
# src/utils/format.ts

競合しているファイルの内容：

function formatDate(date: Date): string {
<<<<<<< HEAD
  return date.toLocaleDateString("en-US", { year: "numeric", month: "short", day: "numeric" });
=======
  return new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(date);
>>>>>>> main
}

解決方法：main のバージョンでは、推奨される最新の Intl.DateTimeFormat API が使われています。このバージョンを採用し、コンフリクトマーカーを削除して、マージを完了します。

function formatDate(date: Date): string {
  return new Intl.DateTimeFormat("en-US", { dateStyle: "medium" }).format(date);
}

# Mark resolved and commit
git add src/utils/format.ts
git commit -m "merge main into feat/user-profile, adopt Intl.DateTimeFormat"

例 2 — ブランチ戦略の設定（GitHub Flow）

シナリオ：ある小規模なチームが、継続的デプロイに向けた軽量なブランチモデルを求めています。

# Ensure main is the default and protected branch
gh repo edit --default-branch main

# Create a feature branch from main
git checkout main && git pull
git checkout -b feat/dark-mode

# ... develop and commit ...
git add .
git commit -m "feat: add dark-mode toggle to settings page

Reads user preference from localStorage and applies the
'dark' class to <html>. Falls back to OS preference via
prefers-color-scheme media query."

# Push and open a pull request
git push -u origin feat/dark-mode
gh pr create \
  --title "feat: add dark-mode toggle" \
  --body "## Summary
- Adds a toggle in Settings that persists to localStorage
- Respects OS-level dark mode preference as default

## Test plan
- [ ] Toggle switches theme immediately
- [ ] Preference persists across page reloads
- [ ] Falls back to OS preference for new users"

# After review and CI pass, merge via GitHub
gh pr merge --squash --delete-branch

要点：main は常にデプロイ可能な状態に保ち、すべての変更をレビューと CI を伴う PR で行い、煩雑さを避けるためマージ後にブランチを削除します。

ベストプラクティス

• コミットはアトミックにします。 各コミットは、単独でコンパイルでき、テストに合格する論理的な変更を1つだけ表すようにします。これにより、bisect、revert、cherry-pickを確実に実行できます。
• シークレットは絶対にコミットしないでください。 最初のコミットを行う前に、.env、認証情報ファイル、秘密鍵を.gitignoreに追加します。意図しない情報漏えいを検出するには、git-secretsやtrufflehogなどのツールを使用します。
• フィーチャーブランチをリベースし、mainにマージします。 リベースするとフィーチャーブランチの履歴が直線的になり、レビューしやすくなります。mainにマージすると、マージコミットが明確な統合ポイントとして保持されます。
• --forceの代わりに--force-with-leaseを使用します。 リモートに、まだフェッチしていないコミットがある場合に処理を失敗させることで、チームメイトの作業を上書きしないようにします。
• リリースにタグを付けます。 本番リリースごとに注釈付きタグ（git tag -a v1.2.0 -m "Release 1.2.0"）を使用すると、デプロイされたコードを特定のコミットまでいつでも追跡できます。
• .gitignoreを包括的に保ちます。 使用する言語やフレームワーク用のテンプレート（github/gitignore）をベースにし、ビルド成果物、エディター設定、ローカル環境ファイルなど、プロジェクト固有の項目を追加します。

エッジケース

• Detached HEAD状態：ユーザーがタグまたは特定のコミットをチェックアウトしている場合は、コミット前に警告します。コミットがブランチに属さない状態になるのを防ぐため、先にブランチを作成するよう提案します。
• 大容量のバイナリファイル：Gitは大容量のバイナリファイル向けに設計されていません。画像、モデル、動画などのアセットにはGit LFSを推奨し、関連するLFS追跡ルールを追加します。
• 浅いクローン：blame、log、bisectなどの操作は、浅いクローン（--depth 1）では失敗することがあります。履歴に依存する操作を行う前に、git fetch --unshallowを実行します。
• サブモジュールとモノレポ：プロジェクトでサブモジュールを使用する場合は、セットアップ手順にgit submodule update --init --recursiveが含まれていることを確認します。モノレポでは、コミット時にパッケージごとの変更範囲を守ります。
• 強制プッシュ後に分岐したブランチ：チームメイトが共有ブランチに強制プッシュした場合は、ローカルの作業が失われないことを確認してから、git fetchに続けてgit reset --hard origin/<branch>を実行するよう案内します。まずチームと調整してください。