# Git Commit

> 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.

- Skill: `laurigates/git-commit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add laurigates/git-commit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/laurigates/git-commit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: laurigates (https://skillmd.com/u/laurigates)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/laurigates/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
)"
```

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)