/semantic-commit

Split changes into semantic units and commit

Breaks big changes into small, meaningful commits with proper messages. Uses only standard git commands.

Usage

/semantic-commit [options]

Options

• `--dry-run`: Show proposed commit splits without actually committing
• `--lang <language>`: Force language for commit messages (en)
• `--max-commits <number>`: Specify maximum number of commits (default: 10)

Basic Examples

# Analyze current changes and commit in logical units
/semantic-commit

# Check split proposal only (no actual commit)
/semantic-commit --dry-run

# Generate commit messages in English
/semantic-commit --lang en

# Split into maximum 5 commits
/semantic-commit --max-commits 5

How It Works

1. **Analyze Changes**: Check what changed with `git diff HEAD` 2. **Group Files**: Put related files together 3. **Create Messages**: Write semantic commit messages for each group 4. **Commit Step by Step**: Commit each group after you approve

When to Split Changes

What Makes a Change "Large"

We split when we see:

1. **Many Files**: 5+ files changed 2. **Many Lines**: 100+ lines changed 3. **Multiple Features**: Changes in 2+ areas 4. **Mixed Types**: feat + fix + docs together

# Analyze change scale
CHANGED_FILES=$(git diff HEAD --name-only | wc -l)
CHANGED_LINES=$(git diff HEAD --stat | tail -1 | grep -o '[0-9]\+ insertions\|[0-9]\+ deletions' | awk '{sum+=$1} END {print sum}')

if [ $CHANGED_FILES -ge 5 ] || [ $CHANGED_LINES -ge 100 ]; then
  echo "Large change detected: splitting recommended"
fi

How to Split into Small, Meaningful Commits

1. Splitting by Functional Boundaries

# Identify functional units from directory structure
git diff HEAD --name-only | cut -d'/' -f1-2 | sort | uniq
# → src/auth, src/api, components/ui, etc.

2. Separation by Change Type

# New files vs existing file modifications
git diff HEAD --name-status | grep '^A' # New files
git diff HEAD --name-status | grep '^M' # Modified files
git diff HEAD --name-status | grep '^D' # Deleted files

3. Dependency Analysis

# Detect import relationship changes
git diff HEAD | grep -E '^[+-].*import|^[+-].*require' | \
cut -d' ' -f2- | sort | uniq

Detailed File Analysis

# Get list of changed files
git diff HEAD --name-only

# Analyze each file's changes individually
git diff HEAD -- <file>

# Determine change type for files
git diff HEAD --name-status | while read status file; do
  case $status in
    A) echo "$file: New creation" ;;
    M) echo "$file: Modification" ;;
    D) echo "$file: Deletion" ;;
    R*) echo "$file: Renamed" ;;
  esac
done

How to Group Files

1. **By Feature**: Keep related functions together

• `src/auth/` files → Authentication
• `components/` files → UI components

2. **By Type**: Same kind of changes

• Only tests → `test:`
• Only docs → `docs:`
• Only config → `chore:`

3. **By Dependencies**: Files that need each other

• Model + Migration
• Component + Style

4. **By Size**: Keep commits manageable

• Max 10 files per commit
• Keep related files together

Output Example

$ /semantic-commit

Analyzing changes...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Detected changes:
• src/auth/login.ts (modified)
• src/auth/register.ts (new)
• src/auth/types.ts (modified)
• tests/auth.test.ts (new)
• docs/authentication.md (new)

Proposed commit splits:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Commit 1/3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Message: feat: implement user registration and login system
Included files:
  • src/auth/login.ts
  • src/auth/register.ts
  • src/auth/types.ts

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Commit 2/3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Message: test: add comprehensive tests for authentication system
Included files:
  • tests/auth.test.ts

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Commit 3/3
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Message: docs: add authentication system documentation
Included files:
  • docs/authentication.md

Execute commit with this split plan? (y/n/edit):

Your Options

• `y`: Go with the proposed split
• `n`: Cancel everything
• `edit`: Change commit messages
• `merge <number1> <number2>`: Combine commits
• `split <number>`: Break up a commit more

Dry Run Mode

$ /semantic-commit --dry-run

Analyzing changes... (DRY RUN)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[Commit split proposal display]

ℹ️  DRY RUN mode: No actual commits will be executed
💡 To execute, run again without --dry-run option

Smart Features

1. Understands Your Project

• Detects project type from config files
• Figures out features from folder structure

2. Change Pattern Recognition

# Detect bug fix patterns
- Keywords like "fix", "bug", "error"
- Addition of exception handling
- Condition branch fixes

# Detect new feature patterns
- New file creation
- New method additions
- API endpoint additions

3. Dependency Analysis

• Changes to import statements
• Addition/modification of type definitions
• Relationship with configuration files

How It's Built

Step-by-Step Commits with Git

1. Preprocessing: Save Current State

# Reset unstaged changes if any
git reset HEAD
git status --porcelain > /tmp/original_state.txt

# Check working branch
CURRENT_BRANCH=$(git branch --show-current)
echo "Working branch: $CURRENT_BRANCH"

2. Sequential Commit Execution by Group

# Read split plan
while IFS= read -r commit_plan; do
  group_num=$(echo "$commit_plan" | cut -d':' -f1)
  files=$(echo "$commit_plan" | cut -d':' -f2- | tr ' ' '\n')

  echo "=== Executing commit $group_num ==="

  # Stage only relevant files
  echo "$files" | while read file; do
    if [ -f "$file"