GitGraph Diagrams

What are GitGraph Diagrams?

Mermaid's GitGraph diagrams help you visualize Git workflows and branching strategies. For data teams, they're invaluable for documenting:

• Feature development workflows

• Release processes

• Data pipeline versioning

• Model deployment strategies

• Hotfix procedures

• Team collaboration patterns

Creating Your First GitGraph

1. From the Code IDE, Click Apps and Agents from the lefthand panel

2. Select Mermaid. Paradime will automatically start a new mermaid project

3. In the terminal that appears, use the arrow keys to select "GitGraph Diagrams"

4. A new gitGraph.mmd file will be created in your editor with this starter template:

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

1. Click the eye icon (👁️) in the top right corner of your Mermaid file to preview the diagram

2. Edit and update your .mmd file as needed - the preview will update automatically

Core Git Operations

Basic Commands

• commit: Add a new commit to current branch

• branch: Create and switch to a new branch

• checkout: Switch to an existing branch

• merge: Merge a branch into current branch

Commit Customization

gitGraph
    commit                               # Regular commit
    commit id: "abc123"                 # Custom ID
    commit tag: "v1.0.0"               # Add release tag
    commit type: HIGHLIGHT             # Highlight important commits
    commit type: REVERSE              # Indicate reverted commits

Branch Management

gitGraph
    commit
    branch feature/new-model            # Create feature branch
    checkout feature/new-model
    commit
    checkout main
    merge feature/new-model            # Merge feature

Common Data Team Workflows

Feature Development

gitGraph
    commit id: "base_models"
    branch feature/new-transformations
    commit id: "add_staging"
    commit id: "add_marts"
    checkout main
    merge feature/new-transformations tag: "v2.0.0"

Release Process

gitGraph
    commit
    branch develop
    commit id: "new_metrics"
    branch feature/reporting
    commit
    checkout develop
    merge feature/reporting
    checkout main
    merge develop tag: "release-1.2.0"

Hotfix Workflow

gitGraph
    commit tag: "prod"
    branch hotfix/data-fix
    commit id: "fix_null_values"
    checkout main
    merge hotfix/data-fix tag: "v1.0.1"

Advanced Features

Custom Commit Types

1. NORMAL: Standard commit (default)

2. REVERSE: Reverted commits

3. HIGHLIGHT: Important commits

Cherry-picking

gitGraph
    commit id: "feat-1"
    branch release
    checkout main
    commit id: "feat-2"
    checkout release
    cherry-pick id: "feat-2"

Orientation Options

• Left to Right (default): gitGraph LR:

• Top to Bottom: gitGraph TB:

• Bottom to Top: gitGraph BT:

Configuration Options

Visual Customization

%%{init: { 
    'gitGraph': {
        'showBranches': true,
        'showCommitLabel': true,
        'mainBranchName': 'main'
    }
}}%%
gitGraph
    commit
    branch develop
    commit

Branch Ordering

• Set main branch order: mainBranchOrder

• Custom branch order: branch develop order: 2

• Default ordering follows appearance in code

Best Practices

1. Use meaningful commit IDs and tags

2. Group related changes in feature branches

3. Mark significant releases with tags

4. Highlight important commits

5. Maintain clear branch naming conventions

6. Document merge strategies

Common Use Cases

• Feature branch workflows

• Release management

• Hotfix procedures

• Data pipeline versioning

• Model deployment strategies

• Team collaboration patterns

---

Additional Resources

For more syntax options and advanced features, visit the official Mermaid documentation