Git: Banishing Stacked Pull Request Demons

A software engineer's guide to sane feature layering

As software engineers, we often find ourselves in a productivity paradox. You finish a solid chunk of work and ship it off for review. But the review cycle is a slow-moving beast, and you can’t just sit on your hands. So, you do the logical thing: you start the next task, which is dependent on the first. You’ve just started a "stack."

Everything is fine until the dreaded PR comment arrives. A suggestion is made to the underlying foundation of your work. You address it, and suddenly... BAM. Conflicts.

Instead of a clean workflow, you’re forced into a series of dark Git incantations to summon the delta of commits up from the seventh circle of Git hell. You git switch, git commit --amend, and then attempt the surgical git rebase --onto to transmute your dependent second-branch into a proper, elegant human. If you're lucky, it works. If you're not, you’re left with a mutant homunculus born of unwise rebase choices and manual conflict resolution.

There is an easier way for us mere mortals. If your organization is savvy enough to use GitHub, a dedicated tool called Aviator (av) can handle the heavy lifting of stacked diffs for you. It is open-source, free to use, and turns those complex rebases into a simple, automated process.

The New Incantations: A Technical Breakdown

To replace the manual "surgery" with automation, av uses a hybrid approach: you use standard Git for your logic and av for the structural "plumbing."

1. Initialize the Altar

Before you start stacking, initialize your repository. This connects the CLI to your GitHub metadata (using your existing gh credentials).

av init

2. Laying the Foundation

Instead of git checkout -b, use av branch. This "tags" the branch in the tool's metadata so it knows exactly who the parent is.

av branch first-branch
# ... make changes ...
git commit -m "Add API layer"

3. Building the Tower

Stay on your current branch and create the next layer. av automatically recognizes the current branch as the parent.

av branch second-branch
# ... make changes ...
git commit -m "Add UI component"

4. The Ritual of Synchronization

When a PR comment forces you to change first-branch:

1. Switch: git checkout first-branch

2. Fix: Address the comments and git commit (or amend).

3. The Cleanse: Run the synchronization command:

av sync

av sync identifies that the foundation has moved, calculates the new delta, and automatically rebases your dependent second-branch onto the new head of its parent.

5. Ascending to GitHub

To push your work without manually managing "Base Branch" settings in the GitHub UI:

av pr

This pushes your entire stack and tells GitHub exactly which branch each PR depends on. Reviewers only see the incremental diff for each layer, keeping reviews fast and focused.

The Verdict

I’ll be integrating this into my workflow over the next few weeks to see how it holds up against the chaos of real-world remote dev life.

Check out the Aviator CLI Documentation to try it yourself.