A fork of spacedentist/spr. See Fork Documentation for the differences.
A command-line tool for submitting and updating GitHub Pull Requests from local Git commits that may be amended and rebased. Pull Requests can be stacked to allow for a series of code reviews of interdependent code.
spr is pronounced /ˈsuːpəɹ/, like the English word 'super'.
Comprehensive documentation of the original tool is available here: https://getcord.github.io/spr/. It describes the original behaviour; see Fork Documentation for where this fork differs.
| Difference | Detail |
|---|---|
| No intermediate base branch | PR2 is based on PR1's branch. More |
| Native GitHub stacks | The chain is registered with GitHub. More |
Depends On in the PR body |
Links the stacked PR to its base. More |
--base |
Base a PR on any branch or lower commit. More |
| Base branch persistence | Pass --base once, not on every update. More |
| Interactive base selection | Prompts when --base is omitted. More |
| Interactive commit selection | --all prompts for commits. More |
[COMMIT] argument |
Target one commit without a prompt. More |
spr sync |
New. Pulls remote PR changes into local commits. More |
spr merge |
New. Enables auto-merge; requires gh. More |
spr land |
Removed. Use spr merge. |
| Cherry-pick by default | --no-cherry-pick uses an intermediate base branch. More |
| Dirty worktree allowed | spr diff no longer refuses. More |
| Pre-push hook runs | Skip it with --no-verify. More |
| Signatures preserved | Git signature and committer are kept. More |
Live git push output |
Shown as it runs. More |
| No title/message prompt | Never asks when they differ. More |
requireTestPlan defaults to false |
More |
When creating stacked PRs, unlike the original spr creating an intermediate base branch, PR2 just uses the branch of PR1 as its base branch. When the PR1 lands, the base branch in PR2 is automatically changed to main. This allows PR2 to land automatically after PR1 is landed without changing base or rerunning CI.
- If the stacked PR shows no conflicts, we do not need to rebase or rerun CI in order to merge it.
- If the stacked PR shows conflicts, we do not need to actually resolve any conflicts.
git pull --rebase && spr diffwill update the stacked PR. CI needs to rerun.
A base PR link is automatically appended to the stacked PR’s body. GitHub automatically tracks the base PR's status. Stacked PR is automatically mentioned in the base PR's conversation timeline.
For example, Depends On: #<Base PR Number>
If --base is not specified for new PR or you just do not like copy/paste, running spr diff for creating new PR automatically prompts users to select a base branch from lower local commits. This also means users just need to run the same command spr diff no matter creating or updating PRs. See the selection experience here.
Running spr diff --all prompts users to select all or some commits to create/update PRs. Pressing → key easily selects all commits when needed. This allows users to have multiple stacks in one branch and users can select the commits of a stack to update. This also allows users to update any commit in the history without using exec spr diff in an interactive rebase. See the multi-selection experience here.
Select base with parent HEAD references. This is useful when you have a series of new stacked commits and you can do spr diff --all --base HEAD^ to stack all of them. BTW, when you have a series of new independent commits and you can do spr diff --all --base main.
spr diff --base <any-branch-name>
spr diff --base <branch-name-of-other-people-PR>
spr diff --base HEAD^ --all
spr diff --base HEAD~2
Users only need to specify a base branch when creating a PR. Updating an existing PR will continue to use the same base branch on GitHub. If needed, existing PR’s base branches can be changed with --base.
spr merge runs gh pr merge <number>, enabling auto-merge on the PR of the HEAD commit. It requires the GitHub CLI to be installed and authenticated. Like spr diff, spr merge --all prompts for commits and spr merge <commit> takes one.
spr land is removed. Use spr merge.
spr diff registers the chain as a GitHub stack, so GitHub shows a stack map and re-targets the remaining PRs when the bottom one merges.
This happens automatically whenever each PR's base is the branch of the PR below it. Commits based on the master branch are not a stack, and neither are chains using an intermediate base branch (--no-cherry-pick). If GitHub rejects the stack, spr warns and carries on; the PRs are still updated.
Reordering a stack, or moving a PR onto a different base, needs --base. spr takes the PR out of its stack first, because GitHub refuses to re-target a stacked PR. GitHub has no endpoint to remove a single PR, so the whole stack is dissolved and rebuilt from whatever chain the run still covers.
--all needs a terminal, which scripts and agents do not have. diff, merge and sync also accept a single commit:
spr diff HEAD~2
spr diff 4b8f5ef
spr merge HEAD~1
spr sync HEAD~2The commit must be in the local stack, cannot be combined with --all, and cannot be a range. Commit ids change when spr writes the Pull Request: line, so re-read them after each command that writes.
spr sync pulls changes made on GitHub back into the local commits, for example after someone pushed to a PR branch or applied a suggestion.
spr sync # HEAD commit
spr sync --all # prompt for commits
spr sync HEAD~2 # one commit
spr sync --dry-run # report changes without writingUnlike spr diff, spr sync checks out a new tree and so requires a clean worktree.
spr diff runs with uncommitted changes; the original spr refuses. It never checks out a tree, and the commits it writes keep the tree of the commits they replace, so the worktree is left untouched. spr sync still requires a clean worktree.
spr diff runs the pre-push hook, which the original spr does not. Use spr diff --no-verify to skip it.
Commits written by spr keep your Git signature and follow Git's committer precedence rules.
Output from git push and the pre-push hook is shown as it runs.
Use cherry-pick by default. Add --no-cherry-pick to create an intermediate base branch.
Almost all the time users update PR summary in GitHub directly. Some workflow has no point in keeping them in sync. So the fork does not prompt when title/message differ.
It does not work well with #Test Plan in markdown.
Homebrew, Nix and crates.io carry the original tool, not this fork.
curl -fsSL https://raw.githubusercontent.com/HongboDu-at/spr/main/install.sh | shInstalls the latest release into $HOME/.local/bin. Set SPR_VERSION (e.g. 1.3.4-enhanced.1) or SPR_INSTALL_DIR to override. Binaries are built for Linux on x86_64 and arm64, and macOS on arm64, and can also be downloaded from the releases page.
spr is written in Rust. You need a Rust toolchain to build from source. See rustup.rs for information on how to install Rust if you have not got a Rust toolchain on your system already.
With Rust all set up, clone this repository and run cargo build --release. The spr binary will be in the target/release directory.
To use spr, run spr init inside a local checkout of a GitHub-backed git repository. You will be asked for a GitHub PAT (Personal Access Token), which spr will use to make calls to the GitHub API in order to create and merge pull requests.
To submit a commit for pull request, run spr diff.
If you want to make changes to the pull request, amend your local commit (and/or rebase it) and call spr diff again. When updating an existing pull request, spr will ask you for a short message to describe the update.
To enable auto-merge on an open pull request, run spr merge, which requires the GitHub CLI. spr land is removed.
For more information on spr commands and options, run spr help. For more information on a specific spr command, run spr help <COMMAND> (e.g. spr help diff).
Feel free to submit an issue on GitHub if you have found a problem with this fork. If you can even provide a fix, please raise a pull request! For problems in the original tool, use spacedentist/spr.
If there are larger changes or features that you would like to work on, please raise an issue on GitHub first to discuss.
spr is MIT licensed.