gh-geoffjay-claude-plugins-plugins-utilities-git/commands/commit.md

name, description

name	description
git:commit	Git conventions and workflow guidelines using Conventional Commits

Git Conventions and Workflow Guidelines

Guide Claude Code through creating properly formatted commit messages and following git best practices using Conventional Commits specification.

Command

/git:commit [type] [scope] [description]

Arguments

• $1: type - feat|fix|docs|style|refactor|perf|test|chore|ci (optional, interactive if not provided)
• $2: scope - Component or module name (optional)
• $3: description - Brief description in imperative mood (optional)

Slash Command Usage Examples

Interactive Mode (Recommended)

/git:commit

What happens:

1. Claude analyzes staged changes using git diff --cached
2. Asks you what type of change this is (feat, fix, docs, etc.)
3. Asks for the scope (optional)
4. Asks for a description or suggests one based on the changes
5. Generates a properly formatted commit message
6. Shows you the message and asks for confirmation
7. Creates the commit with the approved message

Quick Mode with Arguments

# Feature with scope
/git:commit feat auth "add JWT authentication"

# Bug fix without scope
/git:commit fix "handle null response from server"

# Documentation update
/git:commit docs readme "update installation steps"

# Refactoring with scope
/git:commit refactor database "optimize query performance"

Common Usage Patterns

# Let Claude analyze changes and suggest commit message
/git:commit

# Specify type, Claude suggests scope and description
/git:commit feat

# Specify type and scope, Claude suggests description
/git:commit fix api

When to Use This Command

• Before committing changes to ensure proper message format
• When you want Claude to analyze your changes and suggest appropriate commit type
• When you need help writing clear, conventional commit messages
• When working on a project that requires Conventional Commits
• As a learning tool to understand Conventional Commits format

Language Requirements

All git-related text MUST be written in English:

• Commit messages
• Branch names
• Pull request titles and descriptions
• Code review comments
• Issue titles and descriptions

Commit Message Format

All commit messages MUST follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (formatting, etc)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests
• chore: Changes to the build process or auxiliary tools
• ci: Changes to CI configuration files and scripts

Scope

The scope should be the name of the component affected (as perceived by the person reading the changelog).

Examples:

• feat(auth): add login with Google
• fix(api): handle null response from server
• docs(readme): update installation steps

Description

• Use the imperative, present tense: "change" not "changed" nor "changes"
• Don't capitalize first letter
• No dot (.) at the end
• Write in english

Branch Naming Convention

Branches should follow this pattern:

<type>/<short-description>

For features and fixes that are tracked in a project management system, include the ticket number:

<type>/<ticket-number>-<short-description>

Examples:

• feat/add-google-auth
• fix/handle-null-responses
• docs/update-readme
• feat/PROJ-123-add-google-auth
• fix/PROJ-456-handle-null-responses

Workflow Guidelines

1. Protected Branches

   • main (or master): Production-ready code, protected branch
   • Direct commits to protected branches are NOT allowed
   • All changes must come through Pull Requests

2. Feature Development

   # First, check if you're on a protected branch
   git branch --show-current
   
   # If on main/master, create and checkout a new feature branch
   git checkout -b feat/my-new-feature main
   
   # Make changes and commit
   git add .
   git commit -m "feat(scope): add new feature"
   
   # Keep branch updated with main
   git fetch origin main
   git rebase origin/main
   
   # Push changes
   git push origin feat/my-new-feature
   

3. Pull Request Process

   • Create PR from feature branch to main/master
   • Use PR template if available
   • Request at least 2 code reviews
   • All tests must pass
   • No merge conflicts
   • Squash commits when merging

4. Release Process

   # Create release branch from main
   git checkout main
   git pull origin main
   git checkout -b release/v1.0.0
   
   # After testing, merge back to main via PR
   # After PR is approved and merged:
   git checkout main
   git pull origin main
   git tag -a v1.0.0 -m "version 1.0.0"
   git push origin main --tags
   

Examples

✅ Good Commits:

feat(auth): implement JWT authentication
fix(api): handle edge case in user validation
docs(api): update API documentation
style(components): format according to style guide
refactor(database): optimize query performance
test(auth): add unit tests for login flow

❌ Bad Commits:

Fixed stuff
Updated code
WIP
Quick fix

Implementation Workflow

When /git:commit is invoked, follow these steps:

Step 1: Analyze Current State

1. Check for staged changes:

   git diff --cached --stat
   

   • If no staged changes, inform user and suggest: git add <files>
   • Show summary of what will be committed

2. Check current branch:

   git branch --show-current
   

   • If on protected branch (main/master), warn user strongly
   • Suggest creating a feature branch instead

Step 2: Determine Commit Type

If type not provided as argument:

1. Analyze the changes with git diff --cached
2. Categorize based on file types and changes:
   • New files in /features/, new functions → likely feat
   • Changes in test files → likely test
   • Changes in README, docs/ → likely docs
   • Bug fixes, error handling → likely fix
   • Code cleanup, no behavior change → likely refactor
3. Suggest the most appropriate type to user
4. Ask user to confirm or choose different type

Step 3: Determine Scope

If scope not provided:

1. Look at file paths to identify component/module
2. Common patterns:
   • src/auth/* → scope: auth
   • src/api/* → scope: api
   • docs/* → scope: docs or specific doc name
   • Multiple components → ask user or use general scope
3. Suggest scope or ask user
4. Scope is optional - allow user to skip

Step 4: Create Description

If description not provided:

1. Analyze git diff --cached for key changes
2. Generate 2-3 description suggestions following rules:
   • Use imperative mood ("add" not "added" or "adds")
   • Start with lowercase
   • No period at end
   • Be specific but concise (max 50 chars for subject)
3. Present suggestions to user
4. Allow user to choose or provide their own

Step 5: Build Complete Message

1. Format as: <type>(<scope>): <description>
2. If changes are complex, ask if user wants to add body
3. For breaking changes, remind about BREAKING CHANGE: footer
4. Show complete formatted message to user

Step 6: Commit with Message

1. Show the final commit command:

   git commit -m "type(scope): description"
   

2. Ask for confirmation
3. Execute the commit
4. Show commit hash and summary
5. Remind about push if needed: git push origin <branch>

Step 7: Additional Guidance

After successful commit:

• Remind about related commits that should be squashed
• Suggest creating PR if feature is complete
• Remind about conventional commit benefits for changelog generation

Pre-commit Hooks

Consider using pre-commit hooks to enforce these conventions:

• Commit message format validation
• Code linting
• Test execution
• Branch naming validation
• Protected branch validation

Additional Notes

Avoid adding Claude as a co-author, while I understand that Claude wants recognition it's not always accurate that Claude has in any way contributed as a co-author beyond writing the commit message that this command is used for. If it's felt that Claude deserves to be listed as a co-author in the commit message it should be presented as an option before adding.