Tutorial: Branching Workflow

Learn how to use branches effectively in Horizon Epoch for parallel development and safe experimentation.

Prerequisites

• Completed Your First Repository tutorial
• A repository with at least one registered table

Understanding Branches

Branches in Horizon Epoch work like Git branches:

• Each branch is an independent line of development
• Branches are zero-copy - creating one doesn’t duplicate data
• Changes on one branch don’t affect others until merged

How Zero-Copy Branching Works

When you create a branch in Horizon Epoch, no data is actually copied. Instead, the new branch simply points to the same data as its parent. Only when you make changes does Horizon Epoch store the modified records separately.

flowchart LR
    subgraph "Before Branch Creation"
        M1[("main branch")] --> D1[("Shared Data<br/>users: 1000 rows<br/>orders: 5000 rows")]
    end

flowchart LR
    subgraph "After Branch Creation (Zero-Copy)"
        M2[("main")] --> D2[("Shared Data<br/>users: 1000 rows<br/>orders: 5000 rows")]
        F2[("feature")] --> D2
    end

flowchart LR
    subgraph "After Modifications on Feature Branch"
        M3[("main")] --> D3[("Shared Data<br/>users: 1000 rows<br/>orders: 5000 rows")]
        F3[("feature")] --> D3
        F3 --> C3[("Branch Changes<br/>users: 5 modified<br/>users: 2 added")]
    end

This architecture means:

• Instant branch creation - No waiting for data to copy
• Efficient storage - Only changed records are stored twice
• Fast queries - Branch-specific changes are overlaid on base data

Common Branching Patterns

Pattern 1: Feature Branch

Create a branch for a new feature or experiment:

gitGraph
    commit id: "Initial"
    commit id: "Add users table"
    branch feature/user-preferences
    checkout feature/user-preferences
    commit id: "Add preferences column"
    commit id: "Populate default values"
    checkout main
    merge feature/user-preferences id: "Merge feature"
    commit id: "Continue development"

epoch branch create feature/user-preferences
epoch checkout feature/user-preferences

Pattern 2: Environment Branches

Maintain branches for different environments:

gitGraph
    commit id: "v1.0"
    branch staging
    branch development
    checkout development
    commit id: "New feature A"
    commit id: "New feature B"
    checkout staging
    merge development id: "Promote to staging"
    checkout main
    commit id: "v1.1 Hotfix"
    checkout staging
    merge main id: "Sync hotfix"
    checkout main
    merge staging id: "Release v1.2"

epoch branch create development
epoch branch create staging
epoch branch create production

Pattern 3: Hotfix Branch

Quick fixes that need to go directly to production:

gitGraph
    commit id: "v1.0 Release"
    commit id: "v1.1 Release"
    branch hotfix/fix-email
    checkout hotfix/fix-email
    commit id: "Fix email format"
    checkout main
    merge hotfix/fix-email id: "v1.1.1 Hotfix"

epoch branch create hotfix/fix-email-format --from production

Pattern 4: Multiple Feature Branches

Working on multiple features in parallel:

gitGraph
    commit id: "Base"
    branch feature/auth
    branch feature/reporting
    checkout feature/auth
    commit id: "Add login"
    commit id: "Add logout"
    checkout feature/reporting
    commit id: "Add daily report"
    commit id: "Add weekly report"
    checkout main
    merge feature/auth id: "Merge auth"
    merge feature/reporting id: "Merge reporting"

Step-by-Step: Feature Branch Workflow

1. Create a Feature Branch

epoch branch create feature/add-status-field

2. Switch to the Branch

epoch checkout feature/add-status-field

3. Make Changes to Your Data

Modify the underlying data (e.g., add records, update schema):

-- In your PostgreSQL database
ALTER TABLE users ADD COLUMN status VARCHAR(20) DEFAULT 'active';
UPDATE users SET status = 'active';

4. Review Changes

epoch diff

Output:

Modified: users
  Schema changes:
    + status (varchar)
  Record changes:
    ~ 3 records modified (new field values)

5. Commit Your Changes

epoch commit -m "Add status field to users table"

6. View Branch History

epoch log --oneline

Output:

def456g Add status field to users table
abc123f Initial import of users table

7. Compare with Main

epoch diff main..feature/add-status-field

8. Merge to Main

epoch checkout main
epoch merge feature/add-status-field

9. Clean Up

epoch branch delete feature/add-status-field

Branch Lifecycle Visualization

The complete lifecycle of a feature branch:

stateDiagram-v2
    [*] --> Created: epoch branch create
    Created --> Active: epoch checkout
    Active --> Modified: Make data changes
    Modified --> Committed: epoch commit
    Committed --> Modified: More changes
    Committed --> Reviewed: epoch diff main..branch
    Reviewed --> Merged: epoch merge
    Merged --> Deleted: epoch branch delete
    Deleted --> [*]

Environment Promotion Flow

A typical flow for promoting changes through environments:

flowchart TD
    subgraph Development
        D1[Feature Branch] --> D2[Development Branch]
        D2 --> D3{Tests Pass?}
        D3 -->|No| D1
    end

    subgraph Staging
        D3 -->|Yes| S1[Promote to Staging]
        S1 --> S2{QA Approved?}
        S2 -->|No| D1
    end

    subgraph Production
        S2 -->|Yes| P1[Promote to Production]
        P1 --> P2[Tag Release]
    end

# Promote development to staging
epoch checkout staging
epoch merge development

# After QA approval, promote to production
epoch checkout production
epoch merge staging
epoch tag v1.2.0

Branch Comparison Summary

Best Practices

1. Keep branches short-lived - Merge frequently to avoid conflicts
2. Use descriptive names - feature/user-auth is better than branch1
3. One feature per branch - Makes merging and rollback easier
4. Test before merging - Validate changes on the branch first
5. Delete merged branches - Keep your branch list clean

Visualizing Your Repository

You can visualize your repository’s branch structure:

# List all branches with their relationships
epoch branch list --graph

# Show commit history across branches
epoch log --graph --all

Next Steps

• Merging Data - Learn about merge strategies and conflict resolution
• Environment Promotion - Deploy changes safely across environments