Illustrating git Branching with Markdown and Mermaid.js
Tags: mermaid, git, github, documentation
Published: 2023-04-12 03:48:44

---
title: Illustrating git Branching with Markdown and Mermaid.js
published: true
description: Mermaid.js git graphs help you easily explain git concepts in simple markdown. Let's take a look at how they work and what you can do with them.
tags: Mermaid, Git, GitHub, Documentation
series: Mermaid.js
canonical_url: https://newdevsguide.com/2023/04/11/illustrating-git-branching-with-markdown-mermaid-js/
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/px3frs7gn5shm67l92hy.png
# Use a ratio of 100:42 for best results.
# published_at: 2023-04-12 03:40 +0000
---

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](http://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](https://newdevsguide.com/2023/04/08/creating-erds-with-mermaid/), [class diagrams](https://newdevsguide.com/2023/04/08/mermaid-class-diagrams/), [sequence diagrams](https://newdevsguide.com/2023/04/10/mermaid-sequence-diagrams/), and more.

Mermaid.js integrates into GitHub, Visual Studio Code, [Polyglot Notebooks](https://newdevsguide.com/2022/12/14/polyglot-notebooks-csharp/), 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
```

![Git Graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pq9e9tif5xzbc9eoqtqf.png)

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 Graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qmon0gwpy1ynnvw4b617.png)

## 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
```
![Git Graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4s7n0kvs5r5y8e2noplu.png)

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
```
![Git Graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3jmybs58riskyv0b1gap.png)

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
```
![Git Graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/h13fefpe49wrmkiyvqu5.png)

## 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
```
![Git Graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/02m6hk5aegnmkk3iim2g.png)

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"
```
![Git Graph](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/657sqwg37lsz8fwzs4wx.png)

## 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!