Working with remote repositories¶
Note
This page assumes you are using one of the supported Git forges. These are:
- GitHub
- GitLab (v0.9.0)
If you're using a different service, you can still use git-spice, but some features may not be available.
See:
Submitting change requests¶
Info
git-spice uses the term Change Request to refer to submitted branches. These corespond to Pull Requests on GitHub, and to Merge Requests on GitLab.
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: change requests will be created for branches that don't already have them, and updated for branches that do.
For new change requests, these commands will prompt you for CR 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¶
Change 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
Change 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 open CRs¶
You can import an existing open CR into git-spice by checking it out locally, tracking the branch with git-spice, and re-submitting it.
For example:
Important
For this to work, the following MUST all be true:
- The CR is pushed to a branch in the upstream repository
- The local branch name exactly matches the upstream branch name
This will work even for CRs 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.