Commit Staged Files with Conventional Commits

You are helping the user commit their currently staged (indexed) git files using the Conventional Commits specification and commit message best practices.

Pre-flight Checks

Before crafting a commit message, always:

1. Run git status to see what files are staged
2. Run git diff --cached to review the actual staged changes
3. If nothing is staged, inform the user and stop — do not create an empty commit

Conventional Commit Format

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

Types

Note: Comment-only changes (adding, updating, or removing code comments) should use style or chore — never feat or fix. Keep commit messages concise; do not describe individual comments.

Scope

• Optional, but recommended when the change targets a specific module, component, or area
• Use lowercase, kebab-case: feat(auth):, fix(api-client):
• Keep consistent with the project's existing scope conventions
• Check recent git log (git log --oneline -50 or more) for scope patterns already used in the project
• Also note whether the project actually uses conventional commits — if not, adapt to the project's style

Subject Line Rules

• Imperative mood: "add feature" not "added feature" or "adds feature"
• Lowercase first letter: "add feature" not "Add feature"
• No period at the end
• 50 characters or less — hard limit at 72
• Complete the sentence: "If applied, this commit will <subject>"

Body Rules

• Separate from subject with a blank line
• Wrap at 72 characters
• Explain what and why, not how (the diff shows how)
• Use when the subject alone is not sufficient to understand the change
• Use bullet points for multiple related changes

Footer Rules

• BREAKING CHANGE: <description> for breaking changes (triggers major version bump)
• Refs: #123 or Closes #456 for issue references
• Co-authored-by: Name <email> for co-authors
• Signed-off-by: Name <email> when the project requires a Developer Certificate of Origin (DCO)

Decision Process

Follow this process to determine the commit message:

Step 1: Analyze the Staged Changes

Read the diff carefully and identify:

• What files changed and their purpose
• Whether this is a single logical change or multiple unrelated changes
• The primary intent: new feature, bug fix, refactor, etc.

Step 2: Check for Multiple Logical Changes

If the staged changes contain multiple unrelated changes:

• Inform the user: "The staged changes contain multiple unrelated changes. Consider splitting them into separate commits for a cleaner history."
• Classify changes into categories to suggest logical groupings:
  • Tidying — formatting, renaming, dead code removal (no behavior change)
  • Infrastructure/build — dependencies, tooling, configuration
  • Feature implementation — new capabilities
  • Bug fixes — correcting incorrect behavior
  • Documentation — docs-only changes
• Keep dependency manifests with their lock files (e.g., package.json + package-lock.json, go.mod + go.sum, Cargo.toml + Cargo.lock, pyproject.toml + lock files)
• Suggest a commit order that tells a clear story:
  1. Tidying/structural changes first (separate from behavior changes)
  2. Documentation before related code changes
  3. Infrastructure/build before features that depend on them
  4. Feature or fix commits last
• Let the user decide whether to proceed with a single commit or split

Step 3: Determine the Type

• Ask yourself: "What is the primary intent of this change?"
• If a feature includes tests, the type is feat (not test)
• If a bug fix includes a refactor, the type is fix (not refactor)
• The type reflects the reason for the change, not every file touched

Step 4: Determine the Scope

• Look at what area of the codebase is affected
• Check git log --oneline -50 for existing scope conventions
• If the change touches multiple areas, either omit the scope or use the primary area

Step 5: Write the Subject

• Describe the change concisely in imperative mood
• Focus on the user-facing or developer-facing impact
• Bad: fix(api): fixed the bug in the login endpoint
• Good: fix(api): return 401 on expired token instead of 500

Step 6: Write the Body (if needed)

Add a body when:

• The subject does not fully explain the change
• There is important context (why this approach, what was considered)
• The change has side effects or non-obvious consequences
• There is a breaking change to document

Step 7: Present and Confirm

• Present the complete commit message to the user
• Wait for approval before executing the commit
• If the user wants changes, adjust accordingly

Commit Execution

When executing the commit:

• Use git commit -m with a HEREDOC for multi-line messages
• Never use --no-verify — respect pre-commit hooks
• Never use --amend unless the user explicitly requests it
• If a pre-commit hook fails, investigate and fix the issue, then create a new commit
• After committing, run git status to confirm success

Single-line Commit

git commit -m "feat(auth): add JWT token refresh endpoint"

Multi-line Commit

git commit -m "$(cat <<'EOF'
feat(auth): add JWT token refresh endpoint

Implement automatic token refresh when the access token expires.
The refresh endpoint validates the refresh token and issues a new
access token with a 15-minute expiry.

Closes #234
EOF
)"

Examples

Simple Feature

feat: add dark mode toggle to settings page

Bug Fix with Context

fix(parser): handle empty input without panic

The YAML parser panicked on empty strings because it attempted
to access the first character without a length check. Now returns
an empty document instead.

Closes #89

Breaking Change

feat(api)!: require authentication for all endpoints

All API endpoints now require a valid Bearer token. Previously,
read-only endpoints were publicly accessible.

BREAKING CHANGE: unauthenticated requests to /api/* now return 401.
Clients must include an Authorization header with a valid token.

Refs: #156

Documentation Update

docs: add API rate limiting guide

Refactor

refactor(db): extract connection pooling into dedicated module

Move connection pool logic from the monolithic database module into
its own module to improve testability and separation of concerns.
No behavior change.

Anti-patterns to Avoid

Important Guidelines

• Always review the diff before writing the commit message — do not guess
• Never commit secrets (.env, API keys, credentials) — warn the user if staged
• Respect the project's conventions — check recent history for patterns
• One logical change per commit — suggest splitting when appropriate
• Ask before committing — always present the message for approval first