Quick Commit

Create well-structured conventional commits with automated staging, message formatting, and validation.

When to Use This Command

Run this command when you need to:

• Create a conventional commit with proper type, scope, subject, and body formatting
• Stage and commit related changes with automated message generation from diff analysis
• Validate commit messages against team conventions before finalizing the commit

Consider alternatives when:

• You need to amend or rewrite existing commit history (use interactive rebase instead)
• The commit involves complex merge conflict resolution that requires manual staging

Quick Start

Configuration

Copy
name: quick-commit
type: command
category: git-workflow

Example Invocation

Copy
claude command:run quick-commit --type feat --scope auth --message "Add OAuth2 login flow"

Example Output

Staged Changes Analysis:
  Modified: src/auth/oauth.ts (+142, -12)
  Modified: src/auth/middleware.ts (+28, -3)
  Added: src/auth/providers/google.ts (+87)
  Modified: tests/auth/oauth.test.ts (+45)

Commit Message:
  feat(auth): Add OAuth2 login flow

  Implement Google OAuth2 authentication provider with token
  refresh and session management. Add middleware for protecting
  routes that require authentication.

Validation:
  [OK] Type: feat (valid)
  [OK] Scope: auth (matches directory structure)
  [OK] Subject: 38 chars (limit: 70)
  [OK] Body: present and descriptive
  [OK] No secrets detected in staged files

Commit created: a4f8e2c feat(auth): Add OAuth2 login flow

Core Concepts

Conventional Commit Overview

Aspect	Details
Commit Types	feat, fix, ref, perf, docs, test, build, ci, chore, style
Scope	Optional module or area identifier matching project structure
Subject Line	Imperative mood, capitalized, no period, max 70 characters
Body	Explains what and why, not how; separated by blank line
Footer	Issue references (Fixes #123) and breaking change declarations

Commit Creation Workflow

  Changes Ready
       |
       v
  +-------------------+
  | Analyze Diff      |---> Categorize changes by type
  +-------------------+
       |
       v
  +-------------------+
  | Stage Files       |---> Add related files only
  +-------------------+
       |
       v
  +-------------------+
  | Format Message    |---> type(scope): subject + body
  +-------------------+
       |
       v
  +-------------------+
  | Validate Message  |---> Length, format, conventions
  +-------------------+
       |
       v
  +-------------------+
  | Security Scan     |---> Check for secrets in diff
  +-------------------+
       |
       v
  +-------------------+
  | Create Commit     |---> git commit with formatted msg
  +-------------------+

Configuration

Parameter	Type	Default	Description
type	string	auto-detect	Commit type: feat, fix, ref, perf, docs, test, build, ci, chore
scope	string	auto-detect	Module scope inferred from changed file paths
message	string	required	Commit subject line describing the change
body	string	auto-generate	Commit body with additional context (generated from diff if omitted)
issue	string	none	Issue reference to include in footer (e.g., #123, PROJ-456)

Best Practices

1. One Logical Change Per Commit - Each commit should represent a single, coherent change that can be independently reviewed and reverted. Mixing a feature addition with an unrelated refactor makes both harder to understand and review.

2. Write Imperative Subject Lines - Use "Add feature" not "Added feature" or "Adds feature". The imperative mood reads as a command that completes the sentence "If applied, this commit will [subject]."

3. Explain Why in the Body - The diff shows what changed. The commit body should explain why the change was necessary, what alternatives were considered, and any non-obvious implications of the change.

4. Reference Issues in the Footer - Link commits to issue trackers using Fixes #123 or Refs PROJ-456. This creates traceability from code changes back to requirements and bug reports.

5. Scan for Secrets Before Committing - Check staged files for API keys, passwords, tokens, and private keys. A secret committed even briefly to version control should be considered compromised and rotated.

Common Issues

1. Wrong Commit Type Selected - The auto-detected type does not match the intent of the change. Override the type explicitly when the diff analysis misclassifies a change (e.g., a bugfix detected as a refactor because no test files changed).

2. Subject Line Too Long - The commit subject exceeds 70 characters. Shorten the subject to a concise summary and move details into the commit body where there is no length restriction.

3. Staged Files Include Unrelated Changes - Multiple unrelated modifications were staged together. Use git add with specific file paths rather than git add -A to ensure only related changes are included in each commit.