Working with Pull Requests¶
Note
This page assumes you're using git-spice with GitHub. If you're using a different Git hosting service, you can still use git-spice, but some features may not be available.
See:
Submitting pull requests¶
When your local changes are ready, use the following commands to submit your changes upstream:
- gs branch submit (or gs bs) submits the current branch
- gs downstack submit (or gs dss) submits the current branch and all branches below it
- gs upstack submit (or gs uss) submits the current branch and all branches above it
- gs stack submit (or gs ss) submits all branches in the stack
Branch submission is an idempotent operation: pull requests will be created for branches that don't already have them, and updated for branches that do.
For new pull requests, these commands will prompt you for PR information. For example:
Important
Be aware that for stacks with multiple branches, you must have write access to the repository so that you can push branches to it. See Limitations for more information.
Navigation comments¶
Pull Requests created by git-spice will include a navigation comment at the top with a visual representation of the stack, and the position of the current branch in it.
This behavior may be changed with the spice.submit.navigationComment configuration key.
Non-interactive submission¶
Use the --fill flag (or -c since v0.3.0)
provided by all the above commands
to fill in the PR information from commit messages
and skip the interactive prompts.
Additionally, with gs branch submit, you may also specify title and body directly.
Setting draft status non-interactively
Pull requests may be marked as draft or ready for review
non-interactively with the --draft and --no-draft flags.
By default, the submit commands will leave
the draft state of existing PRs unchanged.
If the --draft or --no-draft flags are provided,
the draft state of all PRs will be set accordingly.
Force pushing¶
By default, git-spice will refuse to push to branches
if the operation could result in data loss.
To override these safety checks
and push to a branch anyway, use the --force flag.
Syncing with upstream¶
To sync with the upstream repository, use gs repo sync (or gs rs).
This will update the trunk branch (e.g. main)
with the latest changes from the upstream repository,
and delete any local branches whose PRs have been merged.
Importing pull requests¶
You can import an existing PR into git-spice by checking it out locally, tracking the branch with git-spice, and re-submitting it.
For example, if you have the GitHub CLI installed:
Important
For this to work, the following MUST all be true:
- The PR is pushed to a branch in the upstream repository
- The local branch name exactly matches the upstream branch name
This will work even for PRs that were not created by git-spice, or authored by someone else, as long as the above conditions are met.
In v0.5.0 or newer, this will also auto-detect navigation comments posted to the PR by git-spice, and update them if necessary.