Git Commit Standards

Git Commit Standards

1. Context & Scope

This skill defines the team's git commit and pull request standards, ensuring consistent history and easy rollback/debugging.

Trigger Conditions:

• When user asks to "commit changes"
• When user asks to "create a pull request"
• Before running git commit or gh pr create

Environment:

• Git: 2.30+
• GitHub CLI (optional): 2.20+
• Pre-commit hooks: Enabled (validates format)

Out of Scope:

• Branching strategy (see git-workflow skill)
• Code review guidelines (see code-review-process skill)

2. Negative Knowledge (Read First)

Common mistakes that have caused problems in the past.

Failed Attempts Table

Common Pitfalls

• ❌ Don't: Write vague messages like "updates", "fixes", "changes"

  • Why it fails: 6 months later, impossible to understand intent
  • ✅ Do instead: "fix(auth): prevent token expiry race condition"

• ❌ Don't: Commit WIP code directly to main branch

  • Why it fails: Breaks CI/CD, blocks other developers
  • ✅ Do instead: Use feature branches, squash before merge

• ❌ Don't: Include passwords, API keys, or secrets in commits

  • Why it fails: Git history is permanent, secrets are exposed forever
  • ✅ Do instead: Use .env files (gitignored), run scripts/check_secrets.sh pre-commit

3. Verified Procedure

IMPORTANT: This skill is a "Tool Wrapper" - DO NOT analyze commit message format yourself. Use the deterministic validation script for accuracy and speed.

Prerequisites Check

# Run automated pre-commit validator
python scripts/validate_commit_msg.py --check-setup

# Expected output: "✅ Git hooks installed, conventional commit format enabled"

Step 1: Stage Changes Atomically

Description: Group related changes together, exclude unrelated changes

# Review what changed
git status
git diff

# Stage specific files (atomic changes)
git add path/to/changed/file.py

# OR stage interactively (parts of files)
git add -p path/to/file.py
# Press 'y' to stage hunks that belong together
# Press 'n' to skip unrelated changes

Validation:

# Verify only intended changes are staged
git diff --cached

# Expected: Only logically related changes visible

Step 2: Write Conventional Commit Message

Description: Format message according to team standards

Format:

<type>(<scope>): <subject>

<body>

<footer>

Types (choose one):

• feat: New feature for the user
• fix: Bug fix for the user
• docs: Documentation changes
• style: Code formatting (no logic change)
• refactor: Code restructuring (no behavior change)
• test: Adding or updating tests
• chore: Build process, dependencies, tooling

Example:

git commit -m "$(cat <<'EOF'
feat(api): add rate limiting to /users endpoint

Implements token bucket algorithm with 100 req/min limit.
Prevents abuse observed in incident #456.

Refs: #123
Breaking Change: Clients must handle 429 status codes
EOF
)"

Validation:

# DO NOT validate commit message text manually
# Use the deterministic script instead:
python scripts/validate_commit_msg.py HEAD

# Expected output: "✅ Commit message follows conventional format"
# If errors returned, fix them based ONLY on script output

Step 3: Verify Before Push

Description: Run final checks before pushing to remote

# Run tests (if applicable)
npm test  # or: pytest, cargo test, etc.

# Check commit message format
python scripts/validate_commit_msg.py HEAD

# Push to remote
git push -u origin <branch-name>

Success Criteria:

• Commit message follows conventional format
• Only one logical change per commit
• Tests pass locally
• No secrets or sensitive data included
• Issue number referenced (if applicable)

4. Configuration Reference

Conventional Commit Format

Regex Pattern:

^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,72}$

Scope Examples:

• api - Backend API changes
• ui - Frontend user interface
• db - Database schema/migrations
• auth - Authentication/authorization
• ci - CI/CD pipeline changes

Git Hooks Configuration

Create .git/hooks/commit-msg:

#!/bin/bash
# Validate commit message format
python scripts/validate_commit_msg.py "$1"
exit $?

Make executable:

chmod +x .git/hooks/commit-msg

5. Troubleshooting

Error Pattern Recognition

Diagnostic Commands

# Check recent commit history
git log --oneline -10

# See what would be committed
git diff --cached --stat

# Check for secrets (before committing)
python scripts/check_secrets.sh

# View commit message of last commit
git log -1 --pretty=%B

6. Reference Links

Internal Documentation:

• Full commit message examples: See examples/commit-messages.md
• Branching strategy: See .claude/skills/git-workflow/SKILL.md

External Resources:

• Conventional Commits Specification
• How to Write a Git Commit Message

7. Maintenance Log

8. Metrics & Success Indicators

How to measure if this skill is working:

• Consistency: 95%+ of commits follow conventional format (checked in CI)
• Traceability: Every commit links to an issue or requirement
• Revert Safety: Can revert individual features without side effects

When to update this skill:

• When a commit causes a problem (add to Negative Knowledge)
• When team adopts new commit type or scope
• When git version changes behavior