GitGraph for Release and Branch Strategy with Mermaid

Branching strategy is one of those topics that’s easy to argue about and hard to explain—until you draw it.

Mermaid’s GitGraph diagrams are perfect for documenting:

• trunk-based vs GitFlow
• release branches
• hotfixes
• cherry-picks
• backports
• tagging releases

And unlike screenshots from a slide deck, Mermaid diagrams live right next to your engineering docs and can evolve as your process evolves.

This post focuses on practical release/branch patterns, with copy/paste diagrams you can adapt.

A quick refresher

GitGraph diagrams start with gitGraph and then you describe commits, branches, checkouts, merges, and tags.

Mermaid’s GitGraph syntax has evolved over time; if a snippet doesn’t render in your setup, the structure is still useful as a reference for adjusting to your renderer’s supported syntax.

The smallest example

Source

Rendered

1) Trunk-based development (the “default” for many teams)

Trunk-based usually means:

• short-lived branches
• frequent merges to main
• feature flags for incomplete work
• releases from main

Trunk-based with a short-lived feature branch

Source

Rendered

When trunk-based goes wrong

Common failure modes:

• long-lived feature branches (merge pain)
• “release day” merges (risk spike)
• no feature flags (incomplete work leaks)

GitGraph diagrams are a nice way to show what you want to avoid.

2) Release branches (stabilize without freezing main)

A release branch lets you stabilize while main keeps moving.

Release branch + patch releases

Source

Rendered

Tip: Keep release branches short-lived. If they live forever, you’re maintaining two trunks.

3) Hotfixes (production is on fire)

Hotfixes usually start from the last production tag and get merged forward.

Hotfix branch from a production tag

Source

Rendered

A note on “merge forward”

If you hotfix production but forget to merge forward into main, you’ll reintroduce the bug later.

A GitGraph diagram makes that rule visual.

4) Backports and cherry-picks (supporting multiple versions)

If you maintain multiple supported versions, you’ll likely need backports.

Backport a fix to an older release branch

Source

Rendered

Tip: If you backport regularly, write down the policy: which fixes qualify, how long you support old branches, and who approves.

5) GitFlow (feature + develop + release + hotfix)

GitFlow is heavier than trunk-based, but some teams still use it successfully—especially with longer release cycles.

A GitFlow-shaped diagram

Source

Rendered

The GitFlow footgun

If you don’t merge the release branch back into develop, the divergence grows and you’ll get surprise conflicts.

6) A “release playbook” diagram (staged rollout + tags)

This pattern is useful when you tag releases, then deploy to environments in order.

Source

Rendered

In many orgs, the “deploy branches” are more conceptual than literal. If you don’t use them, keep the diagram focused on tags and environments.

7) Common gotchas (and fixes)

Gotcha: diagrams become too detailed

Fix: keep GitGraph diagrams narrative-level. You’re documenting the strategy, not every commit.

Gotcha: branch names don’t match reality

Fix: mirror your actual conventions: release/x.y, hotfix/x.y.z, feature/<name>.

Gotcha: unclear ownership

Fix: add a short section in the post:

• who cuts release branches
• who approves hotfixes
• who tags releases

8) A blog-ready checklist

Before you publish:

• Choose one strategy per post (or clearly compare two).
• Keep to 10–20 commits.
• Use tags to mark releases (v1.2.3).
• Show the “merge forward” rule for hotfixes.
• If you support multiple versions, show a backport example.

Where to go next

If GitGraph clicks for you, the next Mermaid diagram type that complements release strategy is sequence diagrams for your CI/CD pipeline (build → test → deploy → verify), or flowcharts for release checklists and go/no-go decisions.