/git-collaboration-workflows

name: git-collaboration-workflows
description: Run git collaboration that scales — trunk-based vs git-flow decided by deploy cadence, branch protection and required checks, PR sizing and review etiquette, monorepo vs polyrepo trade-offs, release branches and hotfixes, and history hygiene with disciplined merges.
type: skill
version: 1.0.1
updated: 2026-07-27

Git Collaboration Workflows

Git workflow debates are proxy wars over one variable: **how often you ship**. Choose the branching model from your deploy cadence, enforce it with branch protection instead of vigilance, and keep PRs small enough to review honestly. Deep detail in `references/`; protection settings and a PR-review playbook in `examples/`; `scripts/check-branch-hygiene.mjs` audits a repo's local hygiene.

Choosing the branching model

| You deploy… | Model | Shape | |---|---|---| | Continuously (SaaS default) | **Trunk-based** | Short-lived branches (<2 days) → main; release = deploy main; flags hide unfinished work | | On a cadence (mobile, desktop) | Trunk + **release branches** | Cut `release/1.24` from main; only cherry-picked fixes land on it; tag ships | | Multiple supported majors (enterprise, on-prem) | Trunk + long-lived release lines | Fix on main first, cherry-pick back (never the reverse) |

Full git-flow (develop + feature + release + hotfix branches) earns its complexity only in the third row — adopted by SaaS teams it mostly adds merge ceremony and delays integration. The deciding question is never taste; it's "what do we support in production simultaneously?"

trunk-based:   main ──●──●──●──●──►            release = deploy latest green main
cadence:       main ──●──●──●──►               release/1.24 ──●(cp)──tag 1.24.1
hotfix:        branch from the SHIPPED TAG, fix, tag — then forward-port to main SAME DAY

Mechanics of each and the hotfix path: `references/branching-models.md`.

Short-lived branches or bust

Integration pain grows superlinearly with branch age — two weeks of divergence is a merge project. Working rules:

branch age    < 2 days   (rebase on main daily if longer is unavoidable)
PR size       ≤ ~400 changed lines — review quality collapses beyond that
one PR        one logical change (refactor ≠ behavior change ≠ formatting)
big features  land dark in slices behind a flag (feature-flags-experimentation),
              never in a long-lived feature branch

Stacked PRs (chain of small dependent PRs) are the escape hatch when a change is genuinely large: reviewable slices, one logical narrative — etiquette and mechanics in `examples/pr-review-playbook.md`.

Protection is policy-as-config

Trust the settings, not the culture doc — `examples/branch-protection.md` has the full recommended set. The load-bearing ones: required status checks (build + tests + lint, the same gate for everyone including admins), required review (1 for most teams, 2 for money/security paths via CODEOWNERS), **stale-review dismissal** (a re-push invalidates old approvals), and linear history or squash-only merges so `main` reads as a changelog. Conventional commit messages (`conventional-commits`) make that changelog machine-readable.

Merge strategy: pick one, encode it

• **Squash-merge** (default recommendation): PR = one commit on main; messy WIP commits

vanish; revert = one commit. Cost: intra-PR history lost — fine when PRs are small (rule above).

• **Rebase-merge**: preserves commit series linearly — only worth it if authors curate

commits (interactive rebase discipline); otherwise you're preserving noise.

• **Merge commits**: keeps true topology; `main` becomes unreadable at scale. Reserve for

release-branch merges where the merge point *is* the information.

• Never mix by whim — one strategy per repo, enforced in settings. And **never rewrite

pushed shared history**; `revert` forward instead (`references/history-hygiene.md` covers recovery, bisect, and blame-friendly practices).

Monorepo vs polyrepo (an ownership decision)

Monorepo buys atomic cross-cutting changes, one dependency graph, and universal refactors — at the price of tooling (selective CI via path filters/affected-graphs, CODEOWNERS, merge queues at scale). Polyrepo buys independent pace and clear boundaries — at the price of version-matrix coordination (`release-coordination` in `deployment-strategies`) and cross-repo changes becoming N-PR projects. Rule of thumb: one product surface + one deploy train → monorepo; genuinely independent products/teams → polyrepo. The failure mode is the *unmanaged* middle: 40 repos with hand-maintained version matrices and no contract tests.

Pitfalls

• Long-lived feature branches "to keep main stable" — main stays stable via checks and

flags; the branch just batches risk into one giant merge.

• `main` broken and normalized ("just skip that test") — a red main blocks everyone's

integration; fixing it outranks all feature work, and a merge queue prevents most of it.

• Force-push to shared branches — reflog archaeology for the whole team; protect against it

in settings.

• Review theater: 2,000-line PRs approved in 4 minutes — the size rule exists because

reviewers are human.

• Cherry-picking main→release without fixing main first — the fix vanishes in the next

release cut.

Verification

Run `node scripts/check-branch-hygiene.mjs` inside any repo: it reports stale branches, oversized undelivered work, and non-linear history segments. Then diff your repo settings against `examples/branch-protection.md`. Pairs with `conventional-commits`, `ci-pipeline-design`, `code-review` practices in `deployment-strategies`, and `feature-flags-experimentation`.