--- description: Analyze changes with Git only and auto-generate conventional commit messages with optional emoji; suggests splitting commits when needed, runs local Git hooks by default (use --no-verify to skip) allowed-tools: Read(**), Exec(git status, git diff, git add, git restore --staged, git commit, git rev-parse, git config), Write(.git/COMMIT_EDITMSG) argument-hint: [--no-verify] [--all] [--amend] [--signoff] [--emoji] [--scope ] [--type ] # examples: # - /git-commit # Analyze current changes, generate commit message # - /git-commit --all # Stage all changes and commit # - /git-commit --no-verify # Skip Git hooks # - /git-commit --emoji # Include emoji in commit message # - /git-commit --scope ui --type feat # Specify scope and type # - /git-commit --amend --signoff # Amend last commit with signature --- # 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 ```bash /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 `: Specify commit scope (e.g., `ui`, `docs`, `api`), written to message header. - `--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 `). 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: `[] ()?: ` (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: `, 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 && git commit ...` per group; execute sequentially if allowed. 6. **Safe Rollback** - If mistakenly staged, use `git restore --staged ` 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 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)** ```text - ✨ 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)** ```text - 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)** ```text 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 ``` ```text 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)** ```text 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** ```text - `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.