📚 Illustrating git Branching with Markdown and Mermaid.js

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!