Commit Tidy

Topics

Analyze staged/unstaged changes and recommend whether to split into multiple commits.

When to use

• Before committing large changesets
• User asks "should I split this commit?"
• Reviewing changes that touch many files
• Ensuring atomic, reviewable commits

Split Decision Criteria

Split when

1. Unrelated functionality changes
• Feature A + Bug fix B → 2 commits
• UI change + API change (if independent) → 2 commits

1. Wide file spread
• Changes span 5+ directories with no common purpose
• Frontend + Backend + Config all modified

1. Mixed change types
• Refactoring + New feature → 2 commits
• Formatting + Logic change → 2 commits
• Dependency update + Code change → 2 commits

1. Large diff size
• 500+ lines changed across unrelated areas
• Multiple components modified independently

1. Different reviewers needed
• Changes require different domain expertise
• Security-sensitive + general changes

Keep together when

1. Single logical change
• Feature requires touching multiple files
• Refactoring that must be atomic

1. Dependent changes
• API change + caller updates
• Schema change + migration + model update

1. Related cleanup
• Feature + directly related tests
• Bug fix + regression test

Squash Criteria

When analyzing multiple commits, recommend squashing as well as splitting.

Squash when

1. Same type + same purpose
• test: A test + test: B test (tests for the same feature) → squash into 1
• fix: typo A + fix: typo B (same review feedback) → squash into 1

1. Commits split per loop by automated agents
• Autonomous agents like Ralph commit per loop → squash if same purpose
• Example: proxy test in loop 1, OIDC test in loop 2 → test: add unit tests

1. Consecutive WIP commits
• wip: in progress + feat: complete → squash into one feat

Don't squash

1. Commits with different types — keep test + chore + feat separate
2. Commits belonging to different PRs/issues
3. Independent changes that may need to be reverted

Output format (when recommending squash)

### Recommendation: Squash 2 commits → 1

**Before** (2 commits):
- 441b966a test(dt): OIDC auth, proxy, SSO tests
- e2b6503a test(dt): OIDC route tests (login, callback, me)

**After** (1 commit):
- test(dt): add OIDC auth unit tests

**Reasoning**: Same type (test), same feature (OIDC auth), agent loop split

Instructions

Step 0: Determine scope

When ARGUMENTS specify a range (e.g., "since main", "last 3 commits", "PR #N"), analyze all changes in that range — both committed and uncommitted.

# Range specified (e.g., "X changes since main")
git log --oneline <base>..HEAD -- <path>     # committed changes
git diff <base>..HEAD --stat -- <path>        # committed diff
git diff HEAD --stat -- <path>                # uncommitted diff

The analysis must cover committed commits (squash/split candidates) + uncommitted changes (new commit candidates) as a single unified view. Do not analyze only uncommitted changes when a range is specified.

When no range is specified, default to staged + unstaged changes only.

Step 1: Analyze changes

# Check staged changes
git diff --cached --stat
git diff --cached --name-only

# Check unstaged changes
git diff --stat
git status

Step 2: Categorize files

Group changed files by:

• Feature/Component: Which feature does this belong to?
• Change type: feat, fix, refactor, style, test, docs, chore
• Directory: Are changes localized or spread out?

Step 3: Identify boundaries

Look for natural split points:

• Different conventional commit types
• Independent functionality
• Separate test files from implementation (if tests are for different features)

Step 4: Recommend split strategy

Provide specific recommendations:

## Analysis Results

### Changed Files (N files)
- src/api/... (3 files) - API endpoints
- src/components/... (2 files) - UI components
- tests/... (2 files) - Tests

### Recommendation: Split into N commits

**Commit 1**: feat: add user profile API
- src/api/user.ts
- src/api/types.ts
- tests/api/user.test.ts

**Commit 2**: feat: add profile UI component
- src/components/Profile.tsx
- src/components/Profile.css
- tests/components/Profile.test.tsx

### Reasoning
- API and UI can function independently
- Each can be reviewed by different reviewers

Step 5: Execute split (if requested)

# Unstage all
git reset HEAD

# Stage first commit files
git add src/api/ tests/api/
git commit -m "feat: add user profile API"

# Stage second commit files
git add src/components/ tests/components/
git commit -m "feat: add profile UI component"

Quick Reference

File spread heuristic

Change type combinations to split

Output Format

Analysis results should include:

1. List of changed files with categories
2. Whether split is needed and why
3. Specific commit splitting plan
4. Suggested commit messages for each
5. Execution commands (if requested)