Skip to content

Working with remote repositories

Note

This page assumes you are using one of the supported Git forges. These are:

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:

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.

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.

Example of a stack navigation comment on GitHub

Example of a stack navigation comment on GitLab

This behavior may be changed with the spice.submit.navigationComment configuration key.

Stack history in navigation comments

v0.10.0 When possible, git-spice will remember CRs as they're merged into trunk, and continue to list them in navigation comments of branches based on those changes. However, it is unable to do this following complex stack manipulation operations.

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

v0.2.0

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.

Update existing CRs only

v0.10.0

All submit commands support the --update-only flag. If provided, the submission will update existing CRs in a stack, but not create new ones.

This is most convenient with gs stack submit and friends, allowing you to iterate on a local change that isn't ready for submission, while still being able to pull updates into downstack PRs that have already been submitted.

Example workflow

Suppose we're starting with a stack:

main -> bird (#1) -> fish (#2) -> goat

bird and fish have already been submitted, goat is in-progress.

Tip

The above example makes use of the -n/--dry-run flag of the stack navigation commands. With this flag, the command prints the hash of the target branch without checking it out.

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.

Handling closed Change Requests

When running gs repo sync, if a Change Request was closed (but not merged), git-spice will detect this and offer you the choice of deleting that branch locally.

If you prefer not to be prompted about closed CRs, you can set the configuration option to ignore them:

For more details, see the configuration reference.

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.

Importing stacks of CRs

Unreleased

If you have a stack of related CRs to import, check out all the branches locally and use gs downstack track to track them all at once.

See also Recipes > Track an existing stack.