LogoLogo
HomeAbout usSign up
  • Introduction
  • AttentionSet
    • AttentionSet Best Practices
    • How to View AttentionSet for Others
    • How to Manually Change Attention
    • AttentionSet Chrome extension
    • Attention reasons
    • AttentionSet Slack Home Page
  • Releases
    • Getting Started with Releases
    • Concepts for Releases
      • Terminology for Releases
      • Two-step delivery
      • Rollbacks
      • Cherry-picks
      • Dogfood, Canary and Rollout
      • Release notes
    • How-to Guides for Releases
      • How to Create a Release Project
      • How to Configure Environments
      • How to Create a Scheduled Release
      • Create Custom Workflow Parameters
      • How to Manage Cherry-Picks
      • How to Resolve a Cherry-Pick Failure
      • Working with your CI / CD
        • GitHub Actions workflow
        • Buildkite workflow
    • API Reference for Releases
  • FlexReview
    • Getting Started with FlexReview
    • How to Onboard a Large Org
    • Concepts for FlexReview
      • Read-Only Mode in FlexReview
      • Recursive Ownership in FlexReview
      • Reviewer suggestion and assignment
      • FlexReview Teams and SLO Management
      • Validation in FlexReview
    • How-to Guides for FlexReview
      • How to Get a Reviewer Suggestion
      • How to Exclude Reviewers
      • How to Set Up Team Rules
      • Whitelist Teams for Review Assignment
      • Troubleshoot Reviewer Assignment
      • PagerDuty Integration for Reviewers
      • How to Set Up FlexReview Validation
      • Recommended Slack Notification Settings
      • How to Exclude OOO Reviewers
    • FlexReview Reference
      • Configuration
      • Slash commands
      • Expert scoring algorithms
      • Slack Notifications
      • Out of Office User Exclusion
    • FlexReview Roadmap
  • MergeQueue
    • Getting Started with MergeQueue
    • Merge Rules
    • How-to Guides for MergeQueue
      • How to Configure Base Branches
      • How to Customize Required Checks
      • How to Set Up Fast-Forwarding
      • How to Set Up Pre-Queue Conditions
      • How to Queue / Dequeue via API
      • Pause / Unpause Queues via API
      • Slash Commands Using GitHub Comments
      • How to Customize Sticky Comments
      • Require an Aviator Status Check
      • Backport a PR
      • How to Configure ChangeSets
      • Custom Integrations
        • GitHub Integration
      • How to Create Personal Access Tokens
      • How to Set Up SAML Configuration
        • Microsoft Active Directory
      • How to Merge Stacked PRs
      • How to Block Pull Request Mergeing with Slash Commands
    • Concepts for MergeQueue
      • Queue Modes
      • Pull Request Lifecycle
      • Analytics
      • Parallel Mode
      • CI Status Requirements
      • MQ Created Branches
      • Batching
      • Managing flaky tests
      • Fast-forwarding
      • Pre-Queue Conditions
      • Sticky Comments
      • Backporting
      • Paused Queues
      • Affected Targets
        • Directory-Based Affected Targets
        • nx based affected targets
        • GitHub Actions based Affected Targets
      • ChangeSets
        • Global CI Validation
        • ChangeSets FAQs
      • Priority Merges
        • Instant Merges
      • Merge Rules Audit Trail
      • Timeline
      • Ready Hook
      • Reduce Queue Failures From Staleness
    • MergeQueue References
      • Configuration Schema
      • Configuration Reference MergeQueue
      • GitHub Slash Commands
      • Status Codes
  • Stacked PRs CLI
    • Quickstart for Stacked PRs CLI
    • CLI Installation
    • How-to Guides for Stacked PRs CLI
      • How to Create Stacked PRs in CLI
      • How to Navigate & Modify Stacked PRs
      • Add Commits in the Stack
      • How Split a Commit in CLI
      • How to Split and Fold Pull Requests
      • How to Rename a Branch in CLI
      • How to Adopt a Branch in CLI
      • Orphan a Branch with Aviator CLI
      • How to Do Git Subcommand Aliasing
      • How to Create an Access Token
      • How to Set Up Auto Completion in CLI
      • How to Use Editor Plugins in CLI
    • Concepts for StackedPRs CLI
    • How to Rebase and Sync with GitHub
    • Configuration for StackedPRs CLI
    • Stacked PRs FAQs and Troubleshooting
      • Working with Aviator CLI
      • Default Branch Update Master to Main
    • Manpages for Stacked PRs CLI
      • av(1)
      • av-adopt Command Guide
      • av-auth-status(1) in CLI
      • av-stack-branch(1) in CLI
      • av-commit-create(1) in CL
      • av-stack-diff(1) in CLI
      • av-fetch(1) in CLI
      • av-git-interaction Command Guide
      • av-init(1) in CLI
      • av-stack-next(1) in CLI
      • av-orphan Command Guide
      • av-pr-status(1) in CLI
      • av-pr-create(1) in CLI
      • av-stack-prev(1) in CLI
      • av-stack-reorder(1) in CLI
      • av-reparent Command Guide
      • av-restack Command Guide
      • av-commit-split(1) in CLI
      • av-switch Command Guide
      • av-stack-sync(1) in CLI
      • av-stack-tidy(1) in CLI
      • av-stack-tree(1) in CLI
    • Aviator CLI Major Releases
      • Aviator CLI v0.1.0 Release Notes
  • Aviator's Chrome Extension
  • Pilot Automated Actions
    • Scheduled Events
    • JavaScript Execution
    • Pilot Automated Actions Reference
      • GitHub Reference
      • MergeQueue Reference
      • Slack Reference
  • API and Integrations
    • Slack Integration Guide
    • GraphQL API Quickstart
    • Prometheus Metrics Setup for GCP
    • Reference
      • JSON API
      • GraphQL
      • Webhooks
      • Monitoring Metrics
  • Manage
    • Access Management
    • GitHub App Permissions
    • Security
      • Aviator Agents Data Usage & Retention Policy
    • On-Premise Installation
      • GitHub App for On-Prem
      • GitHub OAuth for On-Prem
      • Use Helm Instructions
      • Use Docker Compose Instructions
      • Prometheus endpoint
      • Slack Integration for On-Premise
      • Google SSO Login for On-Prem
    • FAQs
      • Troubleshooting GitHub app connection
      • MergeQueue FAQs
      • Billing FAQs
Powered by GitBook
On this page
  • Why stacked PRs
  • Getting started
  • Creating a stack
  • Updating the stack
  • Merging the stack
  • Setting up Aviator MergeQueue
  • Man pages and help docs
  • Advanced guides

Was this helpful?

Stacked PRs CLI

Get instructions on managing stacked PRs with Aviator's open-source CLI in the Aviator documentation. Create, update, and merge a stack using Aviator.

PreviousStatus CodesNextQuickstart for Stacked PRs CLI

Last updated 5 months ago

Was this helpful?

Aviator is a suite of productivity tools purpose-built to reduce friction in development workflows. av is an built and managed by Aviator to interact with GitHub and Aviator service. The primary use case is creating and managing Stacked PRs.

The Stacked PRs CLI and can be .

Why stacked PRs

Stacked PRs are useful when you have a lot of code changes that are hard to review in a single PR. Stacked PRs let you break down the changes into smaller PRs that are "stacked" on top of each other, keeping code review manageable. This means you can keep working on the next bit of code related to a feature even while waiting for your previous PR(s) to pass CI, be approved, and merged!

For example, if PR1 is Add the /books/list route to the backend and PR2 is Show the books list in the frontend, we can stack PR2 on top of PR1. This means that you don’t have to wait for PR1 to be reviewed and merged before you can start PR2 (and they can even be reviewed by separate people!).

Getting started

You don’t need an Aviator account to start using the CLI. You can simply install the CLI using your OS package manager. For instance, on Mac you can use Homebrew:

brew install aviator-co/tap/av

Finally, initialize the repository so that CLI can start tracking your active branches.

av init

Creating a stack

Creating the first branch in the stack is just the same as creating any normal branch in your repository, except now you use the av CLI. The av branch command requires one argument which is the name of the branch to create. This command will create a branch on top of the current branch.

# Create a new branch off of your repository default branch
# (usually main or master)
av branch "bookstore-backend"

# Now we can do our development work as normal.
mkdir ./books
echo '...' >> ./books/backend.py
git add ./books
git commit -m "Add /books/list route to backend"

To create the PR, also use the av pr command to ensure that the correct base branch is set in the PR.

av pr

For the next branch, we use the av branch command again, except this time we're branching from bookstore-backend instead of main since we want to build off of our previous work. Behind the scenes, the CLI sets some internal data to be able to recognize that bookstore-frontend is dependent on bookstore-backend.

​​av branch "bookstore-frontend"

And when it comes time to submit our work as PR, we use the av pr command again.

When creating this PR, the CLI again automatically sets the base branch in GitHub as bookstore-backend rather than main to ensure that GitHub shows the diff between bookstore-frontend and bookstore-backend. Otherwise, it would show all the changes from bookstore-backend in the PR for bookstore-frontend which would make code review much harder.

Updating the stack

Since stacked PRs are designed to make code review easier and more incremental, it's likely that you'll need to change code that you wrote earlier in the stack. The av sync command is used to make sure every branch is up-to-date with its stack parent.

To edit a branch that is part of a stack, first we need to check it out.

git checkout bookstore-backend

Then, we can make edits and commit as usual.

echo '...' >> ./books/backend.py
git add ./books
git commit -m "Fix 500 error on malformed input"

Finally, we can run av sync to propagate the changes to all children branches.

av sync

Merging the stack

Merging a stack with Aviator is a little different than merging a non-stacked PR. Although you can merge PRs now manually one at a time, the best way to merge the PRs is to use Aviator MergeQueue.

Setting up Aviator MergeQueue

Aviator MergeQueue is purpose built as a highly scalable stack-aware merge queue. Follow these steps to connect the CLI with Aviator:

  1. Walk through the initial steps, and install the Aviator app on GitHub

  2. Generate a token and add it to your configuration file at ~/.av/config.yaml

~/.av/config.yaml
aviator:
    apiToken: "av_uat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

With that, now to merge a partial or full stack, just queue the top most PR of the stack that you would like to merge:

av pr --queue

After this, Aviator will automatically validate the changes in the stack, and merge all the changes to the target branch (typically main or master). At any time, you can also review the state of your PR using av pr status.

Man pages and help docs

Aviator also publishes man pages, that you can read for more details on the commands:

man av-sync

In addition, all commands also provide in-line help:

$ av sync --help
Synchronize stacked branches to be up-to-date with their parent branches.

By default, this command will sync all branches starting at the root of the
stack and recursively rebasing each branch based on the latest commit from the
parent branch.

If the --all flag is given, this command will sync all branches in the repository.

If the --current flag is given, this command will not recursively sync dependent
branches of the current branch within the stack. This allows you to make changes
to the current branch before syncing the rest of the stack.

If the --rebase-to-trunk flag is given, this command will synchronize changes from the
latest commit to the repository base branch (e.g., main or master) into the
stack. This is useful for rebasing a whole stack on the latest changes from the
base branch.

Usage:
  av sync [flags]

Flags:
      --abort                  abort an in-progress sync
      --all                    synchronize all branches
      --continue               continue an in-progress sync
      --current                only sync changes to the current branch
                               (don't recurse into descendant branches)
  -h, --help                   help for sync
      --prune string[="ask"]   delete branches that have been merged into the parent branch
                               (ask|yes|no) (default "ask")
      --push string            push the rebased branches to the remote repository
                               (ask|yes|no) (default "ask")
      --rebase-to-trunk        rebase the branches to the latest trunk always
      --skip                   skip the current commit and continue an in-progress sync

Global Flags:
      --debug         enable verbose debug logging
  -C, --repo string   directory to use for git repository

Advanced guides

Learn more about the cultural implication of using Stacked PRs in our .

For installation on other platforms or step by step guide, please checkout .

av CLI needs a GitHub credential for creating and updating PRs. Install , and av CLI will use the same credential for interacting with GitHub. Alternatively, you can use a GitHub Personal Access Token. See How to Create an Access Token.

Already have git branches created? Take a look at How to Adopt a Branch in CLI

for a free account with Aviator

Navigate to user access token page:

This is just a quick preview of things you can do with the Aviator CLI. Check our our for more specific use cases:

blog post
installation instructions
GitHub CLI
.
Sign up
https://app.aviator.co/account/apitoken
how to guides
Split and fold branches
Adopt a branch that was created without av
Navigating the stack
Renaming a branch
Setting up auto-complete
open-source CLI
does not require creating an Aviator account
installed directly
Managing stacked PRs using Aviator CLI