---
name: commit-workflow
description: Guided git commit workflow. Use before committing changes — generates a clean commit message from the diff.
language: any
tags: git, commit, version-control
---
# Commit Workflow

When the user asks to commit changes, follow this workflow.

## Step 1: Inspect the changes

Run via `bash`:
- `git status` — see what's modified/staged/untracked
- `git diff HEAD` — full diff of staged and unstaged changes
- `git branch --show-current` — current branch
- `git log --oneline -10` — recent commits (to match style)

## Step 2: Analyze

Determine:
- What's the **single logical change** being committed?
- Are there multiple unrelated changes? If so, suggest splitting into multiple commits.
- What's the conventional commit type?
  - `feat:` new feature
  - `fix:` bug fix
  - `docs:` documentation only
  - `style:` formatting, no code change
  - `refactor:` code change that neither fixes a bug nor adds a feature
  - `perf:` code change that improves performance
  - `test:` adding tests
  - `chore:` build process, tooling, deps

## Step 3: Write the message

Format:
```
<type>(<optional scope>): <imperative subject under 72 chars>

<optional body explaining why, wrapped at 72 chars>

<optional footer like "Fixes #123">
```

Rules:
- Subject in imperative mood: "Add" not "Added" or "Adds"
- Subject lowercase, no period
- Body explains **why**, not what (the diff shows what)
- Reference issues in footer

## Step 4: Stage and commit

If specific files should be staged, run `git add <files>` explicitly. Otherwise `git add -A` is fine.

Commit with a heredoc to preserve formatting:
```bash
git commit -m "$(cat <<'EOF'
feat(auth): add OAuth2 login flow

Implements the login button, callback handler, and session
persistence using JWT in httpOnly cookies.

Fixes #142
EOF
)"
```

## Step 5: Verify

- `git log -1 --stat` to confirm the commit looks right
- `git status` to confirm clean working tree (or remaining unrelated changes)

## Anti-patterns

- ❌ `git commit -m "fix"` — too vague
- ❌ `git commit -m "Update file.py"` — describes what, not why
- ❌ Mixing unrelated changes in one commit
- ❌ Committing `node_modules/`, `.env`, build artifacts
- ❌ Using `--no-verify` to skip hooks without explanation