stack-pr

Stacked PRs allow you to group related changes into a sequence of dependent pull requests. Instead of one large PR containing all changes (e.g., A+B), you create a stack where the first PR contains only change A, and the second PR contains only change B (which depends on A). This makes individual changes easier to review and manage.

Under the hood, stack-pr creates branches following the pattern $USERNAME/stack/$BRANCH_NUM and embeds metadata into commit messages. You should interact with the stack using the provided CLI commands rather than manually editing branches or metadata.

Before installing stack-pr, ensure you have the GitHub CLI (gh) installed and configured with SSH authentication (gh auth login).

Installation via pipx

Recommended method:

pipx install stack-pr

Manual installation from source

Clone the repository and run:

pipx install .

You can define default values for command line options in a configuration file. By default, stack-pr looks for .stack-pr.cfg in the current directory. You can override this location by setting the STACKPR_CONFIG environment variable.

Example .stack-pr.cfg structure:

[common]
verbose=True
hyperlinks=True
draft=False
keep_body=False
stash=False
show_tips=True
[repo]
remote=origin
target=main
reviewer=GithubHandle1,GithubHandle2
branch_name_template=$USERNAME/$BRANCH
[land]
style=bottom-only

The abandon command is used to discard a stack of PRs. For all commits in the stack that contain valid stack-info, it performs the following:

1. Closes the corresponding GitHub PR.
2. Deletes the associated remote and local branches.
3. Removes the stack-info metadata from the commit messages.

stack-pr abandon

The submit command automates the process of turning a sequence of local commits into a stack of interconnected GitHub Pull Requests.

Workflow:

1. It identifies the merge-base between your current branch and the target branch (e.g., main).
2. For each commit in the stack, it creates a new head branch and a corresponding PR.
3. It sets the base branch of each PR to the head branch of the previous PR in the stack (or main for the first one).
4. It annotates commit messages with stack-info metadata to maintain the stack relationship.
5. It pushes all branches to the remote and adds cross-links in the PR descriptions to create a Table of Contents (TOC) for the stack.

Note: If the command succeeds, your commits will be annotated with links to the PRs and the names of the head branches.

stack-pr submit

The land command merges all PRs in a stack into the target branch (e.g., main) and cleans up the repository.

Workflow:

1. It verifies that all commits in the stack have valid stack-info metadata.
2. For each commit in the stack (from oldest to newest):
   • It sets the base branch to point to main.
   • It merges the corresponding PR.
3. Upon success, it deletes all corresponding local and remote branches.

Tip: If you want to land only a specific subset of the stack, you can use the -B (base) and -H (head) options to specify the range of revisions.

stack-pr land

By default, stack-pr operates on the range main..HEAD. You can override this using the following flags for all commands (including view, submit, and land):

• -B <range>: Sets the Base (the starting point of the range). Default is local main.
• -H <range>: Sets the Head (the end point of the range). Default is local HEAD.
• -T <range>: Sets the Target (the branch to rebase onto). Default is origin/main.

Example usage:

# Submit a stack of the last 5 commits
stack-pr submit -B HEAD~5

# Use origin/main as the base
stack-pr submit -B origin/main

# Exclude the last two commits from the stack
stack-pr submit -H HEAD~2

stack-pr view -B HEAD~5 -H HEAD~2
stack-pr submit -B HEAD~5
stack-pr land -B HEAD~5 -H HEAD~2

When running stack-pr submit, you can use several flags to control how PRs are created:

• --draft: Marks all created PRs as drafts.
• --draft-bitmask <bitmask>: Marks specific PRs as drafts using a bitmask (e.g., --draft-bitmask 0010 makes the third PR in a stack of four a draft). The bitmask length must match the number of PRs.
• --reviewer="handle1,handle2": Assigns specific GitHub handles as reviewers to the PRs.

stack-pr submit --draft
stack-pr submit --draft-bitmask 0010
stack-pr submit --reviewer="user1,user2"

The following arguments can be used with any stack-pr subcommand:

-R, --remote: Remote name (default: "origin")
-B, --base: Local base branch
-H, --head: Local head branch (default: "HEAD")
-T, --target: Remote target branch (default: "main")
--hyperlinks/--no-hyperlinks: Enable/disable hyperlink support (default: enabled)
-V, --verbose: Enable verbose output from Git subcommands (default: false)
--branch-name-template: Template for generated branch names (default: "$USERNAME/stack"). Supported variables:
   - $USERNAME: The username of the current user
   - $BRANCH: The current branch name
   - $ID: The location for the ID of the branch (determined by creation order). If $ID is not in the template, it is appended as /$ID.

The stack-pr CLI provides five primary commands:

• submit (alias: export): Creates a new stack of PRs from the specified commits or updates existing PRs to match local changes. It pushes local branches to remote and syncs them with GitHub.
• view: Inspects the commits in the current range and identifies linked PRs. This is a safe, read-only command used to verify the stack state.
• abandon: Removes stack metadata from commits, deletes corresponding local and remote branches, and closes the associated PRs.
• land: Merges the bottom-most PR in the stack and automatically rebases the remaining PRs on the latest main.
• config: Manages configuration values in the .stack-pr.cfg file using <section>.<key>=<value> syntax.

Available subcommands for managing stacked PRs:

submit (alias: export): Submit a stack of PRs.
  --keep-body: Keep current PR body, only update cross-links (default: false)
  -d, --draft: Submit PRs in draft mode (default: false)
  --draft-bitmask: Bitmask for setting draft status per PR
  --reviewer: List of reviewers for the PRs (default: from $STACK_PR_DEFAULT_REVIEWER or config)
  -s, --stash: Stash all uncommitted changes before submitting the PR

land: Land the bottom-most PR in the current stack. (Note: unavailable if land.style is set to 'disable')

abandon: Abandon the current stack.

view: Inspect the current stack.

config: Set a configuration value in the format <section>.<key>=<value>.