How to Resolve Conflicts

When merging branches, conflicts occur when both branches modify the same record’s fields. This guide explains how to identify, understand, and resolve conflicts.

Understanding Conflicts

A conflict happens when:

1. Both branches modify the same record (identified by primary key)
2. Both branches change the same field to different values

Example:

• Branch A changes user 42’s email to alice@company.com
• Branch B changes user 42’s email to alice.smith@example.com

Detecting Conflicts

When you run a merge:

epoch merge feature/branch

If conflicts exist:

CONFLICT: Merge conflict in users
Automatic merge failed; fix conflicts and then commit.

Viewing Conflicts

List Conflicting Tables

epoch status

Output:

On branch main
You have unmerged paths.

Unmerged paths:
  both modified:   users (3 conflicts)
  both modified:   orders (1 conflict)

View 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: phone
    BASE:   555-0100
    OURS:   555-0100
    THEIRS: 555-0199

Record ID: 87
  Field: status
    BASE:   active
    OURS:   inactive
    THEIRS: suspended
------------------------------------------------------------

Export Conflicts to File

epoch conflicts show --format json > conflicts.json

Resolution Methods

1. Interactive Resolution (Recommended)

epoch conflicts resolve --interactive

This walks you through each conflict:

Conflict 1 of 4: users.email (record 42)
  BASE:   alice@example.com
  OURS:   alice@company.com
  THEIRS: alice.smith@example.com

Choose resolution:
  [o] Keep ours (alice@company.com)
  [t] Keep theirs (alice.smith@example.com)
  [b] Keep base (alice@example.com)
  [c] Enter custom value
  [s] Skip (resolve later)
>

2. Accept All from One Side

Accept all changes from your branch (target):

epoch conflicts resolve --ours

Accept all changes from the source branch:

epoch conflicts resolve --theirs

3. Per-Table Resolution

# Accept theirs for users table
epoch conflicts resolve users --theirs

# Accept ours for orders table
epoch conflicts resolve orders --ours

4. Per-Record Resolution

# Keep our version of record 42
epoch conflicts resolve users --record 42 --ours

# Keep their version of record 87
epoch conflicts resolve users --record 87 --theirs

5. Per-Field Resolution

# Set specific value for a field
epoch conflicts resolve users \
    --record 42 \
    --field email \
    --value "alice.final@company.com"

6. Python SDK Resolution

# Get conflicts
conflicts = client.get_conflicts()

for conflict in conflicts:
    print(f"Table: {conflict.table_name}")
    print(f"Record: {conflict.record_id}")

    for field in conflict.fields:
        print(f"  {field.name}:")
        print(f"    base={field.base_value}")
        print(f"    ours={field.ours_value}")
        print(f"    theirs={field.theirs_value}")

        # Resolve programmatically
        client.resolve_conflict(
            table=conflict.table_name,
            record_id=conflict.record_id,
            field=field.name,
            value=determine_winner(field)  # Your logic
        )

# Continue merge
client.merge_continue()

Completing the Merge

After resolving all conflicts:

epoch merge --continue

Or if you want to abandon the merge:

epoch merge --abort

Conflict Prevention Strategies

1. Merge frequently - Smaller, more frequent merges have fewer conflicts
2. Communicate - Coordinate with team on who owns which data
3. Use feature flags - Test changes without modifying shared records
4. Partition work - Different team members work on different record sets

Best Practices

1. Understand the context - Read the commit messages from both branches
2. Check business rules - Some conflicts have a “correct” answer based on business logic
3. Document decisions - Add context in your merge commit message
4. Verify after merge - Run validation queries after resolving conflicts

Example Workflow

# 1. Start merge
epoch merge feature/user-updates

# 2. See what conflicted
epoch conflicts show

# 3. Resolve interactively
epoch conflicts resolve --interactive

# 4. Verify resolutions
epoch status
epoch diff HEAD

# 5. Complete merge with descriptive message
epoch merge --continue -m "Merge user-updates: resolved email conflicts using company domain policy"