How to Make a Git Graph with Mermaid Chart

A git graph is one of the more useful forms of diagrams for developers and DevOps professionals.

Git graphs provide a visual representation of the history and relationships between commits in a git repository. They offer valuable insights into the development process, allowing teams to track changes, understand branching and merging patterns and collaborate effectively.

While supremely useful, git graphs historically haven’t been very easy — or fun – to make. Mermaid Chart, the text-based diagramming platform built on top of Mermaid, is looking to change that.

In this post, we’ll dive into the git graph syntax within Mermaid, which allows users to render git graphs from simple code. The Mermaid Chart platform provides a great way to use Mermaid’s functionality - with a host of features to help you work efficiently and collaborate with colleagues. There’s no need to spend half your day in a GUI with Mermaid Chart. Plus, when you’re reviewing your proposals with colleagues later on, it’s easy to use Mermaid Chart to make changes to your git graphs based on their suggestions.

Let’s explore more about git graph syntax in Mermaid and show you how to use Mermaid Chart to make one.

What is a Git Graph? #

A git graph is a visual representation of git commits and git actions (aka commands) upon various branches within a Git repository. Git graphs are particularly helpful to developers and DevOps teams seeking to share their Git branching strategies.

A well-designed git graph assists with version control and release management in the development process.

What can I use a git graph for? #

Git graphs play a crucial role in the development and DevOps communities, providing a visual representation of the history and relationships between commits in a Git repository:

• Increasing clarity: Git graphs provide a clear visual representation of the branching structure of a repository, making it easier to understand the history of different branches and their relationships.

• Tracking changes and debugging: By examining a Git graph, developers can easily track changes made to the codebase over time. This helps in identifying when and where specific features, bug fixes, or enhancements were introduced.

• Facilitating collaboration: Git graphs facilitate collaboration by enabling team members to visualize and review each other’s work. They provide a shared understanding of the codebase, making it easier to identify potential conflicts or areas that require attention.

How to make a git graph with Mermaid Chart #

Mermaid’s gitgraph syntax is simple and declarative.

Commits are plotted chronologically. Start with the `gitGraph` keyword to specify the diagram type. By default, a gitgraph initializes with the main branch. Use the `commit` keyword to log a commit.

Here’s an example illustrating a bugfix. You can see how there are two commits on the main branch which by common convention often contain the latest code delivered. Then due to a bug, the code was branched to a bugfix branch where a bugfix was committed. Finally the bugfix was merged back into main and delivered.

The image of the git graph illustrates this flow clearly so that it is easy to understand. This basic example illustrates the main concept. Git can, however, do much more, and many of those operations can also be illustrated in a git graph. In the coming sections, we will look closer at some of them.

Commits #

The default for a commit in Mermaid and Mermaid Chart’s git graph is to produce a random id that looks similar to a read git commit hash. In the previous diagram, you can see how that default setting looks. Sometimes it can be helpful to set the commit to something readable as in the following fictive example:

We can see how the commits are described with some text instead of the random id. The syntax to achieve this with mermaid is straightforward, and in the following snippet you can see how we added `id: “label text”` after `commit` where label text is the actual string you want to add to the diagram.

gitGraph
commit id: "Fix for login issue"
commit id: "Added the forgotten file"
commit id: "Disabling the broken feature"

There are other ways to convey information regarding the commits in the diagram. You can have three types of commits, each with a distinct visual representation:

• NORMAL: The standard commit, shown as a solid circle.
• REVERSE: Denotes a reverse commit, depicted as a crossed circle.
• HIGHLIGHT: Emphasizes a commit, displayed as a filled rectangle.

To set a commit type, use the type attribute, as in `commit type: HIGHLIGHT`. If unspecified, the default is NORMAL. Here’s a diagram illustrating these commit types:

Here is the code for the diagram:

gitGraph
commit
commit id: "Normal"
commit id: "Reverse" type: REVERSE
commit id: "Highlight" type: HIGHLIGHT

Cherry-picking commits #

In git, cherry-picking involves selecting and applying a particular commit from one branch to a different branch. This capability is valuable, as it allows you to selectively transfer specific changes or modifications from one branch to another without merging the entire branch.

Mermaid visually represents this with the cherry-pick keyword. Use id: “your_custom_id” to specify the commit, creating a new visual commit marked by a cherry icon and the original id. Ensure the commit isn’t on the current branch, and there’s a preceding commit.

In the following example, someone has been committing a bugfix into the develop branch instead of the hotfix branch. The situation was resolved by cherry-picking the bugfix commit into the hotfix branch after which verification could continue and the hot fix was then delivered and merged into main.

With Mermaid and Mermaid Chart’s git graph, this is easy to visualize as in the previous diagram. The syntax is simple and mirrors how you would do the git operation in a repository as illustrated by the Mermaid code for the example:

gitGraph
commit id: "ZERO-0"
branch "hotfix"
commit
branch "develop"
commit id: "bugfix"
checkout hotfix
cherry-pick id:"bugfix"
checkout main
merge hotfix

The syntax for the cherry-pick is `cherry-pick: “id”` where id the is the id of the commit that was cherry-picked. Note: that you need to be on the destination branch, where the commit is to be picked. This is the reason for the `checkout` statement above the `cherry-pick` in the code. The branch statement in contrast creates a new branch. The branch handling can be summarized by:

• `checkout “branchname”`: This command selects the branch “branchname” for operations.
• `branch “branchname”`: creates a new branch named branchname. There will be an error if “branchname” already exists. (Then checkout should be used).

Tagging Commits #

Another useful function is illustrating tagged commits, mirroring git’s tagging or release versions. Use the tag attribute when declaring a commit, like: `commit tag: “the_tag”`. This is illustrated in the following diagram:

You can see how the tags are illustrated like small tags on top of the commit. The code for this is very similar to the syntax for ids. The only thing you need to do is to add `tag: “tag_text”` to the commit statement. Tags can also be combined with custom ids without problems. Here is the full code of the previous diagram:

gitGraph
  commit tag: "v1.0.0"
  commit id: "bugfix"
  commit tag: "v1.0.1" id: "Release v1.0.1"

Orientation #

Having gitGraphs going from left to right is great. This orientation is very readable — until there is no more space. Luckily we can switch the orientation and render the graph from top to bottom. The following diagram show how the previous diagram looks when tilted so that it renders from top to bottom:

Here is the code:

gitGraph TB:
commit tag: "v1.0.0"
commit id: "bugfix"
commit tag: "v1.0.1" id: "Release v1.0.1"

You can see that the only difference in the code is the addition of TB: to the graph statement.

Getting started with git graphs in Mermaid Chart #

Git graphs are an excellent tool for developers – but only if they’re easy to build and share. This is why we made the git graph available in Mermaid — and in Mermaid Chart, the text-based diagramming platform built on top of Mermaid.

Getting started is as easy as creating your free account!

For those looking for even more Mermaid Chart features, upgrading to our Pro plan gives you unlimited diagrams, team editing capabilities and many more features coming soon.

Mermaid Chart