Occasionally I find myself needing to write about git commands or workflows, either as I am educating new developers or as I am documenting a team's git strategies.
While graphical git tooling such as GitKraken can help with this if you have a practical example, sometimes its nice to have a nice and clean diagram of example commits.
In this article we'll explore how Mermaid.js can help you generate clean and minimalist git graphs using only markdown.
For those not familiar, Mermaid.js is an open-source JavaScript library that converts specialized markdown into diagrams on your page. It is fantastic and can do many diagrams including entity relationship diagrams, class diagrams, sequence diagrams, and more.
Mermaid.js integrates into GitHub, Visual Studio Code, Polyglot Notebooks, and others. Let's see how it handles git commits.
Displaying Basic Commits
At the most basic level, a git graph starts with a gitGraph element and then a series of commit statements.
gitGraph
commit
commit
commit
This creates a git timeline from left to right where the leftmost commit is the first one and the rightmost is the last one.
Notice that the names of each commit are randomly assigned and start with the 1-based index of the commit in the timeline followed by a dash and then the beginnings of a globally unique identifier.
If you want to customize the display of an individual commit, you can provide an id: node followed by the text to use in quotes.
Additionally, you can customize the theme of the graph via the %%{init statement by providing a value of base, forest, dark, default, or neutral. I happen to like base so the remainder of the graphs will feature that theme.
%%{init: { 'theme': 'base' } }%%
gitGraph
commit
commit id: "Fixed Issue #42"
commit
git Branching in Mermaid.js
Of course, a git graph without any sort of branching or merging is both boring and not generally helpful. Let's take a look at a simple graph involving two branches:
%%{init: { 'theme': 'base' } }%%
gitGraph
commit
commit
branch feature
commit
Here all commits start on the main branch and then diverge onto the feature branch after the branch feature statement.
If you want to switch back to another branch without creating a new branch, you can do so with checkout branchname.
Finally, if you want to illustrate merging a branch into another, first checkout the target branch and then use merge branchname to indicate that the second branch was merged into your current branch.
%%{init: { 'theme': 'base' } }%%
gitGraph
commit
commit
branch feature
commit id: "Dark Theme"
checkout main
merge feature
commit
Using branch, checkout, and merge strategically, you can quickly create complex git situations to help illustrate real-world usage scenarios.
%%{init: { 'theme': 'base' } }%%
gitGraph
commit
branch feature
checkout main
commit
branch bugfix
commit
checkout feature
commit id: "Dark Theme"
checkout main
merge feature
commit
checkout bugfix
commit id: "Fixed Null Ref"
checkout main
merge bugfix
commit
Annotating git Commits in Mermaid.js
While commit, branch, checkout, and merge are all you need for basic diagrams, sometimes you can benefit from highlighting certain commits with tag names or symbols.
First, any commit can be annotated with a tag by specifying tag: and then the name of the tag in quotes. This can be combined with id: if desired.
%%{init: { 'theme': 'base' } }%%
gitGraph
commit tag: "v0.4.0"
branch feature
checkout main
commit
branch bugfix
commit
checkout feature
commit id: "Dark Theme"
checkout main
merge feature
commit tag: "v0.4.1"
commit
checkout bugfix
commit id: "Fixed Null Ref"
checkout main
merge bugfix tag: "v0.4.2"
commit
Secondly, each commit has a type: associated with it. By default this is the NORMAL type, but you can also specify type: REVERSE to indicate a commit with an X through it or type: HIGHLIGHT to use a square instead of a circle. Note that the type: attributes do not use quotes while the id: and tag: attributes do.
%%{init: { 'theme': 'base' } }%%
gitGraph
commit tag: "v0.4.0"
branch feature
checkout main
commit
branch bugfix
commit id: "Whoopsies" type: REVERSE
checkout feature
commit id: "Dark Theme"
checkout main
merge feature
commit tag: "v0.4.1"
commit type: HIGHLIGHT
checkout bugfix
commit id: "Fixed Null Ref"
checkout main
merge bugfix tag: "v0.4.2"
Closing Thoughts
I'm personally a huge fan of using Mermaid.js to generate git graphs. The syntax resembles the appropriate git commands for working with branching and the resulting graphs are attractive, simple, and help convey git concepts to new team members.
I personally plan on using Mermaid.js graphs going forward for any git related articles or documentation.
Stay tuned for more articles on Mermaid.js and the awesome things you can build with it!
