Analyze changes, group them into coherent atomic commits, and create signed commits following repository conventions. This command transforms a messy working directory into a clean, logical commit history.

Grouping Principles

Principle	Description
Feature + Tests	Implementation and its tests go together
Config Changes	package.json, tsconfig, etc. grouped separately
Documentation	README, docs/ changes grouped together
Refactoring	Pure refactors (no behavior change) separate
Bug Fixes	Each fix is atomic with its test

Process Overview

Analyze - Run git status and git diff to understand all changes
Group - Cluster related changes into logical commits
Order - Determine optimal commit sequence (deps before features, etc.)
Confirm - Present grouping plan to user for approval
Execute - Create signed commits in sequence

Single vs Multiple Commits

Single commit when:

All changes are for one coherent feature/fix
User provides a specific message via argument
Changes are minimal and related

Multiple commits when:

Changes span different concerns (feature + docs + deps)
Mix of features, fixes, and chores
Better git history benefits future archaeology

User Confirmation

Before creating commits, present the plan:

Proposed Commit Plan:
─────────────────────
1. feat(auth): add OAuth2 refresh token support
   - src/auth/oauth.ts (modified)
   - src/auth/oauth.test.ts (modified)

2. chore(deps): update authentication dependencies
   - package.json (modified)
   - package-lock.json (modified)

3. docs: update OAuth2 setup guide
   - docs/auth/oauth-setup.md (modified)

Proceed with this plan? [Yes / Modify / Single commit]

MANDATORY RULES (NON-NEGOTIABLE)

These rules MUST be followed for EVERY commit:

ALWAYS USE conventional commits v1.0.0 to write the messages:
- you can find the reference into ../../docs/convetional-commits.md
Commit message body must be clean and professional:
- Only the actual commit description
- No metadata, signatures, hashtags, or internal references in the body

Commit Process

Step 1: Gather Context

Run these commands in parallel to understand the current state:

# Check staged and unstaged changes
git status

# View ALL changes (staged and unstaged)
git diff
git diff --cached

# View recent commits for style reference
git log --oneline -10

Step 2: Analyze and Group Changes

For each changed file, determine:

Type: feat, fix, chore, docs, refactor, test, style, perf, ci, build
Scope: Component or area affected (auth, api, ui, etc.)
Logical group: What other files belong with this change?

Grouping heuristics:

IMPORTANT NOTE: This example is only for illustration purposes. The actual grouping should be based on the actual changes and programming language standards.

File Pattern	Likely Group
`.test.ts`, `.spec.ts`	Group with implementation file
`package.json`, `*-lock.json`	Dependency changes
`.md`, `docs/`	Documentation
`.config.`, `tsconfig.*`	Configuration
Same directory/module	Often related

Create a mental (or actual) grouping:

Group 1 (feat): auth changes
  - src/auth/oauth.ts
  - src/auth/oauth.test.ts

Group 2 (chore): dependencies
  - package.json
  - package-lock.json

Group 3 (docs): documentation
  - README.md

Step 3: Determine Commit Order

Order matters for bisectability:

Dependencies first - So subsequent commits can use them
Core changes - Implementation before consumers
Tests with implementation - Keep them atomic
Documentation last - Documents the final state

Step 4: Present Plan and Confirm

MANDATORY: Get user confirmation before executing.

"I've analyzed your changes and propose this commit plan. How should I proceed?",
1. Execute plan
2. Single commit
3. Let me review it

If user selects "Let me review", show the full plan with files per commit.

Step 5: Execute Commits (Signed)

For each commit group, in order:

Stage only the files for this commit:

git add <file1> <file2> ...

Step 6: Verify Commits

After all commits, verify the result:

# Show all new commits
git log --oneline -<number_of_commits>

# Confirm clean state
git status

Important Notes

Smart grouping - Analyzes changes and proposes atomic commits for clean history
No visible markers - The message body stays clean and professional
Transparent - System tracing is documented, just not prominently displayed
Do not use --no-verify - Always run pre-commit hooks unless user explicitly requests
User confirmation - Always present commit plan before executing

When User Provides Message

If the user provides a commit message as argument:

Single commit mode - Skip grouping analysis, use provided message
Use their message as the subject/body
Ensure proper formatting (50 char subject, etc.)
Create signed commit with trailer

Step 7: Offer Push (Optional)

After successful commit, ask the user if they want to push:

Validate if the branch is already tracking a remote branch then:

git push

If branch has no upstream, use:

git push -u origin <current-branch>

smart-commits