← All diagram types

Mermaid gitGraph syntax: commits, branches and merges with examples

Mermaid gitGraph syntax with rendered examples: commits with ids and tags, branching and checkout, merges, and commit types for release history.

A gitGraph draws branch history the way a git client does: commits as dots on coloured lanes, branches as columns, and merges as lines between them. Mermaid's gitGraph is written as the commands you would type, in order.

Everything on this page is rendered by makesPDF's own Mermaid renderer, so a ```mermaid block produces exactly this in the PDF.

Commits

commit appends one commit to the current branch. The first commit after the header sits on main; each one is placed below the last:

mermaid
gitGraph
  commit id: "a1b2c3d" msg: "Scaffold the API"
  commit id: "e4f5a6b" msg: "Add render endpoint"
  commit id: "c7d8e9f" msg: "Fix font subset"
Render this to PDF →How diagram blocks work

Ids, messages and tags

commit takes three optional fields: id: (the short hash), msg: (the subject line) and tag: (a release label, drawn as a pill):

mermaid
gitGraph
  commit id: "a1b2c3d" msg: "Initial commit" tag: "v1.0"
  commit id: "e4f5a6b" msg: "Add render endpoint"
  commit id: "c7d8e9f" msg: "Fix font subset" tag: "v1.1"
Render this to PDF →How diagram blocks work

Branching

branch <name> creates a branch at the current commit, and checkout <name> moves the head so later commits land on it:

mermaid
gitGraph
  commit id: "init"
  branch develop
  checkout develop
  commit id: "feat-1"
  commit id: "feat-2"
Render this to PDF →How diagram blocks work

Merging

merge <name> joins a branch back into the one you have checked out, drawing the connector and a merge commit:

mermaid
gitGraph
  commit id: "init"
  branch feature
  checkout feature
  commit id: "wip"
  commit id: "done"
  checkout main
  commit id: "hotfix"
  merge feature
Render this to PDF →How diagram blocks work

Release history

type: on a commit or merge picks its marker: NORMAL (a filled dot), REVERSE (a hollow dot with a red ring) and HIGHLIGHT (a filled dot with a dark ring). Mixing the types makes important points stand out:

mermaid
gitGraph
  commit id: "init" type: NORMAL
  commit id: "spike" type: HIGHLIGHT
  branch release
  checkout release
  commit id: "cut" type: REVERSE
  checkout main
  merge release type: HIGHLIGHT
Render this to PDF →How diagram blocks work

branch <name> order: <n> fixes a lane's column instead of assigning the next free one.

Not supported in makesPDF yet: the orientation suffix (gitGraph LR: or gitGraph BT:) is parsed but ignored — history is always drawn top-down. Branch names are drawn at the top of their lane on one line, so short names read best. A cherry-pick connector is drawn as a dashed cross-lane line; its parent: field is parsed but not used.