| name | git-commit-granularity |
| description | Gitコミットの粒度(サイズ・単位)ベストプラクティスに従い、アトミックで単一概念のコミットへ分割・整形するガイドを提供する。git add -pによるハンクステージング、セマンティックギャップの回避、クリーンな履歴の構築手順をカバーする。コミット作成時、既存コミットのリファクタリング前、コードレビューでのコミット単位の見直し時に使う。コンフリクト解消、PRマージ、リポジトリの初期セットアップには使わない。 |
Git コミット粒度ガイド
手順
Step 1: 現在の差分を把握する
- 作業ツリーの変更全体を確認する:
git status
git diff --stat
- ステージ済みの変更を確認する:
git diff --cached --stat
- 変更が複数の目的・概念を含む場合は Step 2 へ進む。単一概念であれば Step 4 へスキップする。
Step 2: 差分を論理グループへ分類する
- 差分を論理グループ(バグ修正・機能追加・リファクタリング・タイポ修正など)へ分類する。
- セマンティックギャップ(コードが壊れた中間状態)が生じないかを確認する。判断基準はスキル同梱の
references/granularity-rules.md を読む。
- 各グループが「関数の移動」を伴う場合は、削除と追加を必ず同一コミットに含める(セマンティックギャップ防止)。
Step 3: ハンク単位でステージングする(git add -p)
- インタラクティブなハンクステージングを起動する:
git add -p
- 各ハンクに対してキーを入力する:
y — 現在のグループに属するハンクを採択
n — 次のコミットに回す
s — ハンクをさらに分割(より細かい粒度が必要な場合)
e — ハンクを手動編集(行単位の選択が必要な場合)
q — ステージング終了
- ステージ内容を確認する:
git diff --cached
- 意図した変更のみが含まれていることを確認する。含まれていない場合は
git restore --staged <file> でアンステージし直す。
Step 4: コンパイル/テストの通過確認
- ステージ済みの差分のみで、コードが動作する状態を維持しているか確認する。
- テストスイートまたはビルドを実行する:
npm test / yarn test / pnpm test
go test ./...
pytest
make build
- ビルドまたはテストが失敗した場合は Step 2 へ戻り、セマンティックギャップが生じていないか再確認する。
Step 5: コミットメッセージを作成する
- コミットメッセージの書式を確認する: スキル同梱の
references/granularity-rules.md
- Conventional Commits 形式で書く:
<type>(<scope>): <概要>(50文字以内)
[本文: 変更した理由、背景(任意)]
[フッター: BREAKING CHANGE / 関連 issue 番号(任意)]
type の選択例:
fix — バグ修正
feat — 機能追加
refactor — 振る舞いを変えないリファクタリング
chore — ビルド・設定変更
docs — ドキュメントのみの変更
style — フォーマット・タイポ修正
Step 6: コミットを実行する
- コミットを実行する:
git commit
- 複数のグループが残っている場合は Step 3 へ戻り、次のグループをステージして繰り返す。
- すべてのグループをコミットし終えたら、履歴を確認する:
git log --oneline -n 10
Step 7: 既存コミットの整理(Push 前のみ)
- リモートへの Push 前で、かつローカル履歴が冗長な場合はインタラクティブリベースで整理する:
git rebase -i HEAD~<対象コミット数>
pick を squash(s)または fixup(f)へ変更して論理的にまとめる。
reword(r)でコミットメッセージを修正する。
- 注意: すでに Push 済みのコミットには
rebase -i を使わない。
エラーハンドリング
git add -p でハンク分割後にビルドが壊れる場合は、セマンティックギャップが発生している。削除と追加が分離されていないかスキル同梱の references/granularity-rules.md を再確認する。
- コミット単位の判断が難しい場合はスキル同梱の
scripts/check_granularity.py を実行して差分の概要を得る。
git rebase -i で競合が発生した場合は git rebase --abort で中断し、安全な状態へ戻す。
- Conventional Commits の type 選択が迷う場合はスキル同梱の
references/granularity-rules.md の判定フローを参照する。