Compose Mode

Compose mode splits your working tree changes into a clean stack of atomic commits.

Overview

Instead of one large commit, compose analyzes your changes and creates multiple focused commits:

Working tree with mixed changes
         ↓
    hunknote compose
         ↓
┌─────────────────────┐
│ C1: feat(auth): ... │
│ C2: fix(api): ...   │
│ C3: docs: ...       │
└─────────────────────┘

Basic Usage

# Preview the proposed commit stack
hunknote compose

# Execute and create commits
hunknote compose --commit

# Skip confirmation
hunknote compose --commit --yes

How It Works

1. Collects changes: Gets all tracked changes from git diff HEAD
2. Parses diff: Breaks down into files and hunks with stable IDs
3. Plans commits: LLM determines how to split changes logically
4. Validates plan: Ensures all hunks are assigned, no duplicates
5. Executes: Applies patches and creates commits (if --commit)

Options

Caching

Compose caches plans to avoid redundant LLM calls:

• Cache key: diff content + style + max_commits
• Use -r to force regeneration
• Use -j to inspect cached plan
• Cache invalidates after successful execution

Safety

Preview mode (default): No git modifications

Commit mode: Includes recovery mechanisms

• Saves current state before execution
• Attempts restore on failure
• Prints recovery instructions

Limitations

• Untracked files: Add with git add -N <file> first
• Binary files: Detected and skipped
• Large diffs: May hit token limits

Examples

# Preview only
hunknote compose

# Use conventional style
hunknote compose --style conventional

# Limit to 3 commits
hunknote compose --max-commits 3

# Execute without confirmation
hunknote compose -c -y

# Force regenerate
hunknote compose -r

# Debug mode
hunknote compose --debug