Generate Conventional Commit Messages

Generate a commit message in conventional commits format based on staged changes (git diff --staged).

Show the commit message only — never perform git operations like git commit.

Keep in mind that the commit message will appear in release notes, so it should be clear and concise.

Pre-check

Before inspecting staged changes, always run git log --oneline -5 first. The user may have already committed (e.g., via pre-commit hooks or manually). If the latest commit already covers the current work, generate a message for git diff --staged only if there are additional staged changes.

Type Selection

Choose the type based on what was changed and why. Decide by the class of artifact and whether shipped-program runtime behavior changed — never by how much a user could be inconvenienced.

1. First, identify the nature of the change:

   • Documentation only → docs
   • Build/CI configuration → ci or build
   • Code style/formatting → style
   • Tests only → test
   • Chores (deps, cleanup) → chore
   • Code restructuring without behavior change → refactor

   Stop-gate: if the diff touches ONLY non-code artifacts (docs, build/CI config, tooling scripts, comments, metadata, reference strings like URLs or repo names), the type is settled here — do NOT proceed to step 2. A change to such artifacts is never feat/fix even if it is "wrong/broken" or would inconvenience a user, because the program's runtime behavior does not change. For a mixed non-code diff (e.g. docs + tooling + comments) use chore.

2. For changes to shipped-program runtime behavior, ask: "Did this functionality exist before?"

   • No, this is genuinely new → feat
   • Yes, but it was wrong/broken/non-compliant → fix

Common mistakes to avoid:

• BREAKING CHANGE does not imply feat — a spec-compliance fix can be fix!
• Large code changes do not imply feat — size is irrelevant
• API signature changes do not imply feat — if correcting a mistake, use fix
• User-facing inconvenience does not imply fix — a stale install URL in the README or a broken link in a comment is docs/chore; fix requires the program's own behavior to have been wrong

Line Length

• Title: Keep concise — no strict character limit, but shorter is better
• Body: Wrap at 72 characters per line for readability in git log

Atomic Commits

Split staged changes into separate commits by logical unit. Each commit should be independently reviewable and contain one cohesive change.

When the diff contains multiple logical changes, suggest multiple commit messages with explicit git add instructions for selective staging.

Exclusions

Do NOT include:

• Phase/step numbers (e.g., "Phase 1", "Step 2")
• Plan or task references (e.g., "As part of...", "Following the plan...")
• Internal implementation context

Before outputting, verify the message contains none of the above.

Clipboard

After generating the commit message(s), copy to the clipboard using pbcopy. When copying to the clipboard, do NOT insert a blank line between the title and body. The title and body should be separated by a single newline only (e.g., printf 'title\nbody' | pbcopy).

When there are multiple commits, run a separate printf ... | pbcopy for each commit message. Do NOT combine multiple messages into a single pbcopy call — the user will commit one at a time and needs the clipboard to contain only the current message.

The user-facing output should retain blank lines between title and body for readability.