git-workflow

Git ワークフローとベストプラクティス

目的

クリーンな履歴、アトミックなコミット、プロフェッショナルなワークフローを重視した、Git 操作の包括的なガイドです。ステージ済みの変更を自動的に分析し、単一責任の原則を徹底します。

使用するタイミング

あらゆる Git 操作で有効にしてください。

• 変更のコミット（特に複数のファイル）
• ブランチの作成
• マージまたはリベース
• Git 履歴の管理
• コミットメッセージの作成
• ステージングエリアの整理
• コードレビューの準備
• リポジトリの管理

基本理念

単一責任のルール ⭐

重要： コミットする前に、ステージ済みの変更を分析し、アトミックなコミットに分割してください。

手順：

1. git status を実行して、ステージ済みのファイルをすべて確認します
2. 異なる関心事や機能を特定します
3. すべてをステージから外します：git reset HEAD
4. 関心事ごとに、グループを1つずつステージします
5. 各グループを、内容に焦点を当てたメッセージでコミットします
6. すべての変更がコミットされるまで繰り返します

理由： 履歴のレビュー、取り消し、保守が容易になります。

⛔ コミット前の必須確認

自問してください：「明日、これらの変更のうち1つだけを取り消す必要が生じた場合、それは可能だろうか？」

• いいえ → 複数の関心事が含まれています → 必ず別々のコミットに分割してください
• はい → 1つのコミットに進みます

よくある落とし穴：「すべてのファイルが同じ機能リクエストに関連している」は、まとめてコミットする正当な理由にはなりません。個別に取り消せる変更は、それぞれ別のコミットにしてください。

---

コミットの整理

ステージ済みの変更の分析

# Check what's staged
git status

# See file-level summary
git diff --cached --stat

# See detailed changes
git diff --cached

# Check specific file
git diff --cached path/to/file

グループ化の方針

機能別：

• 認証システムの変更 → 1つのコミット
• 決済モジュール → 別のコミット
• ユーザープロフィール → さらに別のコミット

レイヤー別：

• データベースのマイグレーション → 最初のコミット
• バックエンド API → 2番目のコミット
• フロントエンド UI → 3番目のコミット
• テスト → 4番目のコミット

種類別：

• 新機能（feat）
• バグ修正（fix）
• リファクタリング（refactor）
• ドキュメント（docs）
• パフォーマンス（perf）
• テスト（test）

依存関係別：

• 基盤／インフラを先に
• 基盤に依存する機能を次に

分割のワークフロー

# 1. Analyze current state
git status
git diff --cached --stat

# 2. Unstage everything
git reset HEAD

# 3. Stage first logical group
git add file1.ts file2.ts directory/

# 4. Verify what's staged
git diff --cached --stat

# 5. Commit with focused message
git commit -m "type: concise description"

# 6. Repeat steps 3-5 for remaining groups

例：実際のシナリオ

状況： 関心事が混在した29個のファイルがステージ済み

# Before - messy staging
$ git status
Changes to be committed:
  # Trading Styles feature (25 files)
  modified:   src/app/styles/page.tsx
  new file:   src/core/domain/models/TradingStyle.ts
  new file:   src/infrastructure/database/migrations/create_trading_styles.ts
  ...
  # History enhancements (4 files)
  modified:   src/app/history/page.tsx
  modified:   src/app/api/history/recommendations/route.ts
  ...

解決策：

# 1. Reset staging
git reset HEAD

# 2. Commit #1 - Trading Styles feature
git add \
  package.json pnpm-lock.yaml \
  src/app/styles/ \
  src/core/domain/models/TradingStyle.ts \
  src/core/ports/ITradingStyleRepository.ts \
  src/infrastructure/database/TradingStyleRepository.ts \
  src/infrastructure/database/migrations/create_trading_styles.ts

git commit -m "feat: Add trading style persona system for AI-powered analysis"

# 3. Commit #2 - History enhancements
git add \
  src/app/history/page.tsx \
  src/app/api/history/recommendations/route.ts \
  src/infrastructure/database/TimeseriesRepository.ts \
  src/components/layout/AppLayout.tsx

git commit -m "feat: Add comprehensive search and filtering to history page"

結果： 個別にレビューや取り消しができる、整理された内容に焦点を当てたコミットになります。

---

コミットメッセージ

Conventional Commits 形式

<type>(<scope>): <subject>

<body>

<footer>

種類

• feat - 新機能
• fix - バグ修正
• refactor - コードの再構成（動作の変更なし）
• perf - パフォーマンスの改善
• docs - ドキュメントのみ
• style - フォーマット、空白、セミコロン
• test - テストの追加／更新
• chore - メンテナンス、依存関係
• build - ビルドシステムの変更
• ci - CI/CD の設定
• revert - 以前のコミットの取り消し

件名のルール

• 命令形を使います：「Add feature」のように書き、「Added feature」とは書きません
• 小文字で始めます（先頭を大文字にしません）
• 末尾にピリオドを付けません
• 最大50文字にします
• 具体的で説明的な内容にします

本文のガイドライン

• HOW ではなく、WHAT と WHY を説明します
• 72文字で折り返します
• 複数の変更がある場合は箇条書きを使います
• Issue 番号を参照します：Fixes #123
• 破壊的変更を含めます

例

良い例：

git commit -m "$(cat <<'EOF'
feat: add trading style filtering to history page

Implemented comprehensive search and filtering:
- Multi-criteria filtering (action, type, risk, style)
- Partial symbol search with case-insensitive matching
- LEFT JOIN with trading_styles table
- Extended API with new query parameters

Fixes #456
EOF
)"

悪い例：

git commit -m "Fixed stuff"
git commit -m "WIP"
git commit -m "Updated files"

---

ブランチ戦略

ブランチの命名

形式： type/description-in-kebab-case

種類：

• feature/ - 新機能
• fix/ - バグ修正
• refactor/ - コードの改善
• docs/ - ドキュメント
• test/ - テストの追加
• chore/ - メンテナンス

例：

feature/trading-style-personas
fix/history-filter-bug
refactor/database-queries
docs/api-documentation

ブランチのワークフロー

# Create and switch to new branch
git checkout -b feature/new-feature

# Work on changes
git add ...
git commit -m "..."

# Keep branch updated with main
git fetch origin
git rebase origin/main

# Push to remote
git push origin feature/new-feature

# Create pull request (via GitHub/GitLab UI)

ブランチの管理

# List all branches
git branch -a

# Switch branches
git checkout branch-name

# Delete local branch
git branch -d branch-name

# Delete remote branch
git push origin --delete branch-name

# Rename current branch
git branch -m new-name

---

ステージング操作

選択的なステージング

# Stage specific files
git add file1.ts file2.ts

# Stage entire directory
git add src/features/

# Stage all changes
git add .

# Stage by file extension
git add *.ts

# Interactive staging (patch mode)
git add -p file.ts

パッチモードでの操作

git add -p を使う場合：

• y - このハンクをステージする
• n - このハンクをステージしない
• s - より小さなハンクに分割する
• e - ハンクを手動で編集する
• q - 終了する
• ? - ヘルプを表示する

ステージ解除

# Unstage all files
git reset HEAD

# Unstage specific file
git restore --staged file.ts

# Unstage directory
git restore --staged src/features/

---

履歴の管理

履歴の表示

# Compact history
git log --oneline -10

# Detailed history
git log -5

# With file changes
git log --stat -3

# Specific file history
git log -- path/to/file

# Graph view
git log --oneline --graph --all

# Search commits
git log --grep="search term"

# By author
git log --author="name"

# Date range
git log --since="2 weeks ago"

コミットの修正

# Add forgotten files to last commit
git add forgotten-file.ts
git commit --amend --no-edit

# Change last commit message
git commit --amend -m "new message"

⚠️ 警告： プッシュしていないコミットのみを修正してください！

対話的リベース

# Rebase last 3 commits
git rebase -i HEAD~3

# Rebase from specific commit
git rebase -i commit-hash

オプション：

• pick - コミットをそのまま保持する
• reword - コミットメッセージを変更する
• edit - コミットを編集する
• squash - 直前のコミットとまとめる
• fixup - squash と同様ですが、メッセージは破棄します
• drop - コミットを削除する

コミットのスカッシュ

プッシュする前に：

# Squash last 3 commits
git rebase -i HEAD~3
# Mark commits as "squash" or "fixup"

チェリーピック

# Apply specific commit to current branch
git cherry-pick commit-hash

# Cherry-pick multiple commits
git cherry-pick hash1 hash2 hash3

---

マージとリベース

マージとリベースの違い

マージ：

• マージコミットを作成します
• 完全な履歴を保持します
• 用途：機能ブランチを main に統合する

git checkout main
git merge feature/new-feature

リベース：

• 履歴を書き換え、直線的なタイムラインにします
• 履歴がよりすっきりします
• 用途：main の変更を機能ブランチに取り込む

git checkout feature/new-feature
git rebase main

マージ戦略

ファストフォワード（デフォルト）：

git merge feature/branch

ファストフォワードなし（常にマージコミットを作成）：

git merge --no-ff feature/branch

スカッシュ（すべてのコミットをまとめる）：

git merge --squash feature/branch
git commit -m "feat: merged feature"

コンフリクトの解決

# Check conflict status
git status

# View conflicts
git diff

# After resolving conflicts in editor
git add resolved-file.ts

# Continue rebase
git rebase --continue

# Or abort
git rebase --abort

---

リモート操作

リモートの操作

# View remotes
git remote -v

# Add remote
git remote add origin https://github.com/user/repo.git

# Update remote URL
git remote set-url origin new-url

# Fetch from remote
git fetch origin

# Pull with rebase
git pull --rebase origin main

# Push to remote
git push origin branch-name

# Force push (use carefully!)
git push --force-with-lease origin branch-name

プルリクエストのワークフロー

# 1. Update local main
git checkout main
git pull origin main

# 2. Create feature branch
git checkout -b feature/new-feature

# 3. Make changes and commit atomically
# (following single-responsibility rule)

# 4. Keep branch updated
git fetch origin
git rebase origin/main

# 5. Push to remote
git push origin feature/new-feature

# 6. Create PR via GitHub/GitLab UI

# 7. Address review feedback
git add .
git commit -m "fix: address review comments"
git push origin feature/new-feature

# 8. After PR merged, clean up
git checkout main
git pull origin main
git branch -d feature/new-feature

---

高度なテクニック

スタッシュ

# Stash current changes
git stash

# Stash with message
git stash save "work in progress"

# List stashes
git stash list

# Apply last stash
git stash apply

# Apply and remove stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Drop stash
git stash drop stash@{0}

# Clear all stashes
git stash clear

タグ付け

# Create lightweight tag
git tag v1.0.0

# Create annotated tag
git tag -a v1.0.0 -m "Release version 1.0.0"

# List tags
git tag

# Push tag to remote
git push origin v1.0.0

# Push all tags
git push origin --tags

# Delete tag
git tag -d v1.0.0
git push origin --delete v1.0.0

二分探索（バグの特定）

# Start bisect
git bisect start

# Mark current commit as bad
git bisect bad

# Mark known good commit
git bisect good commit-hash

# Git will checkout middle commit
# Test it, then mark as good or bad
git bisect good  # or git bisect bad

# Repeat until bug is found
# Reset after finding
git bisect reset

reflog（復旧）

# View reflog
git reflog

# Recover lost commit
git reset --hard commit-hash

# Recover deleted branch
git checkout -b recovered-branch commit-hash

---

Git Ignore

.gitignore のパターン

# Ignore file
secret.env

# Ignore directory
node_modules/

# Ignore by extension
*.log

# Ignore except specific file
!important.log

# Ignore in all subdirectories
**/debug.log

よく使われる除外項目

# Dependencies
node_modules/
vendor/

# Build outputs
dist/
build/
*.exe

# Environment
.env
.env.local

# IDE
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

---

ベストプラクティスのチェックリスト

コミットする前に

• git status を実行して、ステージングされたファイルを確認する
• ⛔ GATE：「変更を1つだけ独立して元に戻せますか？」いいえの場合 → コミットを分割する
• 変更を単一の責務ごとにまとめる
• 無関係なファイルをステージングから外す
• 関連するファイルだけをまとめてステージングする
• コミットする前に git diff --cached を確認する
• 明確で説明的なコミットメッセージを書く
• Conventional Commits の形式に従う
• コードが正常にビルドできることを確認する
• 該当する場合はテストを実行する
• コミットが単独でレビュー可能であることを確認する

ブランチ管理

• 内容がわかるブランチ名を使う
• ブランチの存続期間を短く保つ
• main の変更を定期的にリベースする
• マージ済みのブランチを削除する
• main に直接コミットしない

コミットの品質

• アトミックなコミット（1つのコミットにつき1つの論点）
• 意味のあるコミットメッセージ
• WIP や「fix stuff」のようなメッセージを使わない
• コメントアウトしたコードをコミットに含めない
• 生成ファイルを含めない（必要な場合を除く）
• シークレットや認証情報を含めない

コードレビュー

• 小さく、焦点を絞ったプルリクエストにする
• 説明的な PR タイトルと説明を書く
• 関連する Issue を参照する
• レビューを依頼する前に自分でレビューする
• すべてのレビューコメントに対応する
• レビュー中もコミットを整理された状態に保つ

---

避けるべきアンチパターン

❌ 巨大で雑多なコミット

git add .
git commit -m "various changes"

問題： レビュー、取り消し、内容の理解ができません

対処法： 論点ごとにアトミックなコミットへ分割します

❌ 「関連する」変更の一括化

# Multiple features bundled because "they're all for the same task"
git add src/components/Form.tsx src/components/PDFExport.tsx src/types/ src/config/
git commit -m "feat: add form and PDF export with new field types"

問題：「同じ依頼に関連する」≠「同じコミット」。Form を失わずに PDF を元に戻すことはできません。

確認方法： これらの機能のうち、1つだけを独立して元に戻せますか？できない場合は分割します。

対処法：

git add src/config/ src/types/
git commit -m "feat: add field mapping configuration"

git add src/components/Form.tsx
git commit -m "feat: add editable form component"

git add src/components/PDFExport.tsx
git commit -m "feat: add PDF export with bank-style layout"

❌ main への直接コミット

git checkout main
git commit -m "quick fix"
git push

問題： コードレビューを回避することになり、リスクがあります

対処法： 必ず機能ブランチを使います

❌ 共有ブランチへの強制プッシュ

git push --force origin main

問題： 他の人の作業を破壊し、履歴を壊します

対処法： --force-with-lease を使い、自分のブランチにのみ実行します

❌ 大きなバイナリファイル

git add large-video.mp4
git commit -m "add video"

問題： リポジトリのサイズがいつまでも肥大化します

対処法： Git LFS または外部ストレージを使います

❌ シークレットのコミット

git add .env
git commit -m "add config"

問題： セキュリティ上の脆弱性につながり、削除も困難です

対処法： .gitignore、環境変数、シークレット管理を使います

❌ 意味のないメッセージ

git commit -m "fix"
git commit -m "update"
git commit -m "wip"

問題： デバッグに役立たない履歴になります

対処法： 説明的で具体的なコミットメッセージを書きます

---

クイックリファレンス

基本コマンド

# Status and diff
git status
git diff
git diff --cached
git diff --stat

# Staging
git add file.ts
git add .
git reset HEAD
git restore --staged file.ts

# Committing
git commit -m "message"
git commit --amend

# Branching
git branch
git checkout -b branch-name
git branch -d branch-name

# History
git log --oneline -10
git log --stat
git show commit-hash

# Remote
git fetch origin
git pull --rebase
git push origin branch-name

# Stashing
git stash
git stash pop

復旧コマンド

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Undo changes to file
git restore file.ts

# Recover deleted branch
git reflog
git checkout -b branch-name commit-hash

---

リソース

• Conventional Commits： https://www.conventionalcommits.org/
• Git Book： https://git-scm.com/book/en/v2
• Oh Shit, Git!： https://ohshitgit.com/

---

ステータス：本番環境で使用可能 ✅ 行数：約480行（500行ルール以内）✅ カバレッジ：Git のワークフロー全体 ＋ アトミックコミットの徹底 ✅