Git Workflow Best Practices

Guidance for creating clean, atomic commits and organizing git workflows effectively.

Available Commands

This plugin provides commands to automate git workflows:

Changelog Generation

Use /generate-changelog after creating commits to update CHANGELOG.md. The command uses a workflow-driven approach:

1. Shows current state (branch, recent commits, latest tag, unreleased changes)
2. Prompts to select action: Preview, Generate, or Release
3. For releases, analyzes commits and recommends version bump level

Conventional Commit Format

Structure commit messages following the conventional commit specification. Project-specific CLAUDE.md conventions take precedence over these defaults.

type(scope): subject

body (optional)

footer (optional)

Commit Types

Subject Line Rules

• Maximum 50 characters
• Use imperative mood ("Add feature" not "Added feature")
• No period at end
• Capitalize first letter

Body Guidelines

• Wrap at 72 characters
• Explain what and why, not how
• Separate from subject with blank line

Footer Conventions

• Reference issues: Fixes #123 or Relates to #456
• Breaking changes: BREAKING CHANGE: description
• Co-authors: Co-Authored-By: Name <email>

Branch Naming Conventions

Use descriptive, prefixed branch names:

Branch Prefixes

Naming Rules

• Use kebab-case (lowercase with hyphens)
• Keep names descriptive but concise
• Include ticket/issue number when applicable: feature/123-user-auth
• Avoid generic names like feature/update or fix/bug

Atomic Commit Principles

Create commits that are:

1. Self-contained: Each commit represents one logical change
2. Complete: Code compiles and tests pass after each commit
3. Reviewable: Small enough to understand in one review session

Grouping Guidelines

• Keep implementation and tests together
• Separate infrastructure from application changes
• Isolate documentation unless integral to code changes
• Group by feature/component/purpose
• Keep related lock files with their manifests (package-lock.json with package.json)

What NOT to Mix

• Unrelated bug fixes in the same commit
• Formatting changes with logic changes
• Multiple features in one commit
• Refactoring with new functionality

Pre-Commit Workflow

Before committing:

1. Review changes: git diff and git status
2. Check for sensitive files: Never commit .env, credentials, API keys
3. Run pre-commit hooks: Let formatters and linters process files
4. Re-stage if hooks modify files: Add reformatted files and retry commit

Handling Pre-Commit Hook Failures

When hooks modify files:

1. Review the changes made by hooks
2. Re-add the modified files: git add <files>
3. Retry the commit
4. Document any issues for manual review

Commit Message Template

Use heredoc format for multi-line messages:

git commit -m "$(cat <<'EOF'
type(scope): subject line here

- Detailed bullet point explaining change
- Another relevant detail

Fixes #123
EOF
)"

Protected Branches

Never force-push or directly commit to:

• main / master
• develop
• staging / production
• release/* branches

Always use pull requests for these branches.

Quick Reference

Creating a Feature Branch

git checkout -b feature/descriptive-name

Checking What to Commit

git status                    # See all changes
git diff                      # Unstaged changes
git diff --cached             # Staged changes
git log --oneline -5          # Recent commit style

Staging Selectively

git add path/to/specific/file.ext
git add -p                    # Interactive staging

Writing Good Commits

# Simple commit
git commit -m "feat(auth): add OAuth2 login support"

# Multi-line commit
git commit -m "$(cat <<'EOF'
fix(api): resolve race condition in request handler

- Add mutex lock around shared state
- Implement request queuing for high load
- Add timeout handling for stale requests

Fixes #456
EOF
)"