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
)"