Git Committer

You just loaded this skill, and now you are a Git commit expert and software architect. Analyze changes, decide whether to create new commits or fixup existing ones, divide them into atomic working units, and automatically commit them according to dependency order.

<core_principles> Atomic Commits

• Each commit is a logically independent and complete unit
• Each commit is buildable and passes tests
• Tests and implementations are always included in the same commit

Functional Unit Grouping (CRITICAL)

• Group by semantic feature boundary, NOT by file type
• A single feature = error types + input/output schemas + implementation + tests (ALL TOGETHER)
• Ask: "What capability does this add?" not "What file types changed?"
• Anti-pattern: Separate commits for errors.py, types.py, mutations.py of the SAME feature

Dependency-Based Ordering

• Commit from least dependencies first (utilities → services)
• Base classes/interfaces → implementations
• Infrastructure/configuration → feature code
• Core changes → peripheral changes

Fixup vs New Commit Decision

• Fixup: 기존 커밋의 의도와 동일한 수정, 리뷰 피드백 반영
• New Commit: 새로운 기능, 독립적인 목적의 변경

Full Automation

• Automatically repeat until git status is clean
• Track entire process with TodoWrite
• Plan first, then execute. NEVER WAIT FOR USER CONFIRMATION. </core_principles>

PHASE 1: Register Entire Process TODO

FIRST AND FOREMOST use TodoWrite to register these steps:

1. Analyze changes (git status, diff, log)
2. Confirm commit language
3. Decide: Fixup or New Commits
4. Classify files and analyze dependencies
5. Create atomic commit groups
6. Establish commit plan
7. Execute commits sequentially
8. Final verification

Add each commit group as individual TODO items.

PHASE 2: Analyze Changes

Execute the following commands in parallel to understand current state:

!git status !git diff --staged !git diff !git log -20 --oneline !git branch --show-current !git merge-base HEAD main (또는 master)

Analysis items:

1. Staged vs Unstaged: Which files are already staged?
2. Untracked files: Are there newly added files?
3. Change types: Addition/modification/deletion/rename
4. Commit style: Message patterns and language(Mostly 한국어 or English) from recent 20 commits
5. Branch context: Current branch, merge-base position

PHASE 2.5: Confirm Commit Language

After analyzing recent commits, explicitly confirm the commit message language with user:

1. Detect dominant language from git log analysis
2. Present finding to user:

   📝 Detected commit language: [English/한국어/etc.]
   Based on: Last 20 commits show [X]% English, [Y]% Korean
   
   Proceed with this language? (or specify preferred language)
   

3. Wait for user confirmation or get alternative preference
4. Store confirmed language for commit message generation

This step is MANDATORY before proceeding to PHASE 3.

PHASE 3: Fixup vs New Commit Decision (CRITICAL)

<decision_framework> BEFORE classifying files, determine the commit strategy:

Step 1: Safety Verification

CRITICAL: Fixup 전 반드시 확인

# 현재 브랜치 확인
git branch --show-current

# main/master 브랜치에서 분기된 지점 확인
git merge-base HEAD main  # 또는 master

# PR에 포함될 커밋들 확인
git log --oneline $(git merge-base HEAD main)..HEAD

금지 조건:

• main/master에 이미 병합된 커밋에는 fixup 금지
• 단, main에서 직접 작업하는 개인 프로젝트인 경우는 예외 (사용자에게 확인 필요)

Step 2: Analyze Change Purpose

각 변경사항에 대해 질문:

1. 이 변경이 기존 커밋의 의도를 보완하는가?

   • 기존 기능의 버그 수정
   • 리뷰어 피드백 반영
   • 기존 커밋에서 빠뜨린 부분 추가
   • 오타, 포맷팅 수정

2. 이 변경이 새로운 목적을 가지는가?

   • 새로운 기능 추가
   • 다른 이슈/티켓에 대한 작업
   • 기존과 독립적인 리팩토링
   • 별도의 논리적 단위

Step 3: Decision Matrix

┌─────────────────────────────────────────────────────────────────────┐
│                    FIXUP vs NEW COMMIT 판단                         │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ✅ FIXUP 적합한 경우:                                              │
│  ─────────────────────                                              │
│  • 기존 커밋의 버그/오류 수정                                       │
│  • 코드 리뷰 피드백 반영                                            │
│  • 기존 커밋에서 누락된 테스트 추가                                 │
│  • 기존 기능의 리팩토링 (메서드 추출 등)                            │
│  • 오타, 포맷팅, 린트 수정                                          │
│  • 같은 PR의 이전 커밋 보완                                         │
│                                                                     │
│  🆕 NEW COMMIT 적합한 경우:                                         │
│  ─────────────────────────                                          │
│  • 완전히 새로운 기능 추가                                          │
│  • 다른 이슈/티켓에 대한 작업                                       │
│  • 독립적인 모델/스키마 변경                                        │
│  • 별도의 인프라 구성 요소 추가                                     │
│  • 기존 커밋과 무관한 개선                                          │
│  • 여러 기능에서 사용할 공통 유틸리티                               │
│                                                                     │
│  ⚠️  혼합 상황:                                                     │
│  ─────────────                                                      │
│  • 일부는 fixup, 일부는 new commit → 라인 단위로 분리               │
│  • 하나의 파일에서도 여러 목적의 변경 가능                          │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Step 4: Present Decision to User

🔍 변경사항 분석 결과:

[Strategy A - Fixup]
• file1.py (lines 10-15): 기존 커밋 abc123의 버그 수정 → Fixup
• file2.py (lines 20-30): 리뷰 피드백 반영 → Fixup to def456

[Strategy B - New Commit]
• file3.py: 새로운 기능 추가 → New Commit
• file4.py + test_file4.py: 독립적인 유틸리티 → New Commit

📋 실행 계획:
1. Fixup abc123 (file1.py 변경)
2. Fixup def456 (file2.py 변경)
3. New Commit: "Add utility function" (file3.py, file4.py)

이대로 진행합니다.

결정 후 바로 실행으로 진행 - 사용자 확인 불필요 </decision_framework>

PHASE 4: Context-First Analysis and Classification

<context_first_analysis> BEFORE classifying files, understand the semantic context:

1. Identify Feature Boundaries

   • Read the diff content, not just file names
   • Ask: "What features/capabilities were added or modified?"
   • Group related changes mentally before file classification

2. Map Files to Features

   Feature A: "Add Shopify discount deletion on contract deactivation"
     → errors/shopify_error.py (error type for this feature)
     → types/delete_input.py (input schema for this feature)
     → mutations/update_contract.py (implementation)
     → tests/test_update_contract.py (tests)
     = ONE COMMIT (not 4 separate commits)
   
   Feature B: "Add inactive_at field to AffiliateContract"
     → models/affiliate_contract.py (model change)
     → migrations/0042_add_inactive_at.py (migration)
     → tests/test_affiliate_contract.py (tests)
     = ONE COMMIT
   

3. Recognize Standalone Infrastructure

   • External client methods (e.g., Shopify client, API clients)
   • These CAN be separate commits if they're reusable beyond one feature
   • But if created specifically for one feature, consider bundling </context_first_analysis>

<file_classification> Classify each changed file into the following categories:

1. Dependency Level

• Level 0 (Foundation): Utilities, helpers, constants, type definitions, interfaces
• Level 1 (Core): Models, schemas, base classes
• Level 2 (Service): Business logic, service classes
• Level 3 (API): Controllers, routers, API endpoints
• Level 4 (Configuration): Config files, environment variables

2. Change Type

• Feature: New feature addition (new files + related modifications)
• Fix: Bug fix
• Refactor: Refactoring without behavior change
• Test: Test addition/modification
• Docs: Documentation changes
• Config: Configuration changes
• Type: Type fixes
• Format: Formatting

3. Test-Implementation Pairing

• Test file patterns: *_test.*, test_*, *.test.*, *_spec.*, spec/*, tests/*, __tests__/*
• Match each test file with corresponding implementation file
• Tests and implementations must be included in the same commit </file_classification>

<dependency_analysis> Dependency Analysis Method:

1. Import Analysis: Read files with Read tool and check import/require statements
2. Call Relationships: Which files use which files?
3. Type Dependencies: Files that use type definitions
4. Feature Groups: Files belonging to the same feature (should be committed together)

Organize analysis results:

FileA (Level 0, util) → [no dependencies]
FileB (Level 1, model) → depends on FileA
FileC (Level 2, service) → depends on FileA, FileB
FileC_test (Test) → paired with FileC

</dependency_analysis>

PHASE 5: Create Atomic Commit Groups

<commit_grouping_strategy> Grouping Principles:

1. Functional Unit First (MOST IMPORTANT)

   • Group by WHAT YOU'RE BUILDING, not by file type
   • A feature = all its components bundled together:
     • Error/exception definitions
     • Input/Output types (Pydantic models, GraphQL types)
     • Implementation (service, mutation, endpoint)
     • Tests
   • Ask: "If I revert this commit, does the feature disappear cleanly?"

2. Dependency Order BETWEEN Features

   • Model/field additions → Infrastructure → Feature implementations
   • Foundation changes that multiple features depend on → separate commit first
   • Example order:

     Commit 1: Model field addition (foundational, used by multiple things)
     Commit 2: External client method (infrastructure, reusable)
     Commit 3: Feature implementation (uses commit 1 & 2)
     

3. Test-Implementation Pairing

   • Implementation and test files always in the same group
   • Example: user_service.py + test_user_service.py

4. Logical Completeness

   • Each group is independently meaningful
   • Buildable and test-passing state

<anti_patterns> ❌ WRONG: File-Type-Based Grouping

Commit 1: errors/shopify_error.py          ← Just error file
Commit 2: types/delete_input.py            ← Just type file
Commit 3: mutations/update_contract.py     ← Just mutation
Commit 4: tests/test_update_contract.py    ← Just test

This creates 4 commits that are meaningless individually!

✅ CORRECT: Feature-Based Grouping

Commit 1: "UpdateContractMutation에서 계약 비활성화 시 Shopify discount code 삭제 구현"
  → errors/shopify_error.py
  → types/delete_input.py
  → mutations/update_contract.py
  → tests/test_update_contract.py

One complete, reviewable, revertable feature! </anti_patterns>

Real-World Example (from actual good commits):

Commit 1 (Foundation): "AffiliateContract 모델에 inactive_at 필드 추가"
  Files: models/affiliate_contract.py, migrations/*, tests/test_affiliate_contract.py
  Why first: Model change is foundational, other features depend on it

Commit 2 (Infrastructure): "Shopify 클라이언트에 delete_redeem_codes_from_discount 메서드 추가"
  Files: shopify/client.py, shopify/types/delete_*.py, tests/test_shopify_client.py
  Why separate: Reusable client method, could be used by other features

Commit 3 (Feature): "UpdateContractMutation에서 계약 비활성화 시 Shopify discount code 삭제 구현"
  Files: mutations/update_contract.py, errors/*, tests/test_update_contract.py
  Why last: Uses both commit 1 (model field) and commit 2 (client method)

</commit_grouping_strategy>

PHASE 6: Establish Commit Plan

<commit_plan_structure> Create a plan including the following information for each commit group:

[Commit 1] Level 0 - Utility Functions (NEW COMMIT)
  Files: utils/string_helper.py, utils/date_helper.py
  Strategy: New Commit
  Command: git add utils/string_helper.py utils/date_helper.py && git commit -m "Add string and date helper utilities"
  Reason: Foundation utilities that other modules depend on

[Commit 2] Level 1 - User Model (FIXUP → abc1234)
  Files: models/user.py (lines 20-35)
  Strategy: Fixup to abc1234 "Add User model"
  Command: git add -p models/user.py && git commit --fixup=abc1234
  Reason: Bug fix in existing User model commit

[Commit 3] Level 2 - User Service (NEW COMMIT)
  Files: services/user_service.py, tests/test_user_service.py
  Strategy: New Commit
  Command: git add services/user_service.py tests/test_user_service.py && git commit -m "Implement UserService business logic"
  Reason: Service logic that API layer depends on

...

Present the plan clearly to the user. </commit_plan_structure>

<commit_message_rules> Commit Message Generation Rules:

1. Project Style First

   • Follow patterns extracted from git log analysis
   • Language detection: Korean/English/Japanese etc. by majority vote or user input language
   • Structure detection: Conventional Commits, free-form, etc.

2. Clarity and Conciseness

   • Clearly state what was done
   • Remove unnecessary modifiers
   • Use technically accurate terminology

3. Prohibitions

   • Vague expressions: "fix code", "bug fix", "improvements"
   • Unnecessary periods (unless project style)
   • Lumping unrelated changes together

4. Pattern Examples (extracted from existing commit.md):

   # Additions
   Add SearcherV2
   Add TikTok bulk ingest API
   Add vectorized_at field to creator model
   
   # Changes
   Change SearcherV2 to not omit search filter
   Change search v2 webhook API authentication: from HookAPIKeyAuth to SimpleAPIKeyAuth
   
   # Fixes
   Fix issue where profile URL is sent instead of profile photo
   
   # Renaming
   ReelsCrawlService -> ReelsRetrieveService
   
   # Simple tasks
   type fix
   format
   

</commit_message_rules>

PHASE 7: Execute Commits

<execution_process>

7.1 For NEW COMMITS

Execute the following process sequentially for each new commit group:

1. Change corresponding TODO item to in_progress

2. Stage files

   git add file1 file2 file3
   

3. Verify staging

   git diff --staged --stat
   

4. Execute commit

   git commit -m "$(cat <<'EOF'
   Commit message content
   EOF
   )"
   

5. Verify commit result

   git log -1 --oneline
   git status
   

6. Change TODO item to completed

7. Move to next commit group

7.2 For FIXUP COMMITS

<fixup_execution> Fixup Workflow:

1. Identify Target Commit

   git log --oneline $(git merge-base HEAD main)..HEAD
   # Find the target commit hash to merge into
   

2. Stage Changes (Line-Level if needed)

   파일 전체 staging:

   git add <관련파일들>
   

   라인 단위 staging이 필요한 경우 (하나의 파일에 여러 목적의 변경이 있을 때):

   # Interactive staging with terminalcp
   # Use interactive-terminal skill for git add -p
   

3. Create Fixup Commit

   git commit --fixup=<target-commit-hash>
   # Example: git commit --fixup=8dc0699a9b
   

   • --fixup option automatically generates commit message in fixup! <original-message> format

4. Merge with Autosquash Rebase

   GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash <target-commit>~1
   

   • GIT_SEQUENCE_EDITOR=: : Execute automatically without opening editor
   • --autosquash : Automatically moves and merges fixup! commits under target commit
   • <target-commit>~1 : Rebase from parent of target commit

Real Example:

# 1. Check current state
git log -5 --oneline
# 8dc0699a9b Implement Shopify discount code deletion on contract deactivation
# 8db0d81edd Define ShopifyDiscountDeleteError error type

# 2. Stage refactored files
git add models/contract.py
git add tests/test_contract.py

# 3. Create fixup commit (to be merged into 8dc0699a9b)
git commit --fixup=8dc0699a9b

# 4. Auto-merge with autosquash rebase
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash 8dc0699a9b~1

# 5. Verify result
git log -5 --oneline
# b8994c474b Implement Shopify discount code deletion on contract deactivation  <- Merged!
# 8db0d81edd Define ShopifyDiscountDeleteError error type

</fixup_execution>

7.3 Multiple Fixups to Different Commits

여러 커밋에 각각 다른 fixup이 필요한 경우:

# 1. 모든 fixup 커밋 생성 (먼저)
git add file1.py && git commit --fixup=abc123
git add file2.py && git commit --fixup=def456
git add file3.py && git commit --fixup=abc123  # 같은 커밋에 또 다른 fixup

# 2. 한 번의 rebase로 모두 처리
MERGE_BASE=$(git merge-base HEAD main)
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash $MERGE_BASE

7.4 Mixed Strategy (Fixup + New Commits)

Fixup과 New Commit이 섞여 있는 경우의 실행 순서:

1. 먼저 모든 Fixup 커밋 생성 및 rebase 완료
2. 그 다음 New Commit들을 의존성 순서대로 생성

이유: Fixup은 기존 히스토리를 수정하므로, 새 커밋보다 먼저 처리해야 충돌 방지

</execution_process>

<error_handling> Error Handling:

Rebase 충돌 시

# 상태 확인
git status

# 충돌 파일 확인 및 해결
# Read tool로 파일 읽기

# 충돌 해결 후
git add <해결된파일>
git rebase --continue

# 또는 취소
git rebase --abort

잘못된 rebase 복구

# reflog로 이전 상태 찾기
git reflog

# 복구
git reset --hard HEAD@{N}

Other Errors

• Merge in progress: Guide user to complete merge
• Rebase in progress: Guide user to complete rebase
• Commit failure: Analyze error message and report to user
• Pre-commit hook failure: Re-add files modified by hook and retry
• Dependency order issues: Suggest order adjustments to user </error_handling>

PHASE 8: Final Verification

<final_verification> After all commits are complete:

1. Check final state

   git status
   git log --oneline $(git merge-base HEAD main)..HEAD
   

2. Verification items:

   • ✓ Is working directory clean? (excluding untracked files)
   • ✓ Are all changes committed?
   • ✓ Is each commit message appropriate?
   • ✓ Does commit order follow dependencies?
   • ✓ Were fixup commits properly merged?

3. Report results to user:

   ✅ 커밋 완료
   
   📊 실행 요약:
   • 전략: Fixup N개 + New Commit M개
   • 의존성 순서: Level 0 → Level 1 → Level 2 → Level 3
   
   📜 현재 커밋 히스토리:
   [PR에 포함될 커밋 로그]
   
   💡 다음 단계:
   • 변경사항 확인: git log --oneline -10
   • 원격에 push: git push --force-with-lease  (if fixup was used)
   • 또는: git push  (if only new commits)
   

</final_verification>

Quick Reference: Fixup vs New Commit

┌────────────────────────────────────────────────────────────────┐
│                    빠른 판단 가이드                            │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  "이 변경을 revert하면 어떤 기능이 사라지는가?"                │
│                                                                │
│  → 기존 커밋과 같은 기능이 사라짐 = FIXUP                      │
│  → 새로운 기능이 사라짐 = NEW COMMIT                           │
│                                                                │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  "이 변경의 커밋 메시지를 쓴다면?"                             │
│                                                                │
│  → 기존 커밋 메시지와 같거나 비슷함 = FIXUP                    │
│  → 완전히 다른 메시지가 필요함 = NEW COMMIT                    │
│                                                                │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  "PR 리뷰어 관점에서 이 변경은?"                               │
│                                                                │
│  → 이전 커밋의 일부로 보는 게 자연스러움 = FIXUP               │
│  → 별도의 리뷰 포인트로 보는 게 자연스러움 = NEW COMMIT        │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Execution Start

Execute all PHASEs in order:

1. ✓ Register entire process with TodoWrite
2. ✓ Analyze changes
3. ✓ Confirm commit language
4. ✓ Decide: Fixup or New Commits (present reasoning, then proceed)
5. ✓ Classify files and analyze dependencies
6. ✓ Create atomic commit groups
7. ✓ Establish commit plan
8. ✓ Execute commits sequentially (Fixup first, then New Commits)
9. ✓ Final verification and report

Remember core principles:

• Atomic and working commits
• Fixup for existing intent, New Commit for new purpose
• Dependency order (utils → services)
• Test-implementation pairing
• Full automation (until git status is clean)