Tutorial: Merging Data

Learn how to merge branches, handle conflicts, and understand merge strategies in Horizon Epoch.

Prerequisites

• Completed Branching Workflow tutorial
• Understanding of basic branch operations

Merge Types

Fast-Forward Merge

When the target branch hasn’t changed since the source branch was created:

Before:
main:     A---B
               \
feature:        C---D

After (fast-forward):
main:     A---B---C---D

epoch merge feature/simple-change
# Fast-forward merge: main -> def456g

Three-Way Merge

When both branches have diverged:

Before:
main:     A---B---C
               \
feature:        D---E

After (three-way merge):
main:     A---B---C---F
               \     /
feature:        D---E

epoch merge feature/complex-change
# Merged feature/complex-change into main (commit: ghi789h)

Handling Conflicts

Conflicts occur when both branches modify the same record’s fields.

Detecting Conflicts

epoch merge feature/conflicting-changes
# CONFLICT: Merge conflict in users
# Automatic merge failed; fix conflicts and then commit.

Viewing Conflicts

epoch status

Output:

On branch main
You have unmerged paths.
  (fix conflicts and run "epoch merge --continue")
  (use "epoch merge --abort" to abort the merge)

Unmerged paths:
  both modified:   users (3 conflicts)

Inspecting Conflict Details

epoch conflicts show

Output:

Table: users
Record ID: 42
Field: email
  BASE:   alice@example.com
  OURS:   alice@company.com
  THEIRS: alice.smith@example.com

Field: status
  BASE:   active
  OURS:   active
  THEIRS: inactive

Resolving Conflicts

Interactive Resolution

epoch conflicts resolve --interactive

Accept One Side

# Accept all changes from target branch (ours)
epoch conflicts resolve --ours

# Accept all changes from source branch (theirs)
epoch conflicts resolve --theirs

Field-Level Resolution

epoch conflicts resolve users --record 42 --field email --value "alice.smith@company.com"

Completing the Merge

epoch merge --continue

Aborting the Merge

If you need to start over:

epoch merge --abort

Merge Strategies

Default Strategy

The default strategy uses three-way merge with field-level conflict detection:

epoch merge feature/my-branch

Ours Strategy

Keep all conflicting values from the target branch:

epoch merge feature/my-branch --strategy ours

Theirs Strategy

Accept all conflicting values from the source branch:

epoch merge feature/my-branch --strategy theirs

Best Practices

1. Merge frequently - Small, frequent merges have fewer conflicts
2. Review diffs first - Use epoch diff before merging
3. Test after merge - Validate data integrity post-merge
4. Document conflicts - Add context in merge commit messages

Example: Complete Merge Workflow

# 1. Ensure you're on the target branch
epoch checkout main

# 2. Pull latest changes (if using remote)
epoch pull

# 3. Preview what will be merged
epoch diff main..feature/my-feature

# 4. Perform the merge
epoch merge feature/my-feature

# 5. If conflicts, resolve them
epoch conflicts show
epoch conflicts resolve --interactive

# 6. Complete the merge
epoch merge --continue

# 7. Verify the result
epoch log --oneline -5
epoch status

Next Steps

• Environment Promotion - Promote changes across environments
• Resolve Conflicts - Detailed conflict resolution guide