# Git Workflow

> Git workflow conventions — branch naming, conventional commits, PR descriptions, and merge strategy. Use when deciding on a branch name, writing a commit message or PR description, or choosing a merge strategy.

- Skill: `projectious-work/git-workflow` (Agent Skill)
- Install (CLI): `npx skillmds add projectious-work/git-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/projectious-work/git-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: projectious-work (https://skillmd.com/u/projectious-work)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/projectious-work/git-workflow

---


# Git Workflow

## Intro

Use typed branch names, Conventional Commits, and PR descriptions
that explain the why. Squash-merge feature branches for a clean
history. Keep commits atomic and never force-push to shared
branches.

## Overview

### Branch naming

Format: `<type>/<issue>-<short-description>`

Types: `feat/`, `fix/`, `refactor/`, `docs/`, `chore/`

Examples:

- `feat/42-add-user-auth`
- `fix/17-null-pointer-crash`
- `refactor/89-extract-payment-service`

### Commit messages

Follow Conventional Commits:

- **Format:** `<type>: <description>` — lowercase, imperative
  mood, no trailing period
- **Types:** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`,
  `ci`
- **Body:** explain WHY, not WHAT (the diff shows what)
- **Footer:** `fixes #N` or `refs #N` for issue links

### PR descriptions

- **Title:** same format as commit messages, under 70 characters
- **Body:** Summary (what and why), test plan, breaking changes
- Link related issues

### Merge strategy

- **Squash merge** for feature branches — keeps mainline history
  clean
- **Merge commit** for long-lived branches — preserves context
  across the merge
- **Rebase** to keep a feature branch up to date before opening
  the PR

## Gotchas

Agent-specific failure modes — provider-neutral pause-and-self-check items:

- **Mega-commits ("various fixes", 40 files changed).** A commit that mixes unrelated changes is impossible to review, impossible to revert selectively, and tells a lie in its message. Each commit should represent one logical change that can stand alone.
- **Force-pushing to shared branches.** Force-pushing to `main` or any branch others have checked out rewrites history they depend on, causing diverged local states that are painful to recover. Never force-push to a shared branch.
- **Branches that live for months.** Long-lived branches diverge from main, accumulate merge conflicts, and eventually require heroic merge efforts. Rebase weekly or split long-running work into shorter-lived feature branches.
- **PRs with no description.** "See commits" is not a description. The PR description is for the reviewer — it explains what changed, why it changed, and how to verify it. Write it before requesting review.
- **Conventional Commit type misuse.** Using `fix:` for features or `feat:` for refactors corrupts any automation that generates changelogs or determines version bumps from commit types. Match the type to the nature of the change.
- **Squash-merging a long-lived integration branch.** Squash-merge is for feature branches with noisy "wip" commits. A long-lived branch with meaningful commit history should be merge-committed so the history is preserved for future investigation.
- **Committing unrelated changes in the same PR to "save time".** Reviewers are slower on unrelated changes combined in one PR; rollback becomes more expensive if one change needs reverting. Split unrelated changes into separate PRs.

## Full reference

### General rules

- Commit early and often on feature branches; squash at merge time.
- Never force-push to shared branches (`main`, `develop`, release
  branches).
- Keep commits atomic — one logical change per commit. A commit
  that touches three unrelated concerns is three commits.
- A commit message body wraps at 72 columns; the subject line at
  50 if you can.

### Worked example

User: "What should I name this branch for adding search?"

Suggest `feat/30-add-search-functionality` if there's an issue
#30; otherwise `feat/add-search-functionality`. Match the
existing repo's convention if it differs.

### Anti-patterns

- **Mega-commits** — "various fixes" with 40 files changed.
  Impossible to review or revert.
- **Force-push to main** — destroys other contributors' work.
- **Commit messages like "wip", "fix", "stuff"** — every commit
  should be reviewable on its own.
- **PRs with no description** — the PR description is for the
  reviewer, not the author. "See commits" is not a description.
- **Branches that live for months** — long-lived branches
  diverge from main and become merge nightmares. Rebase weekly
  or split the work.

### When to break the rules

Solo-on-a-private-branch force-pushes are fine. Trivial typo
fixes don't need a long body. Use judgment, but the defaults
above are right for almost every team setting.