Stacked PRs CLI | Aviator Documentation

Aviator is a suite of productivity tools purpose-built to reduce friction in development workflows.

av

is an open-source CLI built and managed by Aviator to interact with GitHub and Aviator service. The primary use case is creating and managing Stacked PRs. Managing stacked PRs using Aviator CLI The Stacked PRs CLI does not require creating an Aviator account and can be installed directly . 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!). Learn more about the cultural implication of using Stacked PRs in our blog post . 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: For installation on other platforms or step by step guide, please checkout installation instructions . av CLI needs a GitHub credential for creating and updating PRs. Install GitHub CLI , 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 . Finally, initialize the repository so that CLI can start tracking your active branches. 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. To create the PR, also use the

av pr

command to ensure that the correct base branch is set in the 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

. 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. Already have git branches created? Take a look at How to Adopt a Branch in CLI . 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. Then, we can make edits and commit as usual. Finally, we can run

av sync

to propagate the changes to all children branches. 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: Sign up for a free account with Aviator Walk through the initial steps, and install the Aviator app on GitHub Navigate to user access token page: https://app.aviator.co/account/apitoken Generate a token and add it to your configuration file at

~/.av/config.yaml

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: 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: In addition, all commands also provide in-line help: Advanced guides This is just a quick preview of things you can do with the Aviator CLI. Check our our how to guides for more specific use cases: Split and fold branches Adopt a branch that was created without av Navigating the stack Renaming a branch Setting up auto-complete Previous Status Codes Next Quickstart for Stacked PRs CLI Last updated 1 year ago Was this helpful?

The technical content provided is mostly clear and well-structured, but there are a few areas that could be improved for clarity and accuracy:

1. Code Block Formatting: The code blocks are not consistently formatted. For example, the command av is presented in a separate code block, which might be unnecessary. It could be included inline with the text for better readability.

2. Command Descriptions: The description of the av branch command is a bit unclear. It mentions creating a branch on top of the current branch, but it might be helpful to specify that this is the branch currently checked out in the local repository.

3. Inconsistent Terminology: The term "stack parent" is used in the context of the av sync command. It might be clearer to refer to it as the "parent branch in the stack" to maintain consistency with the rest of the document.

4. Missing Installation Instructions: The text mentions checking out installation instructions for other platforms but does not provide a link or reference to where these instructions can be found.

5. GitHub Credential Setup: The section on GitHub credentials could be more explicit. It mentions using the GitHub CLI or a Personal Access Token but does not provide detailed steps or a link to instructions for setting up these credentials.

6. Aviator MergeQueue Setup: The instructions for setting up the Aviator MergeQueue are somewhat abrupt. It might be helpful to provide more context or a step-by-step guide, especially for users unfamiliar with setting up API tokens.

7. Typographical Errors:

   • "Check our our how to guides" should be "Check out our how-to guides."
   • "For instance, on Mac you can use Homebrew:" is incomplete as it doesn't provide the actual command to install using Homebrew.

8. Link References: The document mentions several resources like "installation instructions," "How to Create an Access Token," and "how to guides" without providing actual links. Including hyperlinks would improve usability.

9. Man Pages and Help Docs: The section on man pages and help docs is incomplete. It mentions that man pages are available but does not provide instructions on how to access them.

10. Last Updated Note: The "Last updated 1 year ago" note at the end might be outdated. It would be beneficial to ensure this information is current.

Overall, the content is informative, but addressing these points would enhance clarity and usability for the reader.

No product messaging analysis available for this page.

No competitive analysis available for this page.