git-workflow — the grammar and hygiene of version control

Git history is a message to the next human who reads git log, runs git blame on a broken line, or bisects a regression at 2am. That human is usually future-you. Every rule in this skill exists to make the next reader's job faster, not to make this moment cheaper. A repo with legible branch names, conventional commits, and a clean linear narrative is a repo you can reason about; a repo with wip, fix stuff, and force-pushed shared history is one you fight.

This is the portable convention layer. It is independent of any SDD phase or CI platform — it is the grammar that ../ship/SKILL.md, ../worktrees/SKILL.md, and ../deployment/SKILL.md all lean on. It does not decide whether to land the work (that is ship) and it does not automate releases in a pipeline (that is deployment). It tells you how to name, commit, untangle, and tag — correctly.

Branch naming

Name a branch from its intent, prefixed by its kind, as a kebab-case slug. Keep it short-lived: hours to days, not weeks. Long branches drift from main and turn into merge pain.

Prefix	Use for	Why
feat/	a new capability	matches the feat commit type; signals a MINOR
fix/	a bug fix	matches fix; signals a PATCH
hotfix/	an urgent fix landing straight to production	flags "skip the slow path" to reviewers
chore/	tooling, deps, config — no product behavior	keeps non-feature noise out of the feature log
docs/	documentation only	reviewers can fast-track, no test gate needed
refactor/	restructure without behavior change	sets the expectation: tests stay green, no new behavior

Slug rules: derive it from the issue title or the one-sentence intent, lowercase, dash-separated, no spaces or / inside the slug. Optionally suffix the issue number.

Bad   my-stuff            (kind unknown, intent unknown)
Bad   eric-branch-2       (names the author and a counter, not the work)
Good  feat/oauth-pkce-flow
Good  fix/expired-refresh-token-401
Good  chore/bump-node-22

Commit grammar — gitmoji + Conventional Commits

Write every commit to Conventional Commits 1.0.0, opened by a gitmoji. The structure:

<gitmoji> type(scope)!: subject

body — what changed and why, wrapped, optional

BREAKING CHANGE: description of the incompatible change
Fixes #123

• The gitmoji is mandatory and comes first — the intention of the change, readable in one glyph when you scan git log --oneline. type is what tooling reads; the emoji is what humans read.
• type is mandatory. scope in parentheses is optional. ! before the colon marks a breaking change.
• Subject: imperative mood ("add", not "added"/"adds"), ≤72 chars, no trailing period.
• Body explains why, not what the diff already shows. Separate from subject by a blank line.
• Footers go last. Fixes #123 / Closes #123 in the body auto-closes that issue when the PR merges.

Type → SemVer effect:

Type	SemVer bump	Notes
feat	MINOR	a new capability
fix	PATCH	a bug fix
docs, chore, refactor, test, build, ci, perf, style, revert	none	allowed, but no implicit version bump
any type with ! or a BREAKING CHANGE: footer	MAJOR	overrides the above regardless of type

BREAKING CHANGE must be uppercase in the footer; the type/scope units are case-insensitive but write them lowercase by convention.

Type → gitmoji, the everyday set (the full 75-emoji table, and why the emoji never replaces the type, are in references/gitmoji.md):

Type	gitmoji	Type	gitmoji	Type	gitmoji
feat	✨	refactor	♻️	build	📦️
fix	🐛	test	✅	style	🎨
docs	📝	perf	⚡️	revert	⏪️
chore	🔧	ci	👷	breaking	💥

Pick by intention, not by which file changed, and prefer the specific one: 🚑️ for a production hotfix, 🩹 for a trivial non-critical fix, 🔥 for a deletion, 🚚 for a rename, ⬆️ for a dep bump, 🔖 for a release commit.

Bad   fix stuff
Bad   updates
Bad   Fixed the login bug.            (past tense, capitalized, trailing period)
Bad   fix(auth): reject expired refresh tokens        (no gitmoji)
Bad   ✨ added a search endpoint                       (gitmoji but no type → no derivable bump)
Good  🐛 fix(auth): reject expired refresh tokens
Good  ✨ feat(api): add /v2/search endpoint with cursor paging
Good  ♻️ refactor(parser): extract token scanner, no behavior change

A breaking change, both forms equivalent:

💥 feat(api)!: drop the legacy /v1 search endpoint

BREAKING CHANGE: /v1/search is removed; callers must migrate to /v2/search.

If the repo runs a strict conventional parser (commitlint, semantic-release) it anchors the type at position 0 and rejects the emoji prefix. Either widen its headerPattern — the config is in references/gitmoji.md — or move the emoji behind the header (feat(api): ✨ add cursor paging), which every parser accepts. Both forms satisfy this convention; dropping the gitmoji does not.

Authorship is always Eric. Never add a Co-Authored-By: Claude trailer, never a "Generated with" footer, never any line crediting an AI tool — in a commit or a PR body. The work is Eric's; the agent is a tool, like the compiler.

History hygiene — rebase, merge, or squash?

Decide by who else has the commits. The lease rule below is non-negotiable.

Situation	Do this	Why
Private branch, only you have it, want linear history	git rebase main, then git push --force-with-lease	rebase rewrites hashes; safe because nobody built on them
Branch others have pulled / built on	git merge main — never rebase it	rebase changes every hash; collaborators' work diverges
Noisy PR (many wip commits)	squash-merge into one gitmoji + conventional commit	main gets one meaningful entry, not 9 scratch commits
Already pushed, shared, and you rewrote it	STOP — coordinate, or git revert instead	force-pushing shared history breaks everyone downstream

After a rebase, push with --force-with-lease, never bare --force:

git push --force-with-lease   # refuses if the remote moved since you fetched — catches a teammate's push
git push --force              # blindly overwrites — can erase a teammate's commits

The interactive cleanup loop (rebase -i, fixup/squash/reword/drop, --autosquash, the conflict→continue cycle, and recovery via git reflog) is a long branchy procedure — see references/interactive-rebase.md rather than reaching for it on every commit.

Releases

Derive the version bump from the commit log, never by guessing. Scan the commits since the last tag:

• any BREAKING CHANGE: / ! → MAJOR (v1.4.2 → v2.0.0)
• otherwise any feat: → MINOR (v1.4.2 → v1.5.0)
• otherwise only fix:/others → PATCH (v1.4.2 → v1.4.3)

Tag with the vMAJOR.MINOR.PATCH form, annotated, then create the release with auto-generated notes:

git tag -a v2.0.0 -m "v2.0.0"
git push origin v2.0.0
gh release create v2.0.0 --generate-notes              # notes via the GitHub Release Notes API
gh release create v2.0.0 --generate-notes --draft      # stage notes, publish later
gh release create v2.0.0-rc.1 --generate-notes --prerelease

GitHub auto-assigns the "latest" label by semver order unless you set it. With release immutability enabled, a published release's tag cannot be edited or deleted — get the version right before you publish.

Bad   added a feature + a breaking config change, tagged v1.5.0   (breaking change → must be MAJOR)
Good  same changes → v2.0.0, bump derived from the BREAKING CHANGE footer in the log

Automating any of this on tag push (a release.yml workflow, OIDC to a registry) is deployment — see ../deployment/SKILL.md. This skill covers the manual/local release act.

PR mechanics — then hand off to ship

Open the PR with autofilled title/body from the commits, against the right base:

gh pr create --fill --base main          # title/body from commits; --base falls back to repo default

Put Fixes #123 in the body to link and auto-close the issue on merge. A PR body should let the reviewer understand the change without reading every line of the diff.

The decision to land — direct-merge vs PR vs park, the pre-ship safety checklist, the actual merge — belongs to ../ship/SKILL.md. This skill only makes the branch, commits, and PR body clean enough to hand over. Setting up the isolated checkout before you start coding is ../worktrees/SKILL.md.

Anti-patterns

Anti-pattern	Why it hurts	Instead
git push --force on a shared branch	silently erases teammates' commits	--force-with-lease, or don't rewrite shared history
git commit -m "wip" / "fix" / "updates"	the log carries zero signal for the next reader	<gitmoji> type(scope): imperative subject
Commit message with no gitmoji	git log --oneline reads as a wall of undifferentiated text	pick the intention's emoji (references/gitmoji.md)
Mixing unrelated changes in one commit	can't revert or review one concern in isolation	one logical change per commit
Long-lived branch (weeks)	diverges from main, merge becomes a battle	short-lived; rebase or merge main in often
Hand-computing the semver bump	breaking change shipped as a MINOR → broken downstream	derive the bump from the commit log
Rebasing a public/shared branch	rewrites hashes others built on	merge shared branches; rebase only private ones
Committing generated/secret files	leaks credentials, bloats history irreversibly	.gitignore; rotate any secret that slipped in
BREAKING CHANGE lowercase	tooling won't detect it → wrong (too-low) bump	uppercase BREAKING CHANGE: in the footer
PR with no description	reviewer reverse-engineers intent from the diff	--fill plus a why, link the issue
Tagging a release with no notes	users can't tell what changed	gh release create --generate-notes
Co-Authored-By: Claude / "Generated with" footer	forges authorship onto a tool	author is always Eric; no AI attribution

Checklist — before a PR or a release

• Working tree clean (git status), no stray or generated files staged.
• Branch rebased on / merged with current main; no avoidable conflicts.
• Every commit carries its gitmoji and a conventional header; wip/scratch commits squashed away.
• No secrets, no AI-attribution trailers.
• PR body explains the why and links the issue (Fixes #).
• (Release) version bump derived from the commit log, tag is vX.Y.Z, annotated.
• (Release) gh release create vX.Y.Z --generate-notes; version confirmed before publishing (immutable once published).