Basic git graph example
gitGraph
commit id: "init"
branch develop
checkout develop
commit id: "feature A"
branch feature/login
checkout feature/login
commit id: "login form"
commit id: "validation"
checkout develop
merge feature/login
checkout main
merge develop tag: "v1.0.0"
branch hotfix
checkout hotfix
commit id: "fix crash"
checkout main
merge hotfix tag: "v1.0.1"Mermaid git graphs draw commit history as a branching diagram. You write Git-like commands — commit, branch, checkout, merge — and get a clear picture of how work flows between branches.
They're the best way to explain a branching strategy such as GitFlow or trunk-based development in contributor guides, or to illustrate what a rebase or cherry-pick does.
When to use a git graph
- Documenting branching strategies in CONTRIBUTING.md
- Teaching Git concepts
- Explaining release and hotfix processes
- Post-mortems of merge mistakes
Git Graph syntax reference
| Syntax | What it does |
|---|---|
gitGraph | Start a git graph (default branch is main). |
commit / commit id: "x" | Add a commit, optionally with a custom id. |
commit type: HIGHLIGHT | REVERSE | Special commit styles. |
commit tag: "v1.0" | Tag a commit. |
branch name | Create a branch and switch to it. |
checkout name / switch name | Switch to an existing branch. |
merge name | Merge a branch into the current branch. |
cherry-pick id: "x" | Cherry-pick a commit by id. |
Git Graph examples
Trunk-based development
Short-lived branches merged quickly back into main.
gitGraph
commit
branch feat-a
commit
checkout main
merge feat-a
branch feat-b
commit
commit
checkout main
merge feat-b tag: "release"Branches, commits, and merges are already a language. A mermaid git graph borrows that language and draws the history, which is why it belongs in a contributor guide. It's not a general process diagram that happens to use the word branch. The commands below are the ones that stay predictable.
What branch and checkout do
The first commit lands on main. That's the default branch in current Mermaid. master doesn't exist until you create it, and checkout master fails with a message that tells you to use branch.
branch feature creates the branch and switches to it. The next commit is on feature, not on main. That's the surprise if you're thinking of command-line Git, where git branch feature creates a branch and leaves you where you were. In this diagram, branch includes the checkout.
checkout main moves back. merge feature merges feature into whatever branch you're on. If you're still on feature, the merge fails, because a branch can't merge into itself. The fix is to checkout the destination first.
You don't need a commit id for a teaching diagram. Add id: "login" when a later cherry-pick or a review comment needs a name. Quote ids that contain spaces. Tags are optional and easy to overuse. One tag on the release commit is enough.
Worked example
Main has a starting commit. Work happens on feature. Main then takes that work.
gitGraph
commit
branch feature
checkout feature
commit
checkout main
merge featureThe first commit is the root on main. branch feature opens the line and moves you onto it, and the explicit checkout feature makes that move obvious to a reader who knows command-line Git. The second commit is the feature work. checkout main is the step people skip, and it's the one that makes merge feature legal. The merge commit appears on main. Feature doesn't disappear from the drawing. The history still shows where the work came from.
If you need a second feature, branch it from main after you have checked main out. Branching while you're still on feature forks from the feature tip, which is what you want for a stack and not what you want for two independent changes. Say the base out loud before you write branch.
A hotfix is the same pattern with a different name. Branch from main, commit, return to main, merge. If the diagram is a policy, two branches are plenty. A picture of the real repo, with twenty branches, is a git log screenshot. When you teach this to people who use command-line Git every day, say out loud that branch also checks the new branch out. That one sentence prevents the "why is my commit on the feature line" question in review.
When this is the wrong diagram
A flowchart is the better picture of a release policy that's about approvals rather than commits. A timeline is the better picture of versions over years when you don't care which branch they came from. Use a git graph when the lesson is the topology of main, a feature branch, and the merge.
Common mistakes
checkout masteron a diagram that never created master. The default branch is main. Create a branch withbranchbefore you check it out.merge featurewhile the current branch is feature. Mermaid reports that you can't merge a branch into itself.checkout mainfirst.- Thinking
branch featureleaves you on main. It switches. The next commit belongs to feature until you checkout main again. - A commit id with spaces and no quotes. Use
commit id: "add login"or skip the id.
Where to go next
The AI git graph generator can turn a branching policy into commands. Step through checkout and merge in the editor, and the cheat sheet lists those commands. The git flow template adds a develop branch and a release if this main-and-feature picture is too small.
Match a real branch
Commit ids in a git graph are labels, not SHAs you must copy from git log. The order is the part that has to be true. If main merged feature on Tuesday, the merge commit sits on main after that branch, not the other way around. A chart that shows the feature branch merging main will teach the wrong history to the next person who reads the README.
Tags belong on the commit you actually tagged. Drawing v1 on the commit before the release, because it looked less crowded, is how release notes drift. The git graph syntax is this page, and the GitFlow template is a fuller picture if you need develop as well as main.
Tips and best practices
- Give important commits ids so they can be referenced by cherry-pick and read easily.
- Use tags for releases to show where versions were cut.
- Configure orientation with an init directive (gitGraph LR: or TB:) for long histories.
Generate a git graph with AI
Not sure where to start? Describe what you need and the AI git graph generator writes the Mermaid code for you. Try prompts like:
- “GitFlow with release and hotfix branches”
- “Feature branch with rebase onto main”
- “Monorepo release train”
Git Graph templates
Git Graph FAQ
Can Mermaid git graphs show cherry-picks?
Yes. Give the source commit an id and use cherry-pick id: "that-id" on the target branch.
How do I rename the main branch?
Set mainBranchName in the gitGraph configuration through an init directive, for example %%{init: {'gitGraph': {'mainBranchName': 'trunk'}}}%%.