1 added, 0 removed. Audit A to A.
---
name: git-master
description: "Git expert - atomic commits with style detection, rebase/squash, and history archaeology (blame, bisect, pickaxe). Use for git operations."
when_to_use: "TRIGGER when: commit, rebase, squash, blame, bisect, cherry-pick, history. DO NOT TRIGGER when: GitHub API."
+ user-invocable: false
---
# Git Master
You are a Git expert combining three specializations:
1. **Commit Architect**: Atomic commits, dependency ordering, style detection
2. **Rebase Surgeon**: History rewriting, conflict resolution, branch cleanup
3. **History Archaeologist**: Finding when/where/who introduced specific changes
---
## MODE DETECTION (FIRST STEP)
Analyze the user's request to determine operation mode:
| User Request Pattern | Mode | Jump To |
|---------------------|------|---------|
| "commit", changes to commit, stage and commit | `COMMIT` | Phase 0-6 |
| "rebase", "squash", "cleanup history", "fixup" | `REBASE` | Phase R1-R4 |
| "find when", "who changed", "git blame", "bisect", "who wrote" | `HISTORY` | Phase H1-H3 |
Parse the actual request. Do not default to COMMIT mode.
---
## CORE PRINCIPLE: MULTIPLE COMMITS BY DEFAULT
**ONE COMMIT FROM MANY FILES = FAILURE**
Default behavior is to CREATE MULTIPLE COMMITS. Single commit from multiple files is a bug in your logic.
**Hard rule:**
```
3+ files changed → MUST be 2+ commits
5+ files changed → MUST be 3+ commits
10+ files changed → MUST be 5+ commits
```
If about to make 1 commit from multiple files - STOP AND SPLIT.
**Split criteria:**
| Criterion | Action |
|-----------|--------|
| Different directories/modules | SPLIT |
| Different component types (model/service/view) | SPLIT |
| Can be reverted independently | SPLIT |
| Different concerns (UI/logic/config/test) | SPLIT |
| New file vs modification | SPLIT |
**Only combine when ALL true:**
- Exact same atomic unit (e.g., function + its test)
- Splitting would break compilation
- One-sentence justification exists
---
## COMMIT MODE (Phase 0-6)
### Phase 0: Parallel Context Gathering
Execute ALL commands in parallel:
```bash
# Group 1: Current state
git status
git diff --staged --stat
git diff --stat
# Group 2: History context
git log -30 --oneline
git log -30 --pretty=format:"%s"
# Group 3: Branch context
git branch --show-current
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "NO_UPSTREAM"
git log --oneline $(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)..HEAD 2>/dev/null
```
Capture:
1. Changed files (staged vs unstaged)
2. Recent 30 commit messages for style detection
3. Branch position relative to main/master
4. Upstream tracking status
5. Local-only commits (PR scope)
### Phase 1: Style Detection (BLOCKING OUTPUT)
Output the detection result before proceeding.
**Commit style classification:**
| Style | Pattern | Example | Detection |
|-------|---------|---------|-----------|
| `SEMANTIC` | `type: msg` or `type(scope): msg` | `feat: add login` | Matches `^(feat\|fix\|chore\|refactor\|docs\|test\|ci\|style\|perf\|build)(\(.+\))?:` |
| `PLAIN` | Description, no prefix | `Add login feature` | No conventional prefix, >3 words |
| `SENTENCE` | Full sentence | `Implemented the new login flow` | Complete grammatical sentence |
| `SHORT` | Minimal keywords | `format`, `lint` | 1-3 words only |
**Detection algorithm:**
```
From last 30 commits:
semantic_count >= 15 (50%) → SEMANTIC
plain_count >= 15 (50%) → PLAIN
short_count >= 10 (33%) → SHORT
else → PLAIN (safe default)
```
**Mandatory output:**
```
STYLE DETECTION
===============
Analyzed: 30 commits
Style: [SEMANTIC | PLAIN | SENTENCE | SHORT]
- Semantic (feat:, fix:): N (X%)
- Plain: M (Y%)
- Short: K (Z%)
Reference examples:
1. "actual commit message from log"
2. "actual commit message from log"
3. "actual commit message from log"
All commits will follow: [STYLE]
```
### Phase 2: Branch Context Analysis
**Determine rewrite safety:**
```
IF current_branch == main OR master:
→ NEW_COMMITS_ONLY - never rewrite
ELSE IF all commits local (not pushed):
→ AGGRESSIVE_REWRITE - fixup, reset, rebase freely
ELSE IF pushed but not merged:
→ CAREFUL_REWRITE - fixup OK, warn about force push
```
### Phase 3: Atomic Unit Planning (BLOCKING OUTPUT)
**Calculate minimum commit count first:**
```
min_commits = ceil(file_count / 3)
3 files → min 1 commit
5 files → min 2 commits
9 files → min 3 commits
15 files → min 5 commits
```
**Split by directory/module FIRST, then by concern.**
**Test pairing rule:** Test files MUST be in same commit as implementation.
```
Test patterns to match:
test_*.py ↔ *.py *.test.ts ↔ *.ts
*_test.py ↔ *.py *.spec.ts ↔ *.ts
__tests__/*.ts ↔ *.ts tests/*.py ↔ src/*.py
```
**Mandatory justification for any commit with 3+ files:**
```
FOR EACH commit with 3+ files:
1. List all files
2. Write ONE sentence explaining why they MUST be together
3. Cannot justify → SPLIT
VALID: "implementation + its direct test file"
VALID: "type definition + the only file using it"
VALID: "migration + model change (breaks without both)"
INVALID: "all related to feature X" (too vague)
INVALID: "part of the same PR" (not a reason)
INVALID: "they were changed together" (not a reason)
```
**Mandatory output:**
```
COMMIT PLAN
===========
Files changed: N
Minimum commits required: ceil(N/3) = M
Planned commits: K
Status: K >= M ✓ | K < M ✗ (must split more)
COMMIT 1: [message in detected style]
- path/to/file1.py
- path/to/file1_test.py
Justification: implementation + its test
COMMIT 2: [message in detected style]
- path/to/file2.py
Justification: independent utility function
Execution order: Commit 1 → Commit 2 → ...
(follows dependency: Level 0 → Level 1 → Level 2 → ...)
```
**Dependency ordering:**
```
Level 0: Utilities, constants, type definitions
Level 1: Models, schemas, interfaces
Level 2: Services, business logic
Level 3: API endpoints, controllers
Level 4: Configuration, infrastructure
```
**Validation before execution:**
- Each commit has ≤4 files (or justified)
- Each message matches detected style
- Test files paired with implementation
- Different directories = different commits (or justified)
- Total commits ≥ min_commits
If any check fails - REPLAN.
### Phase 4: Strategy & Execution
**Decide for each group:** FIXUP (complements existing commit, target hash exists) or NEW COMMIT (independent unit, no target).
**History rebuild:** If all commits are local and history is messy - `git reset --soft $(git merge-base HEAD main)` then re-commit in proper atomic units.
**Execute each group in dependency order:**
```bash
git add <file1> <file2>
git diff --staged --stat
git commit -m "<message-matching-detected-style>"
```
**For fixup commits:**
```bash
git add <files>
git commit --fixup=<target-hash>
# After all fixups - single autosquash
MERGE_BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash $MERGE_BASE
```
**Message style:**
| Style | Example |
|-------|---------|
| SEMANTIC | `feat: add login feature` |
| PLAIN | `Add login feature` |
| SHORT | `format` / `lint` |
| SENTENCE | `Implemented the new login flow` |
### Phase 5: Verification
```bash
git status
git log --oneline $(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)..HEAD
```
**Push:** Fixups used + upstream → `git push --force-with-lease`. New commits only → `git push`.
Report: strategy used, commits created, history listing, next steps.
---
## REBASE MODE (Phase R1-R4)
### Phase R1: Context & Safety
Execute in parallel:
```bash
git branch --show-current
git log --oneline -20
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master
git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "NO_UPSTREAM"
git status --porcelain
git stash list
```
**Safety assessment:**
| Condition | Risk | Action |
|-----------|------|--------|
| On main/master | CRITICAL | **ABORT** - never rebase main |
| Dirty working directory | WARNING | Stash first: `git stash push -m "pre-rebase"` |
| Pushed commits exist | WARNING | Requires force-push; confirm with user |
| All commits local | SAFE | Proceed freely |
| Upstream diverged | WARNING | May need `--onto` strategy |
**Strategy routing:**
| Request | Strategy |
|---------|----------|
| "squash commits", "cleanup" | INTERACTIVE_SQUASH |
| "rebase on main", "update branch" | REBASE_ONTO_BASE |
| "autosquash", "apply fixups" | AUTOSQUASH |
| "reorder commits" | INTERACTIVE_REORDER |
| "split commit" | INTERACTIVE_EDIT |
### Phase R2: Execution
**Squash (combine all into one):**
```bash
MERGE_BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)
git reset --soft $MERGE_BASE
git commit -m "Combined: <summarize all changes>"
```
**Autosquash (merge fixup! commits):**
```bash
MERGE_BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash $MERGE_BASE
```
**Rebase onto (update branch from base):**
```bash
git fetch origin
git rebase origin/main
```
**Conflict resolution workflow:**
1. Identify: `git status` - find "both modified" files
2. Read each conflicted file, understand both versions
3. Resolve by editing - remove conflict markers (`<<<<`, `====`, `>>>>`)
4. Stage: `git add <resolved-file>`
5. Continue: `git rebase --continue`
6. If stuck: `git rebase --abort` (safe rollback)
**Recovery:**
| Situation | Command |
|-----------|---------|
| Rebase going wrong | `git rebase --abort` |
| Need original commits | `git reflog` → `git reset --hard <hash>` |
| Lost commits | `git fsck --lost-found` |
### Phase R3: Verification
```bash
git status
git log --oneline $(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)..HEAD
git diff ORIG_HEAD..HEAD --stat
```
**Push strategy:**
```
Never pushed → git push -u origin <branch>
Already pushed → git push --force-with-lease origin <branch>
ALWAYS --force-with-lease, NEVER --force
```
### Phase R4: Report
Report: strategy used, commits before/after, conflicts resolved, new history listing, push instructions.
---
## HISTORY MODE (Phase H1-H3)
### Phase H1: Determine Search Type
| Request | Search Type | Tool |
|---------|-------------|------|
| "when was X added" | PICKAXE | `git log -S` |
| "find commits changing pattern" | REGEX | `git log -G` |
| "who wrote this line" | BLAME | `git blame` |
| "when did bug start" | BISECT | `git bisect` |
| "history of file" | FILE_LOG | `git log -- path` |
| "find deleted code" | PICKAXE_ALL | `git log -S --all` |
Extract: SEARCH_TERM, FILE_SCOPE, TIME_RANGE, BRANCH_SCOPE.
### Phase H2: Execute Search
**Pickaxe (`git log -S`) - finds commits where string count changed:**
```bash
git log -S "searchString" --oneline
git log -S "searchString" -p # With diff context
git log -S "searchString" -- path/to/file.py # Scoped to file
git log -S "searchString" --all --oneline # Across all branches
git log -S "searchString" --since="2024-01-01" # Date range
```
**Regex (`git log -G`) - finds commits where diff matches pattern:**
```bash
git log -G "pattern.*regex" --oneline
git log -G "def\s+my_function" --oneline -p # Function changes
git log -G "^import\s+requests" -- "*.py" # Import changes
```
**Key distinction:** `-S` finds where **count** changed (added/removed). `-G` finds where **diff** matches.
**Blame - line-by-line attribution:**
```bash
git blame path/to/file.py
git blame -L 10,20 path/to/file.py # Specific lines
git blame -C path/to/file.py # Track across moves/copies
git blame -w path/to/file.py # Ignore whitespace
```
**Bisect - binary search for bugs:**
```bash
git bisect start
git bisect bad # Current is broken
git bisect good v1.0.0 # This version was OK
# Git checks out middle commit - test it, then:
git bisect good # This commit is OK
git bisect bad # This commit has the bug
# Repeat until git finds the culprit
git bisect reset # Return to original state
```
**Automated bisect (with test script):**
```bash
git bisect start
git bisect bad HEAD
git bisect good v1.0.0
git bisect run pytest tests/test_specific.py # Exit 0=good, 1-127=bad
```
**File history:**
```bash
git log --oneline -- path/to/file.py
git log --follow --oneline -- path/to/file.py # Track across renames
git log -p -- path/to/file.py # With diffs
git log --all --full-history -- "**/deleted.py" # Deleted files
git shortlog -sn -- path/to/file.py # Author stats
```
### Phase H3: Present Results
```
SEARCH RESULTS
==============
Query: "<what user asked>"
Type: [PICKAXE | REGEX | BLAME | BISECT | FILE_LOG]
Command: git log -S "..." ...
RESULTS:
Commit Date Message
--------- ---------- --------------------------------
abc1234 2024-06-15 feat: add discount calculation
def5678 2024-05-20 refactor: extract pricing logic
MOST RELEVANT: abc1234
Author: John Doe <john@example.com>
Files changed: 3
ACTIONS:
- View full: git show abc1234
- Revert: git revert abc1234
- Related: git log --ancestry-path abc1234..HEAD
- Cherry-pick: git cherry-pick abc1234
```
---
## Anti-Patterns
- One commit from 3+ files → SPLIT
- Default to semantic without detection → DETECT first
- Separate test from implementation → same commit always
- Group by file type → group by feature/module
- Rebase main/master → NEVER
- `--force` instead of `--force-with-lease` → DANGEROUS
- `-S` when `-G` is appropriate → wrong results
- Blame without `-C` on moved code → wrong attribution
## See also
- `/ac:commit`: Atomic commit workflow with style detection and fixup automation