Git Workflow

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.

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:

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

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.

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.