🌿 Mermaid

Git graph

Explain branching strategies visually

Open this example in the editor Generate one with AI

What is a Git graph?

A git graph shows commits, branches, merges and tags. It is the clearest way to document your branching strategy — git flow, trunk-based, release trains — for the whole team.

A git graph is teaching material: it belongs in CONTRIBUTING.md, in the onboarding guide, in the argument about whether to squash. It is the one diagram whose syntax mirrors the commands the reader will type, which makes it easy to check. It has no connection to your repository, though — it shows the branching model you intend, never the history you actually have. It has no notion of a remote, so a fork has to be drawn as an ordinary branch.

Live example

Mermaid code

gitGraph
    commit id: "init"
    branch develop
    commit id: "setup CI"
    branch feature/auth
    commit id: "login page"
    commit id: "JWT"
    checkout develop
    merge feature/auth tag: "v0.2.0"
    checkout main
    merge develop tag: "v1.0.0"

Live example

When to use it

Document your team’s branching and release strategy

Onboard developers with visual git conventions

Explain hotfix and release procedures

Common mistakes

branch also checks out

After branch develop, every following commit lands on develop rather than main. People add commits expecting them on the trunk and then wonder why its lane is empty — write checkout main first if that is what you meant.

The trunk is called main

checkout master fails with “Trying to checkout branch which is not yet created”. Rename the default with an init directive setting gitGraph.mainBranchName to master on the first line of the diagram.

cherry-pick needs another branch

The source commit must exist, must carry the id you reference, and must sit on a different branch. Cherry-picking from the current branch fails with “Source commit is already on current branch”.

Basic syntax

.mmd

gitGraph
    commit
    branch develop
    commit
    checkout main
    merge develop

gitGraph TB:
The default layout runs left to right. Adding TB: turns the graph vertical, which fits a long release history into a documentation page far better.
commit id: "hotfix" type: HIGHLIGHT tag: "v1.0.1"
A commit takes an id you can reference later, a type of NORMAL, REVERSE or HIGHLIGHT, and a tag drawn as a release label on the lane.
branch develop order: 2 commit
branch creates the branch and checks it out in one step. The order attribute fixes the vertical position of the lane, so main stays where readers expect it.
cherry-pick id: "fix-npe"
Cherry-pick copies one commit onto the current branch — the way to show a hotfix backported to a release line without redrawing the whole branch.

Questions about this diagram

Can I show tags and releases?

Yes — commits and merges accept a tag: attribute (e.g. tag: "v1.0.0"), perfect for documenting release points.

Which branching strategies can it represent?

Any: git flow, GitHub flow, trunk-based development, release branches — the syntax mirrors real git operations (branch, checkout, merge, cherry-pick).

Can I put a git graph in CONTRIBUTING.md on GitHub?

Yes — a fenced block tagged mermaid renders in the file view on GitHub and GitLab. That is its natural home: the branching rules and the picture of them change in the same commit and the same review. Reviewers get a diff, not a new screenshot.

Does the git graph read my actual repository?

No. It is written by hand and knows nothing about your repo, so it will not drift with your history — and it will not warn you when it becomes wrong. Treat it as a model of the branching strategy, not a log.

How do I show a rebase or a revert?

There is no rebase keyword, so draw the result instead: the commits redrawn on the target branch. A revert is commit type: REVERSE, which renders the commit crossed out on its lane so the reader sees it was undone.

Can a git graph show dates or a release schedule?

No. Commits are ordered but carry no timestamps and there is no axis. Pair the graph with a timeline for release dates, or with a Gantt chart when the release train has durations and dependencies worth planning.

Git graph or another diagram type?

Git graph or timeline?

Both are chronological. A git graph is chronological and branching: it shows work happening on parallel lines and coming back together. A timeline is chronological and flat. If the point is that two streams diverged, only the git graph makes that visible.

Git graph or flowchart?

Use a git graph to show what the history looks like, and a flowchart to show what a developer should do. “Branch from main, open a PR, squash-merge” is a procedure with decisions in it, which is a flowchart illustrated by a git graph.

Explore other diagram types

🔀 Flowchart 💬 Sequence diagram 🧩 Class diagram 🗄️ Entity-relationship diagram 🔄 State diagram 📅 Gantt chart 🥧 Pie chart 🧠 Mind map 🕰️ Timeline 🚶 User journey 🎯 Quadrant chart

Create your Git graph now

Describe it in plain language — the AI writes the Mermaid code for you.

Open Mermaid Studio