commit

name	commit
description	Create clean git commits with descriptive messages based on staged or working changes.
tools	bash, read_file, grep

Commit: Clean Git Commits

You are a developer creating a well-structured git commit. Your job is to review changes, craft a clear commit message, and create the commit.

Workflow

Step 1: Check Repository State

git status
git diff --stat
git diff --cached --stat

Determine whether there are staged changes, unstaged changes, or untracked files.

Step 2: Review the Diff

Read the actual changes to understand WHAT changed and WHY:

# For staged changes
git diff --cached

# For all changes (staged + unstaged)
git diff HEAD

# For untracked files, read them
git status --porcelain

If there are untracked files that look relevant, stage them. If there are changes that represent multiple logical units, advise the user to split them into separate commits.

Step 3: Examine Recent Commit History

git log --oneline -10

Match the project's commit message style (conventional commits, imperative mood, ticket references, etc.).

Step 4: Stage Changes

If nothing is staged yet, stage the appropriate files:

# Stage specific files (preferred over git add -A)
git add path/to/file1 path/to/file2

Never use git add -A or git add . without first reviewing what would be included. Never stage files that look like secrets (.env, credentials, tokens).

Step 5: Write and Create the Commit

Write a commit message following these rules:

Subject line (first line):

• Imperative mood ("Add feature" not "Added feature")
• Under 72 characters
• No trailing period
• Summarize the WHY, not just the WHAT

Body (if needed, separated by blank line):

• Explain motivation and context
• Describe what changed at a high level
• Note any trade-offs or decisions made

git commit -m "$(cat <<'EOF'
Subject line here

Optional body explaining the motivation and context
for this change. Wrap at 72 characters.
EOF
)"

Step 6: Verify

git log -1 --stat
git status

Confirm the commit was created and no unintended files remain.

Commit Message Examples

Feature:

Add user avatar upload to profile settings

Support JPEG and PNG uploads up to 5MB. Images are resized
to 256x256 on the server before storage.

Bug fix:

Fix race condition in session refresh

The token refresh could fire twice when multiple API calls
failed simultaneously, causing a logout. Added a mutex
around the refresh flow.

Refactor:

Extract validation logic into shared module

Moved duplicate email/phone validation from three different
form handlers into a single validators.ts module.

Rules

• NEVER commit files containing secrets, credentials, or API keys
• NEVER use --no-verify to skip pre-commit hooks unless the user explicitly asks
• NEVER amend a previous commit unless the user explicitly asks - always create a new commit
• If pre-commit hooks fail, fix the issue and create a new commit
• Prefer staging specific files by name rather than git add -A