# Git Workflow

> Git workflow guidance for branch naming, conventional commits, PR title format, merge strategy, and safe history rewriting. Use when creating branches, preparing commits, or reviewing repository hygiene. Use when this capability is needed.

- Skill: `tomevault-io/git-workflow-112` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/git-workflow-112`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/git-workflow-112/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/git-workflow-112

---


# Git Workflow

Keep history readable, reviewable, and safe for collaborators by using consistent branch names, conventional commits, and disciplined merge behavior.

## When to Activate

- Start a new feature or fix branch
- Prepare commits before opening a PR
- Rename a noisy branch before review
- Decide whether to squash or merge
- Rewrite branch history after review feedback
- Audit commit hygiene before release
- Recover from a mistaken push safely

## Branch Naming

| Change Type | Pattern | Example |
| --- | --- | --- |
| Feature | `feat/<topic>` | `feat/api-pagination` |
| Fix | `fix/<topic>` | `fix/jwt-expiry-check` |
| Chore | `chore/<topic>` | `chore/update-ci` |

## Conventional Commits

| Type | Use When |
| --- | --- |
| `feat:` | User-visible capability added |
| `fix:` | Bug fixed |
| `docs:` | Documentation only |
| `chore:` | Maintenance with no product behavior change |
| `refactor:` | Structure changed without behavior change |
| `test:` | Tests added or updated |
| `perf:` | Measurable performance improvement |

```text
feat(api): add cursor pagination to list users

Why:
- offset scans were timing out on large tenants

What:
- added cursor token parsing
- exposed page.has_more
```

## Pull Requests and Merge Strategy

| Field | Format |
| --- | --- |
| PR title | `<type>(<scope>): <summary>` |
| Description | problem, approach, risks, validation |
| Linked work | issue or ticket reference when available |

| Situation | Preferred | Avoid |
| --- | --- | --- |
| Small feature branch | Squash merge | Preserving noisy fixup history |
| Multi-commit change with meaningful milestones | Merge commit | Squashing away useful audit trail |
| Local cleanup before review | Rebase locally | Rewriting shared branch unexpectedly |

## Safe Rewrites

| Operation | Rule |
| --- | --- |
| Rewrite your own reviewed branch | Use `--force-with-lease` |
| Rewrite shared branch used by others | Do not do it without explicit coordination |
| Recover from mistaken push | Prefer revert when branch is public |

BAD

```text
commit message: stuff
branch: new-branch
```

GOOD

```text
commit message: fix(auth): reject expired refresh tokens
branch: fix/refresh-token-expiry
```

## Checklist

- [ ] Branch name matches `feat/`, `fix/`, or `chore/` intent
- [ ] Commit subject uses a conventional commit type
- [ ] Commit body explains why the change exists when context is non-trivial
- [ ] PR title matches commit style
- [ ] Merge strategy fits the branch history
- [ ] Shared history is never force-pushed without `--force-with-lease`
- [ ] Review fixups are squashed or left intentionally

---
> Source: [kid-sid/codex-spellbook](https://github.com/kid-sid/codex-spellbook) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-16 -->