· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
The Stack
Layers of Change
The Stack is Astral's foundational mental model for managing changes. Rather than thinking in terms of a complex graph of branches and merges, Astral encourages you to think of your work as layers stacked on top of a stable base.
The Mental Model
Imagine your repository history as a stack of transparent plates:
Key Concepts
- Base: The stable state you're building on (usually
main) - Layer: Each commit is a layer of changes
- HEAD: Your current position in the stack
- Stack Operations: Insert, remove, reorder, or squash layers
Working with Stacks
Viewing Your Stack
The asl stack command shows your current position:
$ asl stack
@ 8f2a1c (HEAD) Add user authentication
o 4b1d9e Implement login form
o 1a2b3c Setup database schema
|
o (main)
@ marks your current position (HEAD)o represents other commits in the stack| shows the connection to the baseNavigating the Stack
Move through your stack effortlessly:
# Move down one commit
asl prev
# Move up one commit
asl next
# Move to a specific commit
asl goto 4b1d9e
# Jump to the top of the stack
asl top
# Jump to the base
asl bottom
Building the Stack
Add new layers as you work:
# Make changes and save as a new layer
asl save -m "Add password validation"
# Your stack now has a new layer on top
asl stack
Stack Operations
Reordering Commits
Sometimes you need to change the order:
# Interactive reorder mode
asl reorder
# This opens an editor where you can rearrange commits
pick 8f2a1c Add user authentication pick 4b1d9e Implement login form pick 1a2b3c Setup database schema # Reorder, squash, or edit commits # Lines starting with '#' are ignored
Amending a Layer
Update the current commit:
# Make additional changes
# ...
# Amend the current layer
asl amend
Squashing Layers
Combine multiple layers into one:
# Squash the top 3 commits into one
asl squash 3
Splitting a Layer
Break one commit into multiple:
# Split the current commit
asl split
Why Stacks?
Stacks map naturally to how pull requests work. Each layer can become its own reviewable unit, with clear dependencies.
Need to update a commit buried in your stack? Navigate there, amend it, and Astral handles rebasing automatically.
Stacks encourage atomic, well-organized commits. Each layer should do one thing well.
When conflicts occur, they're isolated to specific layers, making them easier to understand and resolve.