Git history can be messy. Explaining a team's branching strategy using words often leads to confusion. 'Do we merge to develop first?', 'When do we tag?', 'How do hotfixes work?'. Mermaid's `gitGraph` is a specialized diagram type designed specifically to answer these questions by simulating a git history.

Visualizing Gitflow Strategy

Gitflow is a classic branching strategy involving `main`, `develop`, `feature/*`, `release/*`, and `hotfix/*` branches. It is complex, which makes it the perfect candidate for visualization.

This diagram tells a complete story. We see parallel feature development, a stabilization release branch, and the critical hotfix flow where a patch must be applied to both `main` and `develop` to prevent regression.

Customizing the Graph

Mermaid allows you to customize the appearance of commits to draw attention to specific events. You can use custom IDs, Tags, and Types (NORMAL, REVERSE, HIGHLIGHT).

• `commit id: "text"` : Sets the hash/label of the commit.
• `commit tag: "v1.0"` : Adds a visual tag icon.
• `commit type: HIGHLIGHT` : Makes the dot larger/different color.
• `cherry-pick id: "text"` : Shows a commit being copied from another branch.

Trunk-Based Development

In contrast to Gitflow, modern CI/CD often prefers Trunk-Based Development. Here, long-lived branches are avoided. Let's see how that looks.

Release Communication Toolkit

Export your gitGraph and drop it into release notes so non-engineers can follow what shipped, what branched, and what was hotfixed. Pair it with a short glossary explaining branch naming rules and tag semantics.

• Annotate LTS branches, maintenance windows, and freeze periods directly in the diagram.
• Highlight security hotfix branches in red to emphasize urgency.
• Include PR numbers near merges to make code review history discoverable.