Embracing the Stack-Based Workflow

Modern software development rarely progresses in a straight line. Features depend on other features. Bug fixes reveal more bugs. Refactors enable new capabilities. Yet most version control systems force us to think in terms of isolated branches and complex merges. Astral offers a different mental model: the stack.

The Problem with Branches

Consider a common scenario: you're implementing user authentication. It naturally breaks down into several logical changes:

Database schema for user credentials
Password hashing utilities
Login API endpoint
Session management middleware
Logout functionality

Each change builds on the previous one. In Git, you might:

Create one giant branch with everything (hard to review)
Create five separate branches (nightmare to manage dependencies)
Try to use git rebase -i to organize commits (error-prone)

None of these are great. The first makes review difficult. The second creates a web of dependencies. The third requires expert Git knowledge and often goes wrong.

Enter the Stack

Astral treats dependent changes as a stack—a vertical series of commits where each layer builds upon the one below. This maps naturally to how features are actually developed and reviewed.

Working with Your Stack

Building the Stack

As you work, each asl save adds a new layer to your stack:

# Implement database schema
asl save -m "Setup user database schema"

# Add password utilities  
asl save -m "Add password hashing utils"

# Continue building...
asl save -m "Create login API endpoint"

Navigating

Need to modify an earlier commit? Navigate there directly:

# Move down to the password utils commit
asl prev 2

# Or go directly by hash
asl goto b2c3d4e

# Check where you are
asl stack

Making Changes Mid-Stack

Here's where the stack shines. Say a reviewer asks you to change how password hashing works. In Git, this would mean a painful interactive rebase. In Astral:

# Navigate to the commit
asl goto b2c3d4e

# Make your changes
vim src/auth/password.go

# Amend the commit
asl amend

# Return to the top of your stack
asl top

Astral automatically rebases the commits above. If there are conflicts, they're isolated to specific commits, making them easier to resolve.

Code Review with Stacks

Stacks align perfectly with how modern code review works:

Each commit becomes a focused, reviewable unit
Reviewers can understand changes incrementally
You can address feedback in the right commit
The final merged history is clean and logical

Submitting for Review

When you're ready, you can submit each layer for review individually or as a complete stack. Different teams prefer different approaches—Astral supports both.

Advanced Stack Operations

Reordering Commits

Sometimes you realize commits should be in a different order:

# Interactive reorder
asl reorder

# In the editor, rearrange lines:
# pick a1b2c3d Setup user database schema  
# pick c3d4e5f Create login API endpoint    ← moved up
# pick b2c3d4e Add password hashing utils   ← moved down
# pick d4e5f6a Implement session middleware
# pick e5f6a7b Add logout functionality

Squashing

Combine multiple commits when they logically belong together:

# Squash the top 2 commits
asl squash 2

# Edit the combined commit message
# The result: one commit with all changes

Splitting

Too much in one commit? Split it:

# Navigate to the oversized commit
asl goto c3d4e5f

# Split it into multiple commits
asl split

# Astral resets to before the commit
# You can now save changes as multiple commits

The Mental Model Shift

Adopting the stack workflow requires a small mental shift:

Think vertically instead of horizontally
Each commit is a layer, not a snapshot
History is malleable until you ship
Dependencies are explicit and visual

Once you internalize this model, you'll find yourself working more confidently with dependent changes. No more fear of rebases. No more hesitation about restructuring your work.

Conclusion

The stack-based workflow isn't just a feature—it's a philosophy. It acknowledges that real development is messy, that changes depend on other changes, and that we should be able to reorganize our work without fear.

Give stacks a try. Start with your next feature. We think you'll find it's a more natural way to work with version control.

— The Astral Team