· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·

Merging

Merging Visualization
Core Concepts / Merging

Three-Way Merge

Merging is how separate lines of development come together. Astral uses a sophisticated three-way merge algorithm that intelligently combines changes and clearly identifies conflicts when they occur.

The Three-Way Merge

When merging two branches, Astral looks at three versions:

Merge Diagram
Ours
Your changes
Base
Common ancestor
Theirs
Their changes
↓ merge ↓
Result

How It Works

  1. Find Base: Identify the common ancestor of both branches
  2. Diff Both Sides: Calculate what changed in each branch since the base
  3. Apply Non-Conflicts: Changes that don't overlap are applied automatically
  4. Mark Conflicts: Overlapping changes are marked for manual resolution

Performing a Merge

Basic Merge

# Switch to target branch
asl switch main

# Merge feature branch
asl merge feature-auth
Successful Merge
$ asl merge feature-auth

Merging 'feature-auth' into 'main'...

Auto-merging src/auth/login.go
Auto-merging src/db/users.go

✓ Merge completed: 8f2a1c3d
2 files merged automatically

Merge with Conflicts

When conflicts occur:

$ asl merge feature-auth

Merging 'feature-auth' into 'main'...

Auto-merging src/auth/login.go
CONFLICT (content): Merge conflict in src/config/settings.go

✗ Automatic merge failed
  1 conflict needs resolution
  
Use 'asl status' to see conflicts
Use 'asl resolve' after fixing

Resolving Conflicts

View Conflicts

asl status

# Output shows:
# Unmerged paths:
#   both modified:   src/config/settings.go

Conflict Markers

Conflicting files contain markers:

Conflict Markers
<<<<<<< OURS (main)maxConnections = 100=======maxConnections = 200>>>>>>> THEIRS (feature-auth)

Resolution Process

  1. Edit the file: Remove markers, keep the correct content
  2. Mark as resolved: asl resolve src/config/settings.go
  3. Complete the merge: asl merge --continue
# After editing the file
asl resolve src/config/settings.go

# Continue the merge
asl merge --continue

Merge Strategies

Fast-Forward Merge

When the target branch hasn't diverged:

asl merge feature-auth --ff

# Result: Just moves the pointer, no merge commit
When to Use

Fast-forward is cleanest when your feature is purely additive and main hasn't changed.

No Fast-Forward

Force a merge commit even when fast-forward is possible:

asl merge feature-auth --no-ff

# Result: Always creates a merge commit

Squash Merge

Combine all commits into one:

asl merge feature-auth --squash

# Result: All changes applied as one commit

Aborting a Merge

If things go wrong:

# Abort and return to pre-merge state
asl merge --abort

Best Practices

Small, Frequent Merges

Merge early and often. Large divergence leads to complex conflicts.

Test After Merge

Always run your test suite after a merge, even if it was automatic.

Meaningful Commit Messages

Merge commits should summarize what was integrated and why.

Consider Squashing

For feature branches with many WIP commits, squash before merging.

Next Steps

Reference
CLI Commands →
Deep Dive
Architecture Overview →
└─── End of Document ───┘