Visualizing git branching strategies with Mermaid gitGraph

Every team has a branching strategy. Most teams have never written it down. The result is a mix of tribal knowledge, conflicting PRs, and the inevitable "wait, do I merge main into my branch or rebase?" question that surfaces at the worst possible time.

Mermaid's gitGraph diagram type lets you document your branching model in plain text and drop it into your contributing guide or README — where it gets read, not lost in a wiki nobody opens.

What gitGraph does

gitGraph renders a visual representation of git history: commits, branches, merges, and cherry-picks. Unlike a screenshot of git log --graph, it's editable, version-controlled, and doesn't become stale when someone force-pushes.

A minimal example:

gitGraph
    commit id: "Initial commit"
    commit id: "Add auth"
    branch feature/login
    checkout feature/login
    commit id: "Login form"
    commit id: "Auth API"
    checkout main
    merge feature/login id: "Merge login"
    commit id: "Hotfix: typo"

This renders a two-branch history with a merge back to main. The id on each commit becomes its label.

The syntax

gitGraph
    commit [id: "label"] [tag: "v1.0"]
    branch <branch-name>
    checkout <branch-name>
    merge <branch-name> [id: "label"]
    cherry-pick id: "<commit-id>"

A few things to know:

• checkout switches the active branch. New commits land on whichever branch is currently checked out.
• branch creates a new branch from the current HEAD.
• merge merges the named branch into the currently checked-out branch.
• cherry-pick id copies a commit by its id to the current branch. The ID must match a commit defined earlier in the diagram.

Documenting trunk-based development

Trunk-based development is easy to describe in words ("everyone commits to main, feature branches are short-lived") but the nuances are clearer visually:

gitGraph
    commit id: "Initial"
    branch feature/payments
    checkout feature/payments
    commit id: "Payment form"
    commit id: "Stripe integration"
    checkout main
    merge feature/payments id: "Merge payments"
    branch feature/notifications
    checkout feature/notifications
    commit id: "Email service"
    checkout main
    merge feature/notifications id: "Merge notifications"
    commit id: "Release v1.1" tag: "v1.1"

The diagram makes two things visible that prose can't: branches are short (two commits each) and nothing lives off main for long.

Documenting Gitflow

Gitflow is more complex — a develop branch, feature branches off develop, release branches, and hotfixes off main. A diagram pays for itself here:

gitGraph
    commit id: "Initial" tag: "v1.0"
    branch develop
    checkout develop
    commit id: "Baseline"
    branch feature/user-profiles
    checkout feature/user-profiles
    commit id: "Profile page"
    commit id: "Avatar upload"
    checkout develop
    merge feature/user-profiles id: "Merge profiles"
    branch release/1.1
    checkout release/1.1
    commit id: "Bump version"
    commit id: "Fix edge case"
    checkout main
    merge release/1.1 id: "Release" tag: "v1.1"
    checkout develop
    merge release/1.1 id: "Sync release"
    branch hotfix/login-bug
    checkout hotfix/login-bug
    commit id: "Fix login redirect"
    checkout main
    merge hotfix/login-bug id: "Hotfix" tag: "v1.1.1"
    checkout develop
    merge hotfix/login-bug id: "Sync hotfix"

This is the kind of diagram that saves 20 minutes of explanation for every new team member. Writing it down also tends to surface questions the team hadn't consciously asked — "do we always sync hotfixes back to develop immediately, or after the next release?"

Practical tips

Keep commits representative, not exhaustive. A gitGraph for documentation should show the pattern, not the entire history. Three or four commits per branch illustrates the cadence without overwhelming readers.

Use tag to mark releases. Tags render as labels on commits and make the versioning strategy visible at a glance. commit id: "Release" tag: "v1.1" is clearer than just commit id: "Release".

Label merges clearly. merge feature/payments id: "Merge payments" is more scannable than an unlabeled merge node, especially in a diagram with multiple branches converging.

Match your real branch names. Documentation that uses feature/login when your team uses feat/login creates exactly the confusion you were trying to prevent. Copy-paste your actual branch naming convention.

Put the diagram where the policy lives. A gitGraph in CONTRIBUTING.md is seen by every contributor when they first open a PR. A gitGraph in a separate wiki page is seen by people who are already confused enough to search for it.

Beyond branching strategies

gitGraph is useful anywhere you need to show "this happened before that" across parallel lines of work:

• Post-mortems — reconstruct what the branch history looked like before the bad merge, and show how it was resolved.
• Changelogs — a visual commit history from v1.0 to v1.1 gives context that a bullet list can't.
• Onboarding — "here's the three-step lifecycle of a feature: branch from main, PR to main, squash merge." A diagram is faster to scan than a numbered list.
• Comparing strategies — put a trunk-based and a Gitflow diagram side by side in a decision document. The tradeoffs jump off the page.

What gitGraph can't do

Mermaid's gitGraph is a documentation tool, not a git client. It won't validate that your diagram matches your actual repository, and it doesn't support every git operation (rebasing, for example, isn't representable). Think of it like a subway map — an accurate abstraction optimized for navigation, not a satellite image of the tracks.

For repositories with complex histories, consider showing one representative sprint or release cycle rather than trying to capture everything.

Getting started

Draft your branching model in MermaidCreator's visual editor, adjust until it matches your actual workflow, and paste the Mermaid source directly into your CONTRIBUTING.md or team wiki. Because it's plain text, your next update is a one-line edit — not a redesign session in a diagram tool.

The best branching strategy is the one the whole team can see, explain, and follow. A diagram helps with all three.