What's the basic operation set in Mermaid gitGraph syntax?

Four primitives cover most needs. commit adds a commit to the current branch. branch creates a new branch and switches to it. checkout switches to an existing branch (does not create). merge merges the named branch into the current one. Operations stack in source order, just like real git commands. Add modifiers to commits (commit id: "name", commit tag: "v1.0", commit type: HIGHLIGHT) to label and style individual nodes.

How do I tag a release in a Mermaid git graph?

Two ways. Tag the merge commit itself with merge develop tag: "v1.0.0" — the tag appears on the merge node. Or tag a standalone commit with commit tag: "v1.0.0" — the tag attaches to that specific commit. Most release workflows tag the merge into main, so the first form is more common. Tags render as labelled badges next to the commit node and are the standard way to show release points in onboarding documentation.

Can I render the git graph horizontally?

Yes — add LR after gitGraph: gitGraph LR:. The default orientation is vertical (top-down) with branches stacked, but for wide documentation surfaces — onboarding pages, README files, slide decks — horizontal orientation often reads better. The same commit / branch / merge syntax works in both layouts. Pick horizontal when the diagram needs to be wider than tall to fit its destination; pick vertical (the default) for narrow side panels and standard documentation.

How do I show a cherry-pick?

Use cherry-pick id: "commit-id" — this brings a single commit from another branch into the current branch without merging the whole history. Cherry-picks are useful for showing hotfix propagation: when a fix on main needs to be backported to an older release branch, cherry-pick is the actual git operation and cherry-pick id: "hotfix" is the diagram syntax. The referenced commit id must exist elsewhere in the graph (declared earlier on another branch) for the cherry-pick to render correctly.

Why is my git graph so cluttered?

Almost always because it's trying to represent real repository history. Pick a representative 5-8 commit slice instead of a 50-commit history. The goal of a git graph in documentation is to communicate the workflow — what branches exist, how they merge, when releases happen — not to be a complete log of every commit. For gitflow documentation, three branches (main, develop, one feature) with five-to-seven commits and one or two merges is usually enough to show the pattern. Add more only if specific commits are needed to illustrate edge cases.

Diagram type

Mermaid Git Graph Syntax & Examples

Reference for Mermaid gitGraph syntax — commit, branch, checkout, merge, and tag operations. Copy-paste examples for gitflow, trunk-based, and release branching strategies.

Syntax reference, layout guidance, and ready-to-open examples for this diagram type.

At a glance

A syntax reference for Mermaid's gitGraph grammar — read this when you need the exact way to declare a commit, switch branches, merge with a tag, or pick a different layout orientation.

What is a Mermaid git graphBasic syntax — gitGraph + commit + branchCommit labels & typesMerges & cherry-picksOrientation — LR for horizontal layoutsCommon patterns & gotchas

Syntax reference

Mermaid gitGraph constructs, one per row

Construct	Syntax	Notes
Diagram keyword	`gitGraph`	First line. Append a direction to change the axis: `gitGraph LR:` or `gitGraph TB:`. Work starts on a branch called `main`.
Commit	`commit`	Lands on whichever branch is currently checked out. Without an id it is auto-numbered `c1`, `c2`, and so on.
Named commit	`commit id: "Normal"`	The id doubles as the visible label, so give it something readable.
Tagged commit	`commit id: "R" tag: "v1.0.0"`	`tag:` renders as a release marker and can be combined with `id:` and `type:` on the same line.
Commit type	`commit type: HIGHLIGHT`	`NORMAL` (the default), `HIGHLIGHT` and `REVERSE`.
Branch	`branch develop`	Creates the branch from the current commit but does not move onto it — you still need to check it out.
Switch branch	`checkout develop`	`switch develop` is accepted as an alias.
Merge	`merge develop tag: "v2.0.0"`	Merges the named branch into the branch you are currently on. Accepts `id:` and `tag:` like a commit.
Cherry-pick	`cherry-pick id: "B"`	Copies a commit from another branch onto the current one; the id must match an existing commit.

Syntax reviewed 9 August 2026

Rendered proof

Simple gitflow-like branching example.

Theme · Atlas

Open this diagram in editor

View Mermaid sourcePlain-text diagram syntax — copy or edit directly.

diagram.mmd

1gitGraph
2  commit id: "init"
3  branch develop
4  checkout develop
5  commit id: "feature A"
6  branch feature/login
7  checkout feature/login
8  commit id: "login scaffold"
9  commit id: "login tests"
10  checkout develop
11  merge feature/login
12  checkout main
13  merge develop tag: "v1.0.0"

Open in editor with this template

What is a Mermaid git graph

A git graph is a visualisation of a git branching workflow — commits, branches, merges, and tags rendered as nodes and lines. It is the right shape when the question is what-does-our-branching-strategy-look-like: onboarding documentation explaining gitflow, contributing guides showing the expected branch model, release-process documentation showing how main / develop / feature branches interact. A small git graph at the top of a CONTRIBUTING.md replaces multiple paragraphs of prose with one scannable visual. The diagram doesn't show real commits from a repository — it's an illustrative model showing what the workflow looks like, not what actually happened.

Basic syntax — gitGraph + commit + branch

Every git graph starts with gitGraph. The most basic operation is commit — adds a commit to the current branch. commit id: "label" gives the commit an explicit name; without it Mermaid generates a hash-like id automatically. branch <name> creates a new branch and switches to it. checkout <name> switches to an existing branch. merge <name> merges the named branch into the current one. These four primitives — commit, branch, checkout, merge — cover the vast majority of real git graphs. Commits accumulate on whatever branch is currently checked out, just like in real git.

gitGraph — diagram type keyword (always first)
commit — adds a commit to the current branch
branch <name> — create new branch and switch to it
checkout <name> — switch to existing branch
merge <name> — merge named branch into current

Commit labels & types

The commit operation accepts several modifiers. commit id: "name" sets an explicit commit id (recommended for readability). commit tag: "v1.0.0" adds a release tag. commit type: HIGHLIGHT flags a notable commit with distinct styling. commit type: REVERSE shows a revert. The three commit types — NORMAL (default), REVERSE, HIGHLIGHT — are useful for distinguishing routine work from significant events on the same branch. Tags appear as labels attached to the commit node and are typically used to mark releases.

commit id: "name" — explicit commit id (recommended)
commit tag: "v1.0.0" — adds a release tag
commit type: HIGHLIGHT — visually emphasises this commit
commit type: REVERSE — shows a revert

Merges & cherry-picks

merge <branch> performs the most common merge — bring another branch's history into the current one. Add merge <branch> id: "merge-id" to label the merge commit, or merge <branch> tag: "v2.0.0" to tag it as a release point. Mermaid also supports cherry-picks via cherry-pick id: "commit-id", which brings a single commit from another branch into the current branch without merging the whole history. Cherry-picks are particularly useful in release-branch workflows where a hotfix on main needs to be propagated to an older release branch.

Orientation — `LR` for horizontal layouts

By default git graphs render vertically (top-down), with branches as horizontal swim lanes. For wide documentation surfaces — onboarding pages, README files, slide decks — horizontal orientation often reads better. Add LR after gitGraph: gitGraph LR: to flip to left-to-right layout. The same commit / branch / merge syntax works in both orientations; only the rendered direction changes. For most CONTRIBUTING docs that show a typical gitflow, vertical (the default) reads naturally because branches appear stacked.

Common patterns & gotchas

Three patterns dominate real git graphs. Gitflow (feature → develop → release → main with hotfix branches) is the most common — needs at least three branches and several merges to communicate the strategy. Trunk-based development is simpler — most commits land directly on main with short-lived feature branches that merge back quickly. Release-branch workflows show main + release branches per version with cherry-picks for backports. The most common gotcha: forgetting that checkout only switches branches, it doesn't create them — use branch <name> first if the branch doesn't exist. Second gotcha: representing realistic repository history makes the graph unreadable — pick a representative 5-8 commit slice instead of a 50-commit history.

checkout switches to an existing branch — use branch first to create new ones
Keep commits to a representative slice (5-8); real history clutters
Tag releases on merge commits: merge develop tag: "v1.0.0"