Beauty Diagram
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.

Use this page to connect a high-intent search query to the right problem-solution narrative.

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
Rendered proof
Simple gitflow-like branching example.
Theme · Atlas
Open this diagram in editor
This example could not be rendered in the proof block. The source is still available below.
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"

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"`
FAQ

Mermaid Git Graph Syntax & Examples — frequently asked questions

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

Four primitives cover most needs. `commit` adds a commit to the current branch. `branch <name>` creates a new branch and switches to it. `checkout <name>` switches to an existing branch (does not create). `merge <name>` 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.