basher83/git-workflow

Git Workflow Best Practices

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

Available Skills

This plugin provides fork-isolated skills to automate git workflows:

| Skill | Purpose | |-------|---------| | git-status | Quick repository status summary | | git-commit | Create commits with pre-commit hooks via commit-craft agent | | branch-cleanup | Clean up merged/stale branches | | generate-changelog | Generate CHANGELOG.md using git-cliff |

All workflow skills use context: fork for delegation isolation. The git-commit skill delegates to the commit-craft agent, which handles the full commit workflow including pre-commit hook detection, execution, and failure recovery.

Changelog Generation

Use generate-changelog after creating commits to update CHANGELOG.md. Accepts an optional action argument (preview, generate, release). Without an argument, prompts interactively.

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

| Type | Purpose | |------|---------| | feat | New feature | | fix | Bug fix | | docs | Documentation only | | style | Formatting, no code change | | refactor | Code restructuring | | perf | Performance improvement | | test | Adding/updating tests | | build | Build system changes | | ci | CI configuration | | chore | Maintenance tasks | | revert | Revert previous commit |

Subject Line Rules

• Maximum 72 characters
• Use imperative mood ("add feature" not "added feature")
• No period at end
• Lowercase subject (e.g. feat(auth): add oauth2 login — match the casing of existing commits in the repo if a different convention is established)

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

| Prefix | Purpose | Example | |--------|---------|---------| | feature/ | New functionality | feature/user-authentication | | fix/ | Bug fixes | fix/login-redirect-loop | | hotfix/ | Urgent production fixes | hotfix/security-patch | | release/ | Release preparation | release/v2.1.0 | | docs/ | Documentation updates | docs/api-reference | | refactor/ | Code restructuring | refactor/database-layer | | test/ | Test additions | test/integration-suite | | chore/ | Maintenance | chore/dependency-updates |

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

Pushing to Main

Default for solo work: commit and push directly to main. Branches and PRs add friction without review value when no one else is reviewing.

Use a branch + PR only when:

• The repo has CI gates (tests, lint, build checks) that run on PRs and the operator wants those gates enforced before merge.
• Working with collaborators who review changes.
• The change is risky enough that the operator wants an explicit checkpoint (revert-by-merge, staged rollout).

Force-push to main is acceptable on solo repos to rewrite local mistakes (e.g. amending a just-pushed commit), but confirm with the operator first if the commit may already be referenced elsewhere.

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