Git Commit

---
created: 2026-01-21
modified: 2026-09-23
reviewed: 2026-09-02
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

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