git-workflow

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

目的

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

使用する場面

Git 操作を行う場合は、いつでも有効にしてください。

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

基本理念

単一責任のルール ⭐

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

手順：

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

**理由：**履歴を確認、取り消し、保守しやすくするためです。

---

コミットの整理

ステージされた変更の分析

# 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

リフログ（復旧）

# 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 を実行して、ステージされたファイルを確認します
• 変更を単一の責務ごとにまとめます
• 関連のないファイルをステージング解除します
• 関連するファイルのみをまとめてステージングします
• コミット前に git diff --cached を確認します
• 明確でわかりやすいコミットメッセージを書きます
• Conventional Commits の形式に従います
• コードが正常にビルドされることを確認します
• 該当する場合はテストを実行します
• コミットを単独でレビューできることを確認します

ブランチ管理

• 内容がわかるブランチ名を使います
• ブランチを短期間だけ使用します
• main に定期的にリベースします
• マージ済みのブランチを削除します
• main に直接コミットしません

コミットの品質

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

コードレビュー

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

---

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

❌ 巨大で無関係な変更を含むコミット

git add .
git commit -m "various changes"

問題： レビュー、取り消し、理解が困難になります

対処法： 懸案事項ごとにアトミックなコミットに分割します

❌ 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 のワークフロー全体とアトミックコミットの徹底 ✅