Claude Command: Commit (Git-only)

This command works without any package manager/build tools, using only Git to:

• Read changes (staged/unstaged)
• Determine if changes should be split into multiple commits
• Generate Conventional Commits style messages with optional emoji for each commit
• Execute git add and git commit as needed (runs local Git hooks by default; use --no-verify to skip)

---

Usage

/git-commit
/git-commit --no-verify
/git-commit --emoji
/git-commit --all --signoff
/git-commit --amend
/git-commit --scope ui --type feat --emoji

Options

• --no-verify: Skip local Git hooks (pre-commit/commit-msg etc.).
• --all: When staging area is empty, automatically git add -A to include all changes in the commit.
• --amend: Amend the last commit without creating a new one (preserves author and timestamp unless local Git config specifies otherwise).
• --signoff: Add Signed-off-by line (use when following DCO process).
• --emoji: Include emoji prefix in commit message (omit for plain text).
• --scope <scope>: Specify commit scope (e.g., ui, docs, api), written to message header.
• --type <type>: Force commit type (e.g., feat, fix, docs), overrides automatic detection.

Note: If the framework doesn't support interactive confirmation, enable confirm: true in front-matter to avoid mistakes.

---

What This Command Does

1. Repository/Branch Validation

   • Check if in a Git repository using git rev-parse --is-inside-work-tree.
   • Read current branch/HEAD status; if in rebase/merge conflict state, prompt to resolve conflicts first.

2. Change Detection

   • Get staged and unstaged changes using git status --porcelain and git diff.
   • If staged files = 0:
     • If --all is passed → Execute git add -A.
     • Otherwise prompt choice: continue analyzing unstaged changes for suggestions, or cancel to manually group staging.

3. Split Suggestions (Split Heuristics)

   • Cluster by concerns, file modes, change types (e.g., source code vs docs/tests; different directories/packages; additions vs deletions).
   • If multiple independent changesets or large diff detected (e.g., > 300 lines / across multiple top-level directories), suggest splitting commits with pathspecs for each group (for subsequent git add <paths>).

4. Commit Message Generation (Conventional with Optional Emoji)

   • Auto-infer type (feat/fix/docs/refactor/test/chore/perf/style/ci/revert...) and optional scope.
   • Generate message header: [<emoji>] <type>(<scope>)?: <subject> (first line ≤ 72 chars, imperative mood, emoji included only with --emoji flag).
   • Generate message body:
     • Must have a blank line after the subject.
     • Use list format, each item starts with -.
     • Each item must use imperative verb-first sentences (e.g., "add…", "fix…", "update…").
     • Colon-separated formats are prohibited (e.g., "Feature: description", "Impl: content").
     • Describe the motivation, implementation details, or impact scope (3 items or fewer recommended).
   • Generate message footer (if any):
     • Must have a blank line after the Body.
     • BREAKING CHANGE: If there are breaking changes, must include BREAKING CHANGE: <description>, or add exclamation mark after type (e.g., feat!:).
     • Other footers use git trailer format (e.g., Closes #123, Refs: #456, Reviewed-by: Name).
   • Select message language to match the predominant language in Git history. Inspect recent commit subjects (e.g., git log -n 50 --pretty=%s) to decide Chinese vs English; if unclear, fall back to the repository's primary locale or English.
   • Write draft to .git/COMMIT_EDITMSG for use with git commit.

5. Execute Commit

   • Single commit scenario: git commit [-S] [--no-verify] [-s] -F .git/COMMIT_EDITMSG
   • Multiple commit scenario (if split accepted): Provide clear instructions for git add <paths> && git commit ... per group; execute sequentially if allowed.

6. Safe Rollback

   • If mistakenly staged, use git restore --staged <paths> to unstage (command provides instructions, doesn't modify file contents).

---

Best Practices for Commits

• Atomic commits: One commit does one thing, easier to trace and review.
• Group before committing: Split by directory/module/feature.
• Clear subject: First line ≤ 72 chars, imperative mood.
• Body with context: Explain motivation, solution, and impact scope (colon-separated formats prohibited).
• Follow Conventional Commits: <type>(<scope>): <subject>.

---

Type to Emoji Mapping (When --emoji is Used)

• ✨ feat: New feature
• 🐛 fix: Bug fix (includes 🔥 remove code/files, 🚑️ hotfix, 👽️ adapt to external API changes, 🔒️ security fix, 🚨 fix warnings, 💚 fix CI)
• 📝 docs: Documentation and comments
• 🎨 style: Code style/formatting (no semantic changes)
• ♻️ refactor: Refactoring (no new features, no bug fixes)
• ⚡️ perf: Performance improvements
• ✅ test: Add/fix tests, snapshots
• 🔧 chore: Build/tools/misc tasks (merge branches, update configs, release tags, pin dependencies, .gitignore, etc.)
• 👷 ci: CI/CD configuration and scripts
• ⏪️ revert: Revert commits
• 💥 feat: Breaking changes (explained in BREAKING CHANGE: section)

If --type/--scope is passed, it will override auto-detection. Emoji is only included when --emoji flag is specified.

---

Guidelines for Splitting Commits

1. Different concerns: Unrelated feature/module changes should be split.
2. Different types: Don't mix feat, fix, refactor in the same commit.
3. File modes: Source code vs docs/tests/configs should be grouped separately.
4. Size threshold: Large diffs (e.g., >300 lines or across multiple top-level directories) should be split.
5. Revertability: Ensure each commit can be independently reverted.

---

Examples

Good (with --emoji)

- ✨ feat(ui): add user authentication flow
- 🐛 fix(api): handle token refresh race condition
- 📝 docs: update API usage examples
- ♻️ refactor(core): extract retry logic into helper
- ✅ test: add unit tests for rate limiter
- 🔧 chore: update git hooks and repository settings
- ⏪️ revert: revert "feat(core): introduce streaming API"

Good (without --emoji)

- feat(ui): add user authentication flow
- fix(api): handle token refresh race condition
- docs: update API usage examples
- refactor(core): extract retry logic into helper
- test: add unit tests for rate limiter
- chore: update git hooks and repository settings
- revert: revert "feat(core): introduce streaming API"

Good (with Body)

feat(auth): add OAuth2 login flow

- implement Google and GitHub third-party login
- add user authorization callback handling
- improve login state persistence logic

Closes #42

fix(ui): fix button spacing on mobile devices

- adjust button padding to fit small screens
- fix styling issues on iOS Safari
- optimize touch target size

Good (with BREAKING CHANGE)

feat(api)!: redesign authentication API

- migrate from session-based to JWT authentication
- update all endpoint signatures
- remove deprecated login methods

BREAKING CHANGE: authentication API has been completely redesigned, all clients must update their integration

Split Example

- `feat(types): add new type defs for payment method`
- `docs: update API docs for new types`
- `test: add unit tests for payment types`
- `fix: address linter warnings in new files` ← (if your repo has hook errors)

---

Important Notes

• Git only: No package manager/build commands (pnpm/npm/yarn etc.).
• Respects hooks: Executes local Git hooks by default; use --no-verify to skip.
• No source code changes: Command only reads/writes .git/COMMIT_EDITMSG and staging area; doesn't directly edit working directory files.
• Safety prompts: In rebase/merge conflicts, detached HEAD states, prompts to handle/confirm before continuing.
• Auditable and controllable: If confirm: true is enabled, each actual git add/git commit step requires confirmation.