Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
What is a Stack?

A stack is a chain of lanes where each lane’s branch is based on another lane’s branch instead of directly on main. This mirrors the stacked PR workflow used in many engineering teams — break a large feature into small, reviewable chunks that build on each other. 
main
└── lane/auth-models        (base: main)
    └── lane/auth-ui        (base: lane/auth-models)
        └── lane/auth-tests (base: lane/auth-ui)
Each lane in the stack maps to one pull request. Reviewers see small, focused diffs. The stack topology is tracked automatically — ADE knows which lanes depend on which, and uses this knowledge for rebase propagation, conflict detection, and PR targeting.

​
Creating a Stack

There are two ways to add a lane to a stack. You can nest lanes as deep as needed — each child targets the lane directly above it. However, stacks deeper than 3-4 levels become harder to manage and review. If a stack is growing deep, consider whether some layers can be merged or parallelized.

​
Viewing the Stack

ADE surfaces stack relationships in multiple places:
LocationWhat you see
Lanes panelIndented tree showing parent-child relationships with depth indicators
Workspace GraphConnected chain of nodes with edges showing base-branch dependencies
PR panelStack context in PR descriptions — which PR this builds on, full chain visualization
Lane detailParent lane reference and stack depth in the lane header
The Workspace Graph is the most powerful view for stacks. Each lane appears as a node, and you can see status badges (uncommitted changes, open PRs, active agents, conflicts) at a glance across the entire chain.

​
Stack Chain Resolution

ADE resolves the full stack chain using a recursive query that walks parent-child relationships from any lane in the stack. The chain includes every lane from the root (the lane based on main) down to the deepest leaf. Each item in the chain tracks:
  • Lane identity — name, branch, and worktree path
  • Depth — how many levels from the root
  • Status — dirty state, ahead/behind counts relative to the parent, rebase state
  • Parent reference — which lane this one depends on
This chain is used for rebase propagation, conflict simulation, and PR auto-targeting.

​
Rebasing a Stack

When a parent lane receives new commits, its children are now out of date. ADE handles this through rebase suggestions and rebase runs.

​
Rebase Suggestions

ADE monitors the relationship between each lane and its parent. When the parent’s HEAD moves ahead, ADE proactively surfaces a rebase suggestion on each affected child with:
  • The number of commits the child is behind
  • A preview of what the rebase will touch
  • Whether the rebase is likely to conflict (based on merge simulation)
Suggestions are generated by the auto-rebase suggestion service which watches upstream branch activity and computes behind-counts automatically. A compact banner above the lane list surfaces each affected child; from there you can View in Rebase tab to open the full rebase workspace, or Dismiss the suggestion if it isn’t relevant. Starting the actual rebase, choosing its scope, resolving conflicts, and triggering pushes all happen inside the Rebase tab — the lane-list banner stays a notification surface, not a one-click action bar.

​
Rebase Scope

When you start a rebase, ADE offers two scopes:
ScopeBehavior
Lane only (lane_only)Rebases just the selected lane onto its updated parent. Child lanes below it are not touched.
Lane and descendants (lane_and_descendants)Rebases the selected lane, then propagates through every descendant in dependency order. This is the “rebase the whole stack” action.

​
How Stack Rebase Works

For a lane_and_descendants rebase, ADE creates a Rebase Run — a tracked operation that processes each lane in the chain sequentially:
1

Start from the target lane

ADE rebases the selected lane onto its parent’s current HEAD using git rebase.
2

Walk the descendants

For each child lane in dependency order, ADE rebases it onto its parent’s updated HEAD. The order is deterministic — children are processed in creation order within each level.
3

Handle conflicts

If a conflict is detected during any lane’s rebase, that lane enters conflict status and the run pauses. You resolve the conflict in that lane’s worktree, then resume. Lanes below the conflicting lane are marked blocked until the conflict is resolved.
4

Optional push

After a successful rebase, ADE can force-push each rebased lane’s branch to its remote. You choose the push mode (none or review_then_push) when starting the rebase.
Each Rebase Run tracks per-lane status (pending, running, succeeded, conflict, blocked, skipped), pre/post HEAD SHAs, and any errors. You can inspect the run in the Rebase tab or the History view.
ADE uses git rebase (not git rebase --onto) for standard stack rebases. If conflicts occur, ADE aborts the rebase on that lane and enters conflict status rather than leaving the worktree in a partially-rebased state. The previous state is always recoverable.

​
Rollback

If a rebase run produces unexpected results, you can roll it back. ADE records the pre-rebase HEAD SHA for each lane in the run, so rollback restores each lane to its exact state before the rebase started.

​
Drag-to-Reparent

In the Workspace Graph, you can restructure a stack by dragging a lane node onto a different parent.
1

Open the Workspace Graph

Navigate to the Workspace Graph view from the sidebar.
2

Drag a lane node

Click and drag a lane node onto the lane you want as its new parent.
3

Confirm the reparent

ADE previews the operation and asks for confirmation. The preview shows:
  • The old parent and new parent
  • Whether a rebase is needed (it usually is)
  • Any potential conflicts detected by merge simulation
4

ADE executes the reparent

ADE updates the lane’s base branch reference, then rebases the lane onto the new parent’s HEAD. If the rebase fails due to conflicts, ADE aborts and reverts the base branch reference — the lane stays with its original parent.
You cannot reparent the primary lane, reparent a lane to itself, or create a circular dependency (e.g., making a parent lane a child of one of its descendants). ADE validates all of these cases before executing the reparent.

​
Stacked PRs

Stacks and stacked PRs are closely related. When you open a PR from a lane in a stack, ADE automatically targets the parent lane’s branch (not main). When the base PR merges into main, ADE suggests retargeting the next child PR to main and rebasing. See the Stacked PR Workflows guide for the full end-to-end workflow including landing strategies.

​
Tips

  • Keep stacks shallow. 2-3 levels is the sweet spot. Beyond 4 levels, rebase chains become slow and conflicts multiply.
  • Rebase frequently. Accept rebase suggestions promptly — the longer you wait, the more likely conflicts become.
  • Use the Graph. The Workspace Graph gives the best overview of stack health. Status badges tell you at a glance which lanes need attention.
  • Land from the bottom. Always merge the base PR first, then retarget and merge upward. Landing out of order creates unnecessary conflicts.

​
Next Steps

Stacked PR Workflows

Full guide for creating, reviewing, and landing stacked PRs using ADE lanes.

Workspace Graph

Visualize stacks, run merge simulations, and drag-reparent lanes in the interactive graph.