git-commit

# Git Commit ## When to Use This Skill | Use this skill when... | Use the alternative when... | |---|---| | Creating a local commit with conventional message and pre-commit hooks | Use `git-push` afterwards to send the commit to remote | | Auto-detecting related GitHub issues and inserting `Fixes #N` references | Use `github-issue-autodetect` to study the detection patterns themselves | | Staging and committing without pushing or opening a PR | Use `git-commit-push-pr` to chain commit + push + PR creation in one step | | Applying repo conventions (humble tone, logical grouping) to a single commit | Use `git-commit-workflow` for the broader staging + message convention guidance | Create local commits with proper conventional messages and issue references. ## When to Use **Trigger phrases:** - "commit" / "commit locally" / "commit these changes" - "save changes" / "save my work" - "stage and commit" - "create a commit" **Context signals:** - User has made code changes - `git status` shows modified/untracked files - No mention of "push", "remote", or "PR" ## Workflow ### 1. Assess State ```bash # Check branch and status git branch --show-current git status --porcelain=v2 --branch # View changes git diff --stat # Unstaged git diff --cached --stat # Already staged ``` ### 2. Stage Changes **Explicit staging** (preferred): ```bash git add src/feature.ts git add tests/feature.test.ts git status --porcelain # Verify ``` **Modified tracked files**: ```bash git add -u # Stage all modified tracked files ``` ### 3. Run Pre-commit Hooks If `.pre-commit-config.yaml` exists: ```bash pre-commit run --all-files # If hooks modify files (formatters), re-stage: git add -u pre-commit run --all-files # Should pass now ``` ### 4. Detect Related Issues Scan open issues for matches (see **github-issue-autodetect** skill): ```bash gh issue list --state open --json number,title,labels --limit 30 ``` **Match staged changes to issues** by: - File paths mentioned in issue body (high confidence) - Error messages or function names (high confidence) - Directory/component matches (medium confidence) ### 5. Create Commit **IMPORTANT:** Use HEREDOC directly in the git commit command. ```bash git commit -m "$(cat <<'EOF' type(scope): concise description Optional body explaining the change. Fixes #123 Refs #456 Co-Authored-By: Claude <model name> <noreply@anthropic.com> EOF )" ``` **The scope is required.** Write `type(scope): …` — `docs(readme): update install steps`, never a bare `docs: update install steps`. The Conventional Commits spec lets you omit the scope; this house convention does not (`.claude/rules/conventional-commits.md`). Take it from the component or plugin the change touches. Use the exact `Co-Authored-By` line the harness provides for the current session — do not copy a model name from this example. **Inside a quoted heredoc (`<<'EOF'`), backticks, `$`, and `\` are already literal — never backslash-escape them.** A reflexive `\`` produces a literal backslash in the commit message that survives into `git log` and needs an `--amend` to clean up. For trailer conventions (Co-authored-by, Signed-off-by, BREAKING CHANGE, Release-As), see **git-commit-trailers** skill. ### Conventional Commit Types | Type | Use Case | Version Bump | |------|----------|--------------| | `feat` | New feature | Minor | | `fix` | Bug fix | Patch | | `perf` | Performance improvement | Patch | | `refactor` | Code restructuring | None | | `docs` | Documentation | None | | `test` | Adding tests | None | | `chore` | Maintenance, deps | None | | `ci` | CI/CD config | None | | `build` | Build system, deps | None | See [Conventional Commits Standards](../../.claude/rules/conventional-commits.md) for complete reference. ### Issue References | Keyword | Effect | |---------|--------| | `Fixes #N` | Closes issue on merge (bug fixes) | | `Closes #N` | Closes issue on merge (features) | | `Refs #N` | Links without closing (partial work) | ## Output On success, report: ``` Created commit: abc1234 Message: feat(auth): add OAuth2 support Fixes #123 Refs #456 Ready for: push to remote, create PR, or continue working ``` ## Composability This skill creates **local commits only**. For remote operations: - **git-push** skill: Push commits to remote - **git-pr** skill: Create pull request Common compositions: - "commit" → git-commit only - "commit and push" → git-commit → git-push - "commit and create PR" → git-commit → git-push → git-pr **Before building further on an existing PR branch** (an additional in-session request continuing earlier work), invoke `/git:pr-sync-check` first. If the verdict is anything other than `in_sync` / `no_pr` / `no_remote` — e.g. `pr_merged` or `behind` — stop and reconcile (branch off the updated default, or `git pull --rebase`) before committing. See `.claude/rules/pr-branch-sync.md`. ## Error Handling **No changes to commit:** ``` Nothing to commit. Working tree clean. ``` **Pre-commit hook fails:** ```bash # Fix the issue, then: git add -u pre-commit run --all-files # Then commit ``` **Merge conflict markers:** ``` Cannot commit: unresolved merge conflicts in <file> ``` ## Best Practices 1. **One logical change per commit** - Easier to review and revert 2. **Always reference issues** - Maintains traceability 3. **Run pre-commit before staging** - Avoids re-staging formatter changes 4. **Keep subject under 72 chars** - Better display in git log 5. **Use imperative mood** - "Add feature" not "Added feature" 6. **Add appropriate trailers** - Co-authored-by for pair/AI work, Signed-off-by for DCO projects, BREAKING CHANGE for major versions (see git-commit-trailers)