Git Commit Helper

Git Commit Helper

Quick start

Analyze staged changes and generate commit message:

# View staged changes
git diff --staged

# Generate commit message based on changes
# (Claude will analyze the diff and suggest a message)

Commit message format

Follow conventional commits format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, missing semicolons)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks

Examples

Feature commit:

feat(auth): add JWT authentication

Implement JWT-based authentication system with:
- Login endpoint with token generation
- Token validation middleware
- Refresh token support

Bug fix:

fix(api): handle null values in user profile

Prevent crashes when user profile fields are null.
Add null checks before accessing nested properties.

Refactor:

refactor(database): simplify query builder

Extract common query patterns into reusable functions.
Reduce code duplication in database layer.

Analyzing changes

Review what's being committed:

# Show files changed
git status

# Show detailed changes
git diff --staged

# Show statistics
git diff --staged --stat

# Show changes for specific file
git diff --staged path/to/file

Commit message guidelines

DO:

• Use imperative mood ("add feature" not "added feature")
• Keep first line under 50 characters
• Capitalize first letter
• No period at end of summary
• Explain WHY not just WHAT in body

DON'T:

• Use vague messages like "update" or "fix stuff"
• Include technical implementation details in summary
• Write paragraphs in summary line
• Use past tense

Multi-file commits

When committing multiple related changes:

refactor(core): restructure authentication module

- Move auth logic from controllers to service layer
- Extract validation into separate validators
- Update tests to use new structure
- Add integration tests for auth flow

Breaking change: Auth service now requires config object

Scope examples

Frontend:

• feat(ui): add loading spinner to dashboard
• fix(form): validate email format

Backend:

• feat(api): add user profile endpoint
• fix(db): resolve connection pool leak

Infrastructure:

• chore(ci): update Node version to 20
• feat(docker): add multi-stage build

Breaking changes

Indicate breaking changes clearly:

feat(api)!: restructure API response format

BREAKING CHANGE: All API responses now follow JSON:API spec

Previous format:
{ "data": {...}, "status": "ok" }

New format:
{ "data": {...}, "meta": {...} }

Migration guide: Update client code to handle new response structure

Template workflow

1. Review changes: git diff --staged 2. Identify type: Is it feat, fix, refactor, etc.? 3. Determine scope: What part of the codebase? 4. Write summary: Brief, imperative description 5. Add body: Explain why and what impact 6. Note breaking changes: If applicable

Interactive commit helper

Use git add -p for selective staging:

# Stage changes interactively
git add -p

# Review what's staged
git diff --staged

# Commit with message
git commit -m "type(scope): description"

Amending commits

Fix the last commit message:

# Amend commit message only
git commit --amend

# Amend and add more changes
git add forgotten-file.js
git commit --amend --no-edit

Reference Files

• `references/GIT_COMMIT.template.md` - Conventional commits format template with types, scopes, and examples

Best practices

1. Atomic commits - One logical change per commit 2. Test before commit - Ensure code works 3. Reference issues - Include issue numbers if applicable 4. Keep it focused - Don't mix unrelated changes 5. Write for humans - Future you will read this

Commit message checklist

• [ ] Type is appropriate (feat/fix/docs/etc.)
• [ ] Scope is specific and clear
• [ ] Summary is under 50 characters
• [ ] Summary uses imperative mood
• [ ] Body explains WHY not just WHAT
• [ ] Breaking changes are clearly marked
• [ ] Related issue numbers are included

Git Commit Message Template

Follow Conventional Commits specification for consistent, machine-readable commit history.

Commit Message Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Examples

Simple Feature

feat: add user authentication endpoint

Feature with Scope

feat(auth): add OAuth2 login support

Bug Fix with Issue Reference

fix: resolve null pointer in user service

The getUser method was not handling missing records properly.

Closes #123

Breaking Change (Footer)

feat: update API response format

BREAKING CHANGE: response now returns data in `items` array instead of `results`

Breaking Change (Type Prefix)

feat!: drop support for Node 14

Multi-paragraph Body

fix(parser): handle edge cases in date parsing

Previously the parser would fail silently on malformed dates.
Now it throws a descriptive error with the invalid input.

This change affects all date fields in the API response.

Reviewed-by: Jane Doe
Refs: #456

Footer Tokens

Claude Code Attribution

When Claude generates the commit:

feat(api): implement rate limiting

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Rules

1. Type is REQUIRED and lowercase 2. Scope is OPTIONAL, noun in parentheses 3. Description is REQUIRED, imperative mood ("add" not "added") 4. Body is OPTIONAL, separated by blank line 5. Footer is OPTIONAL, separated by blank line 6. Breaking changes MUST be indicated with ! or BREAKING CHANGE: footer 7. Maximum 72 characters for subject line 8. Use present tense ("add feature" not "added feature")

Quality Checklist

• [ ] Type matches the change category
• [ ] Description is concise and imperative
• [ ] Subject line under 72 characters
• [ ] Body explains WHY, not just WHAT
• [ ] Breaking changes clearly indicated
• [ ] Issue references included if applicable