---

created: 2026-01-21 modified: 2026-05-30 reviewed: 2026-04-25 name: git-commit description: Create commits with conventional messages and issue references. Use when user says "commit", "save changes", or "stage and commit". Local commits only — see git-push for remote. user-invocable: false allowed-tools: Bash(git status *), Bash(git diff *), Bash(git log *), Bash(git add *), Bash(git commit *), Bash(git restore *), Bash(pre-commit *), Bash(gh issue *), Read, Grep, Glob, TodoWrite

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

# 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):

git add src/feature.ts
git add tests/feature.test.ts
git status --porcelain              # Verify

Modified tracked files:

git add -u                          # Stage all modified tracked files

3. Run Pre-commit Hooks

If .pre-commit-config.yaml exists:

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):

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.

git commit -m "$(cat <<'EOF'
type(scope): concise description

Optional body explaining the change.

Fixes #123
Refs #456

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
EOF
)"

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 logand 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 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:

# 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)