Register
Process Type
Graphical expression
Mind Type
Structured expression
Note Type
Efficient expression

Git diagramSyntax

Git diagram

A Git graph is a visual representation of git commits and git operations on different branches.

Git graphs are especially helpful for developers and operations teams and can be used to share their Git branching strategy.

Mermaid can render Git graphs

Code
                            
Copy
Embed
--- title: Example Git diagram --- gitGraph commit commit branch develop checkout develop commit commit checkout main merge develop commit commit

Mermaid supports basic git operations, such as:

  • commit : represents a new commit on the current branch.
  • branch : creates and switches to a new branch and sets it as the current branch.
  • checkout : switches to an existing branch and sets it as the current branch.
  • merge : merges an existing branch into the current branch.

With these Git operations, you can very easily and quickly draw Git graphs in Mermaid. Entity names usually start with an uppercase letter, although there is no accepted standard for this and it is not required in Mermaid.

Note: checkout and switch can be used interchangeably.

Syntax

The Mermaid syntax for Git graphs is very direct and simple. It takes a declarative approach, and each commit is drawn on the Git graph timeline in the order it appears in the code. Basically, it follows the insertion order of each command.

First, declare your diagram type using the gitGraph syntax. The gitGraph syntax tells Mermaid that you want to draw a Git graph and parses the diagram code accordingly.

Every Git graph is initialized with a main branch. Unless you create a different branch, commits go to the main branch by default. This is driven by the way git works: at the beginning you always start from the main branch. By default, the main branch is set as the current branch.

You can use the commit syntax to register a commit on the current branch; let's see how this works:

A simple git graph showing three commits on the default branch main:

Code
                            
Copy
Embed
gitGraph commit commit commit

If you look carefully at the previous example, you can see the default branch main along with three commits. Also note that by default, each commit is given a unique and random ID.

Adding a custom commit ID

For a given commit, you can specify a custom ID using the id property when declaring it, followed by a colon :, with the custom value in double quotes.

Let's see how it works with the help of the diagram below:

Code
                            
Copy
Embed
gitGraph commit id: "Alpha" commit id: "Beta" commit id: "Gamma"

在此示例中,我们给提交分配了自定义 ID。

Changing the commit type

In Mermaid, there are three types of commits, which are rendered slightly differently in the diagram. These types are:

  • NORMAL : the default commit type, represented by a solid circle
  • REVERSE : emphasizes that the commit is a reverse commit, represented by a crossed solid circle.
  • HIGHLIGHT : highlights a specific commit, represented by a solid rectangle.

For a given commit, you can specify its type using the type property when declaring it, followed by a colon : and the desired type option discussed above. For example: commit type:

Note: if the commit type is not specified, NORMAL is selected by default

Let's look at the diagram below to see how these different types of commits are made:

Code
                            
Copy
Embed
gitGraph commit id: "Normal" commit commit id: "Reverse" type: REVERSE commit commit id: "Highlight" type: HIGHLIGHT commit

In this example, we specified a different type for each commit. Also, see how we included both id and type when declaring the commits.

Adding a tag

For a given commit, you can decorate it with tag, similar to the concept of a tag or release in the git world. You can attach a custom tag using the tag property when declaring the commit, followed by a colon :, with the custom value in double quotes.

Code
                            
Copy
Embed
gitGraph commit commit id: "Normal" tag: "v1.0.0" commit commit id: "Reverse" type: REVERSE tag: "RC_1" commit commit id: "Highlight" type: HIGHLIGHT tag: "8.8.4" commit

In this example, we set a custom tag for a commit.

Creating a new branch

In Mermaid, to create a new branch, you can use the branch syntax. You also need to provide the name of the new branch. The name must be unique and cannot be the name of an existing branch.

When Mermaid reads the branch syntax, it creates a new branch and sets it as the current branch. This is equivalent to creating a new branch in a Git graph and switching to it.

Code
                            
Copy
Embed
gitGraph commit commit branch develop commit commit commit

In this example, you can see how we started from the default main branch and pushed two commits onto it. We then created the develop branch, and all subsequent commits were placed on the develop branch because it became the current branch.

Checking out an existing branch

In Mermaid, to switch to an existing branch, you can use the checkout syntax, and you also need to provide the name of the existing branch. If no branch with the specified name is found, it will cause a console error. Example usage: checkout develop

When Mermaid reads the checkout syntax, it finds the branch with the specified name and sets it as the current branch. This is equivalent to checking out a branch in Git.

Code
                            
Copy
Embed
gitGraph commit commit branch develop commit commit commit checkout main commit commit

In this example, we first started from the default main branch and pushed two commits onto it. We then created the develop branch, after which all three commits were placed on the develop branch because it became the current branch. Afterwards, we used the checkout syntax to set the current branch to main, and all subsequent commits were recorded on the main branch.

Merging two branches

In Mermaid, to merge or connect to an existing branch, you need to use the merge syntax. You also need to provide the name of an existing branch to merge. If no branch with the specified name is found, an error will be shown in the console. In addition, you can only merge two separate branches; you cannot merge a branch with itself.

Syntax example: merge develop

When Mermaid reads the merge syntax, it finds the specified branch and its last commit and merges it with the last commit of the current branch. It is represented by a solid double circle.

The following is an example of merging two branches:

Code
                            
Copy
Embed
gitGraph commit commit branch develop commit commit commit checkout main commit commit merge develop commit commit

In this example, we first started from the main branch and pushed two commits onto it. We then created the develop branch and pushed three commits onto it. Afterwards, we used the checkout syntax to set the current branch to main, and all subsequent commits were made against the main branch. Finally, we merged the develop branch into the main branch, producing a merge commit. Since the current branch was still main at that point, the last two commits were both recorded on that branch.

You can also add similar attributes to your merge:

  • id overrides the default ID with a custom ID
  • tag adds a custom tag to the merge commit
  • type overrides the default type of the merge commit. You can use the other commit types mentioned earlier.
Code
                            
Copy
Embed
gitGraph commit id: "1" commit id: "2" branch nice_feature checkout nice_feature commit id: "3" checkout main commit id: "4" checkout nice_feature branch very_nice_feature checkout very_nice_feature commit id: "5" checkout main commit id: "6" checkout nice_feature commit id: "7" checkout main merge nice_feature id: "customID" tag: "customTag" type: REVERSE checkout very_nice_feature commit id: "8" checkout main commit id: "9"

Selectively merging commits from another branch

Mermaid supports cherry-picking a commit from another branch to the current branch. You can also use the cherry-pick syntax to cherry-pick a commit from another branch.

To use the cherry-pick syntax, you must specify an id using the id property, then write the desired commit id after a colon :, enclosed in double quotes. For example:

Here are some important rules to note:

  • You need to provide an id in order to select an existing commit. If the given commit ID does not exist, it will cause an error. To do this, use the format commit id:$value to declare the commit.
  • The given commit must not exist on the current branch; the cherry-picked commit must always come from a branch different from the current branch.
  • The current branch must have at least one commit before a cherry-pick can be performed, otherwise it will cause an error.
  • When cherry-picking a merge commit, a parent commit ID must be provided. If the parent property is omitted or an invalid parent commit ID is provided, an error will be raised.
  • The specified parent commit must be the direct parent of the merge commit being cherry-picked.
Code
                            
Copy
Embed
gitGraph commit id: "ZERO" branch develop branch release commit id:"A" checkout main commit id:"ONE" checkout develop commit id:"B" checkout main merge develop id:"MERGE" commit id:"TWO" checkout release cherry-pick id:"MERGE" parent:"B" commit id:"THREE" checkout develop commit id:"C"

Specific config options

In a Mermaid Git graph you can configure the following options:

  • showBranches : Boolean, defaults to true. If set to false, branches are not displayed.
  • showCommitLabel : Boolean, defaults to true. If set to false, commit labels are not displayed.
  • mainBranchName : String, defaults to main. The name of the default branch.
  • mainBranchOrder : the position of the main branch in the branch list. Defaults to 0, which means that by default the main branch is in position 1.
  • parallelCommits : Boolean, defaults to false. If set to true, commits that are distant from the parent will be displayed on the same level.

Hiding branch names and connecting lines

Sometimes you may want to hide branch names and connecting lines. You can do this using the showBranches syntax. By default its value is true, and you can use a directive to set it to false.

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' gitGraph: showBranches: false --- gitGraph commit branch hotfix checkout hotfix commit branch develop checkout develop commit id:"ash" tag:"abc" branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix commit type:NORMAL checkout develop commit type:REVERSE checkout featureB commit checkout main merge hotfix checkout featureB commit checkout develop branch featureA commit checkout develop merge hotfix checkout featureA commit checkout featureB commit checkout develop merge featureA branch release checkout release commit checkout main commit checkout release merge main checkout develop merge release

Commit label layout: rotate or horizontal

Mermaid supports two types of commit label layout. The default layout is rotated, which means the label is placed below the commit circle and rotated 45 degrees for better readability. This is especially useful for commits with long labels.

Another type is horizontal, which means the label is placed below the commit circle and horizontally centered, without rotation. This is especially useful for commits with short labels.

You can change the layout of commit labels by using the rotateCommitLabel syntax in a directive. It defaults to true, which means commit labels are rotated.

Example usage: rotated commit labels

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' gitGraph: rotateCommitLabel: true --- gitGraph commit id: "feat(api): ..." commit id: "a" commit id: "b" commit id: "fix(client): .extra long label.." branch c2 commit id: "feat(modules): ..." commit id: "test(client): ..." checkout main commit id: "fix(api): ..." commit id: "ci: ..." branch b1 commit branch b2 commit

Example usage: horizontal commit labels

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' gitGraph: rotateCommitLabel: false --- gitGraph commit id: "feat(api): ..." commit id: "a" commit id: "b" commit id: "fix(client): .extra long label.." branch c2 commit id: "feat(modules): ..." commit id: "test(client): ..." checkout main commit id: "fix(api): ..." commit id: "ci: ..." branch b1 commit branch b2 commit

Hiding commit labels

Sometimes you may want to hide commit labels. You can do this using the showCommitLabel syntax. By default its value is true, and you can use a directive to set it to false.

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' gitGraph: showBranches: false showCommitLabel: false --- gitGraph commit branch hotfix checkout hotfix commit branch develop checkout develop commit id:"ash" branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix commit type:NORMAL checkout develop commit type:REVERSE checkout featureB commit checkout main merge hotfix checkout featureB commit checkout develop branch featureA commit checkout develop merge hotfix checkout featureA commit checkout featureB commit checkout develop merge featureA branch release checkout release commit checkout main commit checkout release merge main checkout develop merge release

Customizing the main branch name

Sometimes you may want to customize the name of the main branch. You can do this using the mainBranchName syntax. By default its value is main, and you can use a directive to set it to any string.

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' gitGraph: showBranches: true showCommitLabel: true mainBranchName: 'MetroLine1' --- gitGraph commit id:"NewYork" commit id:"Dallas" branch MetroLine2 commit id:"LosAngeles" commit id:"Chicago" commit id:"Houston" branch MetroLine3 commit id:"Phoenix" commit type: HIGHLIGHT id:"Denver" commit id:"Boston" checkout MetroLine1 commit id:"Atlanta" merge MetroLine3 commit id:"Miami" commit id:"Washington" merge MetroLine2 tag:"MY JUNCTION" commit id:"Boston" commit id:"Detroit" commit type:REVERSE id:"SanFrancisco"

Take a look at the virtual metro line diagram created with Mermaid. Here, we changed the default main branch name to MetroLine1.

Customizing branch order

In Mermaid, by default, branches are displayed in the order in which they are defined or appear in the diagram code.

Sometimes you may want to customize the branch order. You can do this by using the order syntax next to the branch definition, which you can set to a positive number.

Mermaid follows the priority order given by the order syntax.

  • The main branch is always displayed first because its default order value is 0. (Unless its order has been modified via the mainBranchOrder syntax in the configuration and changed from 0.)
  • Next, all branches without an order are displayed in the order they appear in the diagram code.
  • Next, all branches with an order are displayed in the order of their order value.

To fully control the order of all branches, an order must be defined for all branches.

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' gitGraph: showBranches: true showCommitLabel: true --- gitGraph commit branch test1 order: 3 branch test2 order: 2 branch test3 order: 1

In the diagram above, all branches follow the defined order.

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' gitGraph: showBranches: true showCommitLabel: true mainBranchOrder: 2 --- gitGraph commit branch test1 order: 3 branch test2 branch test3 branch test4 order: 1

In the diagram above, all branches without a specified order are drawn in the order they were defined. Afterwards, the test4 branch is drawn because its order is 1. Then, the main branch is drawn because its order is 2. Finally, the test1 branch is drawn because its order is 3.

Note: because we have overridden mainBranchOrder to 2, the main branch is not drawn at the beginning but is displayed according to its order.

Here, we changed the default main branch name to MetroLine1.

Direction

Mermaid supports three directions: left to right (default), top to bottom, and bottom to top.

Left to right (default, LR:)

In Mermaid, the default direction runs from left to right, with branches stacked on top of each other.

However, you can explicitly set this value using LR: after the gitGraph syntax.

Code
                            
Copy
Embed
gitGraph LR: commit commit branch develop commit commit checkout main commit commit merge develop commit commit

Top to bottom (TB:)

In the top-to-bottom direction, commits run from the top to the bottom of the diagram, and branches are arranged side by side.

To orient the graph in this way, you need to add TB: after the gitGraph syntax.

Code
                            
Copy
Embed
gitGraph TB: commit commit branch develop commit commit checkout main commit commit merge develop commit commit

Bottom to top (BT:)

In the bottom-to-top direction, commits run from the bottom to the top of the diagram, and branches are arranged side by side.

To orient the graph in this way, you need to add BT: after the gitGraph syntax.

Code
                            
Copy
Embed
gitGraph BT: commit commit branch develop commit commit checkout main commit commit merge develop commit commit

Temporary commits (parallelCommits: false)

Code
                            
Copy
Embed
--- config: gitGraph: parallelCommits: false --- gitGraph: commit branch develop commit commit checkout main commit commit

Parallel commits (parallelCommits: true)

Code
                            
Copy
Embed
--- config: gitGraph: parallelCommits: true --- gitGraph: commit branch develop commit commit checkout main commit commit

Themes

Mermaid supports a range of custom themes that you can use to find a theme that suits you. Note: you can actually override the variables of an existing theme to create your own custom theme.

The following are the different custom theme options:

  • redux-color
  • redux-dark-color
  • redux
  • redux-dark
  • default
  • neutral
  • dark
  • forest
  • neo
  • neo-dark
  • base

To change the theme, you can use the initialize syntax.

Base theme

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'base' --- gitGraph commit branch hotfix checkout hotfix commit branch develop checkout develop commit id:"ash" tag:"abc" branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix commit type:NORMAL checkout develop commit type:REVERSE checkout featureB commit checkout main merge hotfix checkout featureB commit checkout develop branch featureA commit checkout develop merge hotfix checkout featureA commit checkout featureB commit checkout develop merge featureA branch release checkout release commit checkout main commit checkout release merge main checkout develop merge release

Forest theme

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'forest' --- gitGraph commit branch hotfix checkout hotfix commit branch develop checkout develop commit id:"ash" tag:"abc" branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix commit type:NORMAL checkout develop commit type:REVERSE checkout featureB commit checkout main merge hotfix checkout featureB commit checkout develop branch featureA commit checkout develop merge hotfix checkout featureA commit checkout featureB commit checkout develop merge featureA branch release checkout release commit checkout main commit checkout release merge main checkout develop merge release

Default theme

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' --- gitGraph commit type:HIGHLIGHT branch hotfix checkout hotfix commit branch develop checkout develop commit id:"ash" tag:"abc" branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix commit type:NORMAL checkout develop commit type:REVERSE checkout featureB commit checkout main merge hotfix checkout featureB commit checkout develop branch featureA commit checkout develop merge hotfix checkout featureA commit checkout featureB commit checkout develop merge featureA branch release checkout release commit checkout main commit checkout release merge main checkout develop merge release

Dark theme

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'dark' --- gitGraph commit branch hotfix checkout hotfix commit branch develop checkout develop commit id:"ash" tag:"abc" branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix commit type:NORMAL checkout develop commit type:REVERSE checkout featureB commit checkout main merge hotfix checkout featureB commit checkout develop branch featureA commit checkout develop merge hotfix checkout featureA commit checkout featureB commit checkout develop merge featureA branch release checkout release commit checkout main commit checkout release merge main checkout develop merge release

Neutral theme

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'neutral' --- gitGraph commit branch hotfix checkout hotfix commit branch develop checkout develop commit id:"ash" tag:"abc" branch featureB checkout featureB commit type:HIGHLIGHT checkout main checkout hotfix commit type:NORMAL checkout develop commit type:REVERSE checkout featureB commit checkout main merge hotfix checkout featureB commit checkout develop branch featureA commit checkout develop merge hotfix checkout featureA commit checkout featureB commit checkout develop merge featureA branch release checkout release commit checkout main commit checkout release merge main checkout develop merge release

Customizing with theme variables

Mermaid allows you to customize your diagrams using theme variables, which control the appearance and style of the various elements of the diagram.

To understand this, let's take the default theme as an example; the default values of the theme variables are automatically taken from the theme.

Using the default theme to set the branch colors:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' --- gitGraph commit branch develop commit tag:"v1.0.0" commit checkout main commit type: HIGHLIGHT commit merge develop commit branch featureA commit

Mermaid supports theme variables to override the defaults, for up to 8 branches, meaning you can set the colors of up to 8 branches using theme variables. After more than 8 branches, the theme variables are reused in a cyclical manner, that is, the 9th branch will use the style of the 1st branch.

Customizing branch colors

You can use the git0 to git7 theme variables to customize the branch colors. Mermaid allows you to set the colors of up to 8 branches, where the git0 variable controls the color of the first branch, git1 controls the color of the second branch, and so on.

Note: the default values of these theme variables are taken from the selected theme. If you want to override the defaults, you can use the initialize syntax to add custom theme variable values.

Example:

Now let's override the default values of the git0 to git3 variables:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' themeVariables: 'git0': '#ff0000' 'git1': '#00ff00' 'git2': '#0000ff' 'git3': '#ff00ff' 'git4': '#00ffff' 'git5': '#ffff00' 'git6': '#ff00ff' 'git7': '#00ffff' --- gitGraph commit branch develop commit tag:"v1.0.0" commit checkout main commit type: HIGHLIGHT commit merge develop commit branch featureA commit

Customizing branch label colors

You can use the gitBranchLabel0 to gitBranchLabel7 theme variables to customize the branch label colors. Mermaid allows you to set the colors of up to 8 branches, where the gitBranchLabel0 variable controls the color of the first branch label, the gitBranchLabel1 variable controls the color of the second branch label, and so on.

Let's see how to use the default theme to set the branch label colors:

Now let's override the default values of the gitBranchLabel0 to gitBranchLabel2 variables:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' themeVariables: 'gitBranchLabel0': '#ffffff' 'gitBranchLabel1': '#ffffff' 'gitBranchLabel2': '#ffffff' 'gitBranchLabel3': '#ffffff' 'gitBranchLabel4': '#ffffff' 'gitBranchLabel5': '#ffffff' 'gitBranchLabel6': '#ffffff' 'gitBranchLabel7': '#ffffff' 'gitBranchLabel8': '#ffffff' 'gitBranchLabel9': '#ffffff' --- gitGraph checkout main branch branch1 branch branch2 branch branch3 branch branch4 branch branch5 branch branch6 branch branch7 branch branch8 branch branch9 checkout branch1 commit

Here, you can see that the colors and styles of branch8 and branch9 are taken from the branches at index positions 0 (main) and 1 (branch1) respectively.

Customizing commit colors

You can use the commitLabelColor and commitLabelBackground theme variables to customize the color and background color of commit labels respectively.

Example: now let's override the default values of the commitLabelColor to commitLabelBackground variables:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' themeVariables: commitLabelColor: '#ff0000' commitLabelBackground: '#00ff00' --- gitGraph commit branch develop commit tag:"v1.0.0" commit checkout main commit type: HIGHLIGHT commit merge develop commit branch featureA commit

mermaid.grammar_mermaid_commit_label_define_label_font_big_small

You can use the commitLabelFontSize theme variable to customize the font size of commit labels.

Example: now let's override the default value of the commitLabelFontSize variable:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' themeVariables: commitLabelColor: '#ff0000' commitLabelBackground: '#00ff00' commitLabelFontSize: '16px' --- gitGraph commit branch develop commit tag:"v1.0.0" commit checkout main commit type: HIGHLIGHT commit merge develop commit branch featureA commit

Customizing label font size

You can use the tagLabelFontSize theme variable to customize the font size of labels.

Example: now let's override the default value of the tagLabelFontSize variable:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' themeVariables: commitLabelColor: '#ff0000' commitLabelBackground: '#00ff00' tagLabelFontSize: '16px' --- gitGraph commit branch develop commit tag:"v1.0.0" commit checkout main commit type: HIGHLIGHT commit merge develop commit branch featureA commit

Customizing label color

You can use the tagLabelColor, tagLabelBackground, and tagLabelBorder theme variables to customize labels, changing the label text color, label background color, and label border respectively.

Example: now let's override the default values of the tagLabelColor, tagLabelBackground, and tagLabelBorder variables:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' themeVariables: tagLabelColor: '#ff0000' tagLabelBackground: '#00ff00' tagLabelBorder: '#0000ff' --- gitGraph commit branch develop commit tag:"v1.0.0" commit checkout main commit type: HIGHLIGHT commit merge develop commit branch featureA commit

Customizing highlight commit color

You can use the gitInv0 to gitInv7 theme variables to customize the color of highlighted commits according to the branch they are on. Mermaid allows you to set the color of specific highlighted commits for up to 8 branches, where the gitInv0 variable controls the color of highlighted commits on the first branch, the gitInv1 variable controls the color of highlighted commits on the second branch, and so on.

Now let's override the default values of the git0 to git3 variables:

Code
                            
Copy
Embed
--- config: logLevel: 'debug' theme: 'default' themeVariables: 'gitInv0': '#ff0000' --- gitGraph commit branch develop commit tag:"v1.0.0" commit checkout main commit type: HIGHLIGHT commit merge develop commit branch featureA commit