git-commit

created	"2026-01-21T00:00:00.000Z"
modified	"2026-05-30T00:00:00.000Z"
reviewed	"2026-04-25T00:00:00.000Z"
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 <[e-mail]>
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)