How to Draw Git Graphs in Mermaid

2026-03-05 · MermZen Tutorial

Git graphs visualize version control system branch management, commit history, and merge operations. They are ideal for software development team collaboration, project management, and version control teaching. Mermaid uses gitGraph keyword for Git graphs.

Why Use Git Graphs?

Problems Git Graphs Solve

Git graphs address key challenges in understanding and communicating version control workflows:

• Visualizing Branching Strategies: Transform abstract Git commands into visual timelines that show exactly when branches were created, where commits were made, and how code flows together
• Tracking Development Flow: See the complete journey of code from initial commits through feature branches to final merge
• Documenting Release History: Create permanent visual records of what code went into each release
• Onboarding New Team Members: Help newcomers understand your team's branching conventions without reading lengthy documentation

Suitable Scenarios

Git graphs excel in these situations:

Team Onboarding: When new developers join, a Git graph shows your branching strategy at a glance.

Code Review Preparation: Before reviewing complex changes, visualize the branch structure to understand the context.

Release Planning: Plan and communicate release strategies by showing which features will merge when.

Documentation: Include in technical documentation to illustrate your Git workflow.

When NOT to Use Git Graphs

Git graphs are not suitable for:

• Simple Linear History: If your project just commits to main with no branching, a Git graph adds no value:

gitGraph
    commit "Initial commit"
    commit "Add feature A"
    commit "Fix bug B"
    commit "Release v1.0"

• Showing File Changes: Git graphs show commit structure, not what changed in each commit
• Detailed Code Review: Use diff views for line-by-line code changes
• Performance Analysis: Git graphs don't show commit sizes or impact

Comparison with Other Diagrams

Git Graph vs Flowchart

Understanding when to use each diagram type helps you choose the right visualization:

Use Git Graphs when: Documenting your team's Git workflow, planning releases, or showing how features branch and merge.

Use Flowcharts when: Documenting deployment processes, CI/CD pipelines, or decision workflows. For example, a code review process is better shown as a flowchart:

flowchart TD
    A[Start Development] --> B{Feature Complete?}
    B -->|Yes| C[Create Pull Request]
    B -->|No| D[Continue Coding]
    D --> B
    C --> E{Code Review Approved?}
    E -->|Yes| F[Merge to Main]
    E -->|No| G[Address Feedback]
    G --> D
    F --> H[Deploy to Production]

Decision Guide

• Multiple parallel features merging at different times? → Git Graph
• Sequential process with decision points? → Flowchart
• Showing who worked on what and when? → Git Graph
• Documenting how to handle errors? → Flowchart

Declaring a Chart

Use gitGraph keyword:

gitGraph
    title Git Graph Title

Basic Commits and Branches

Create simple commits and branches:

gitGraph
    title Basic Git Graph
    commit "Initial commit"
    commit "Feature A"
    branch feature-branch1
    commit "Complete feature 1"
    commit "Fix bug 1"
    checkout main
    branch feature-branch2
    commit "Complete feature 2"

Branch Merging

Demonstrate branch merging operations:

gitGraph
    title Branch Merge Example
    commit
    branch feature-1
    commit
    commit
    checkout main
    branch feature-2
    commit
    commit
    checkout main
    merge feature-1
    commit
    merge feature-2

Tags and Versions

Add tags and version management:

gitGraph
    title Version Management Example
    commit "v1.0.0 release"
    branch feature/auth
    commit "Add authentication"
    commit "Fix security vulnerability"
    checkout main
    merge feature/auth tag: "v1.1.0"
    commit "Test fixes"
    branch hotfix/security
    commit "Critical security fix"
    checkout main
    merge hotfix/security tag: "v1.1.1"

Full Example: Product Development Flow

gitGraph
    title Product Development Git Flow
    commit "Project initialization"
    commit "Basic architecture"
    branch feature/login
    commit "Implement login functionality"
    commit "Login UI optimization"
    checkout main
    branch feature/dashboard
    commit "Dashboard framework"
    commit "Data visualization components"
    commit "User statistics"
    checkout main
    branch feature/settings
    commit "User settings page"
    commit "Security settings"
    checkout main
    merge feature/login tag: "v1.0.0-beta"
    commit "Testing fixes"
    merge feature/dashboard
    merge feature/settings tag: "v1.0.0"
    branch hotfix/performance
    commit "Optimize loading speed"
    commit "Reduce memory leaks"
    checkout main
    merge hotfix/performance tag: "v1.0.1"

Best Practices

1. Keep Diagrams Simple (Max 5-6 Branches)

Complex diagrams become hard to read. Limit yourself to 5-6 concurrent branches maximum:

gitGraph
    title Best Practices Example
    commit "Meaningful commit message"
    branch feature/user-profile
    commit "feat: Add user profile page"
    checkout main
    commit "chore: Update dependencies"
    merge feature/user-profile tag: "v1.1.0"
    branch hotfix/security
    commit "fix: Security vulnerability fix"
    checkout main
    merge hotfix/security tag: "v1.1.1"

Why: Each branch adds visual complexity. Too many branches create a "spaghetti" diagram that's impossible to follow.

2. Use Meaningful Branch Names

Clear branch names communicate intent:

gitGraph
    title Meaningful Branch Names
    commit id: "Initial commit"
    branch feature/user-authentication
    commit id: "Add OAuth login"
    checkout main
    branch bugfix/login-redirect-issue-234
    commit id: "Fix redirect loop"
    checkout main
    merge feature/user-authentication tag: "v1.1.0"
    merge bugfix/login-redirect-issue-234

3. Tag Important Releases

Always tag releases so you can reference them later:

gitGraph
    title Tag Important Releases
    commit id: "Project start"
    branch feature/core-api
    commit id: "Core API implementation"
    checkout main
    merge feature/core-api tag: "v1.0.0"
    branch hotfix/critical-fix
    commit id: "Fix security issue"
    checkout main
    merge hotfix/critical-fix tag: "v1.0.1"
    branch feature/new-module
    commit id: "New module added"
    checkout main
    merge feature/new-module tag: "v1.1.0"

Tags make it easy to:

• Roll back to stable versions
• Generate changelogs
• Track what features shipped when

4. Show Merge Strategies Clearly

Document your merge strategy in the diagram:

gitGraph
    title Show Merge Strategies
    commit id: "Main branch"
    branch feature-a
    commit id: "Feature A commit 1"
    commit id: "Feature A commit 2"
    checkout main
    branch feature-b
    commit id: "Feature B work"
    checkout main
    merge feature-a id: "Merge commit (merge)"
    checkout feature-b
    merge main id: "Rebase onto main"
    checkout main
    merge feature-b id: "Fast-forward merge"

Common Mistakes

Mistake 1: Overly Complex Diagrams

❌ Don't create diagrams with too many branches:

gitGraph
    title ❌ Overly Complex Diagram
    commit id: "Start"
    branch f1
    commit id: "F1"
    branch f2
    commit id: "F2"
    branch f3
    commit id: "F3"
    branch f4
    commit id: "F4"
    branch f5
    commit id: "F5"
    branch f6
    commit id: "F6"
    checkout main
    merge f1
    merge f2
    merge f3
    merge f4
    merge f5
    merge f6

✅ Instead: Split into multiple diagrams or simplify the scope.

Mistake 2: Missing Commit Messages

❌ Don't leave commits without messages:

gitGraph
    title ❌ Missing Commit Messages
    commit
    commit
    branch feature
    commit
    commit
    checkout main
    merge feature
    commit

✅ Instead: Always add meaningful messages:

gitGraph
    title ✅ With Clear Messages
    commit id: "Initial setup"
    commit id: "Add dependencies"
    branch feature/auth
    commit id: "Implement login"
    commit id: "Add tests"
    checkout main
    merge feature/auth id: "Merge auth feature"
    commit id: "Prepare release"

Mistake 3: Not Showing Merge Conflict Resolution

❌ Don't hide the complexity of merge conflicts:

When two branches modify the same files, show that conflicts were resolved:

gitGraph
    title Show Conflict Resolution
    commit id: "Base commit"
    branch feature-x
    commit id: "Modify config.json"
    commit id: "Feature X complete"
    checkout main
    branch feature-y
    commit id: "Also modify config.json"
    commit id: "Feature Y complete"
    checkout main
    merge feature-x tag: "Pre-merge"
    merge feature-y id: "⚠️ Resolved conflict in config.json"
    commit id: "Both features integrated"

✅ Best practice: Document significant merge conflicts and their resolutions in the diagram to help future developers understand the integration challenges.

Git Workflow Examples

Feature Branch Workflow

One branch per feature, merge to main when complete:

gitGraph
    title Feature Branch Workflow
    commit "Project initialization"
    branch feature/user-auth
    commit "Add user authentication"
    checkout main
    merge feature/user-auth

Git Flow Workflow

More complex branching strategy for large projects:

gitGraph
    title Git Flow Workflow
    commit "Initial commit"
    branch develop
    commit "Development branch"
    branch feature/login
    commit "Login feature"
    checkout develop
    merge feature/login
    checkout main
    merge develop tag: "v1.0.0"

Branch Naming Conventions

Common Commands Reference

Git graph syntax mapped to Git commands:

gitGraph
    title Common Commands Reference
    commit id: "git commit"
    branch feature
    commit id: "git branch"
    checkout feature
    commit id: "git checkout"
    checkout main
    merge feature id: "git merge"
    commit id: "git tag v1.0" type: HIGHLIGHT

Commit Message Convention:

• feat: New feature
• fix: Bug fix
• docs: Documentation update
• style: Code formatting
• refactor: Code refactoring
• test: Testing
• chore: Build/tooling

Branch Management Tips:

• Feature branch naming: feature/xxx
• Pull latest code before merging
• Regularly clean up merged branches
• Use Pull Requests for code review

Quick Reference

Next Step

After mastering Git graphs, you can continue learning other Mermaid diagram types or check our Mermaid Cheat Sheet for complete syntax reference.

To try the above code in MermZen, click Open Editor and paste the code there.