Mermaid gitGraph Tutorial: Visualize Git Branching and Merges from Text
Explaining a branching strategy in words is painful; Mermaid's gitGraph draws the commits, branches, and merges from a few readable commands.
Git branching strategies are notoriously hard to explain in prose - "we branch off develop, then merge back after review, but hotfixes come off main" collapses into confusion the moment there are more than two branches. A picture of the commit graph makes it obvious, but drawing that picture by hand and keeping it current is tedious. Mermaid's gitGraph solves this by letting you describe the history as a short sequence of commands that mirror the git operations themselves: commit, branch, checkout, merge.
This tutorial covers the gitGraph commands and how they compose into a clear branching diagram, with snippets you can drop straight into the Mermaid editor at /diagram-tools/mermaid-editor. The rendered graph lives as an editable diagram in Atlas Diagram Studio at /diagrams, ideal for onboarding docs and RFCs that explain a workflow. If you would rather describe your branching model in plain English, the AI diagram generator at /diagram-tools/ai-diagram-generator can produce a first draft you then adjust.
The core commands
A gitGraph opens with the keyword "gitGraph" and then reads a list of operations, one per line, executed in order just like a real git session. You begin implicitly on the "main" branch, and "commit" adds a node to the current branch. The mental model is exactly git: you are on a branch, you commit to it, you create and switch branches, and you merge them back. Because the commands map one to one onto git verbs, the source doubles as documentation of the workflow it depicts.
Commits can be plain or labeled. Writing "commit" alone adds an anonymous commit, while 'commit id: "fix bug"' gives it a visible label, and you can tag a commit or mark its type. Branches are created with "branch featureX", which also switches you onto the new branch, and you move between existing branches with "checkout main". Merging is a single command, "merge featureX", which draws the merge back into whatever branch you are currently on.
Branches, merges, and cherry-picks
The real value shows when you compose these into a realistic flow. The bullets below list the commands you will use to model anything from a simple feature branch to a full git-flow with releases and hotfixes.
- "commit" adds a commit to the current branch; add 'id: "message"' to label it.
- "commit type: HIGHLIGHT" (or "NORMAL", "REVERSE") changes how the commit dot is drawn.
- 'commit tag: "v1.0.0"' attaches a release tag balloon to the commit.
- "branch develop" creates a new branch and switches to it in one step.
- "checkout develop" switches to an existing branch so subsequent commits land there.
- "merge develop" merges the named branch into the current branch, drawing the merge commit.
- 'cherry-pick id: "abc123"' copies a specific commit from another branch onto the current one.
Orientation and configuration
By default a gitGraph runs left to right along the horizontal, which reads like a familiar commit history. You can flip it to a top-to-bottom orientation with "gitGraph TB:" when a vertical layout fits your page better, or use "gitGraph BT:" for bottom-to-top. Branch ordering and colors follow a theme, and you can override the branch color order through the diagram configuration when you want a specific branch to stand out.
Labels are worth a moment of care because a gitGraph is usually there to teach. Give the commits that anchor the story an "id" so a reader can point at "the release commit" or "where the hotfix branched," and tag the commits that represent releases. A graph with a few well-chosen labels communicates a branching strategy far better than one where every dot is anonymous, and the labels cost nothing to add in the source.
Where gitGraph earns its keep
The gitGraph is at its best in documentation that explains a workflow rather than a single moment in time: onboarding guides that teach the team's branching model, RFCs proposing a change to how releases are cut, or a blog post comparing git-flow with trunk-based development. It is not meant to mirror your live repository automatically - it is a teaching diagram you author to make a strategy legible, which is exactly why the text-based approach fits, since it versions alongside the docs it supports.
Because it is Mermaid, the same diagram embeds in a README, renders in the Mermaid editor at /diagram-tools/mermaid-editor, and opens for styling in Atlas Diagram Studio at /diagrams. For the wider set of software diagrams that pair well with it - sequence diagrams for API calls, C4 for architecture - the complete Mermaid guide at /guides/mermaid-js-complete-guide is the map, and the guide on generating diagrams from code at /guides/how-to-generate-diagrams-from-code covers keeping such diagrams honest over time.