git-workflows

Git Workflows

When to Use

• Creating commits with conventional commit messages
• Shipping code (commit + review + push + PR)
• Creating pull requests with proper descriptions
• Generating changelogs from commit history
• Preparing code for review or merge

When NOT to Use

• Basic git operations (status, diff, log) — just run them directly
• Branch management strategy — use using-git-worktrees
• Code review content — use requesting-code-review

---

Quick Reference

Workflow	Reference	Key content
Committing	references/committing.md	Conventional commits, message format, pre-commit checks
Shipping	references/shipping.md	Full ship workflow: review → test → commit → push → PR
Pull Requests	references/pull-requests.md	PR creation, description templates, gh CLI patterns
Changelogs	references/changelogs.md	Changelog generation from commits, Keep a Changelog format

---

Conventional Commit Format

type(scope): subject

body (optional)

footer (optional)

Type	When
feat	New feature
fix	Bug fix
docs	Documentation only
refactor	Code restructuring, no behavior change
test	Adding or fixing tests
chore	Maintenance, dependencies, CI
style	Formatting, whitespace

Subject Line Rules

• Max 50 characters, imperative mood ("Add" not "Added"), no trailing period

---

Ship Workflow

1. Pre-ship checks (secrets, debug statements)
2. Self-review (code quality, style)
3. Run tests (full suite, coverage check)
4. Create commit (conventional format)
5. Push to remote
6. Create PR (summary, test plan, checklist)

---

PR Description Template

## Summary
- [Change 1]
- [Change 2]

## Test Plan
- [ ] Unit tests pass
- [ ] Manual testing done

## Checklist
- [ ] No breaking changes
- [ ] Tests added/updated
- [ ] Documentation updated

---

Best Practices

1. Atomic commits — one logical change per commit, not one file per commit.
2. Explain why, not what — the diff shows what changed; the message explains why.
3. Stage specific files — prefer git add <file> over git add -A to avoid committing secrets or unrelated changes.
4. Reference issues — include Closes #123 or Fixes #456 in footers.
5. Pre-commit checks — verify no secrets, debug statements, or commented-out code before committing.
6. PR descriptions matter — reviewers read the description before the diff; make it count.

Common Pitfalls

1. Committing secrets — .env files, API keys, tokens in staged changes.
2. Vague commit messages — "fix stuff", "updates", "WIP" provide no context.
3. Giant PRs — 500+ line PRs get rubber-stamped; split into focused chunks.
4. Amending published commits — rewriting history others have pulled causes conflicts.
5. Skipping pre-commit hooks — --no-verify hides real issues.
6. Force pushing to shared branches — can destroy teammates' work.

---

Related Skills

• requesting-code-review — Preparing changes for reviewer feedback
• finishing-a-development-branch — End-of-branch workflow decisions
• using-git-worktrees — Isolated branch management