Recipes¶

Workflows¶

Create branches without committing¶

v0.5.0

The default workflow for git-spice forces you to commit immediately to new branches: gs branch create will create a new branch, and commit staged changes to it immediately, or if there are no staged changes, it will create an empty commit.

If you have a workflow where you prefer to create branches first, and then work on them, you can use the following to adjust the workflow:

Configure gs branch create to never commit by default by setting spice.branchCreate.commit to false.
```
git config --global spice.branchCreate.commit false
```
Use gs branch create as usual to create branches. Changes will not be committed automatically anymore.
```
gs branch create my-branch
```
If, for some branches, you do want to commit staged changes upon creation, use the --commit flag or -m/--message (which always implies --commit).
```
gs branch create my-branch --commit
gs branch create my-branch -m "Commit message"
```

Working with unsupported remotes¶

v0.6.0

If you're using a Git hosting service that is not supported by git-spice (e.g. Bitbucket, SourceHut, etc.), you can use git-spice to manage your branches locally without any issues. However, when it comes to pushing branches to the remote, there are some options that can help your workflow.

Stop git-spice from trying to submit changes to the service by setting spice.submit.publish to false.
```
git config spice.submit.publish false
```
gs repo sync will detect branches that were merged with merge commits or fast-forwards, and delete them locally. For branches that were merged by rebasing or squashing, you'll need to manually delete merged branches with gs branch delete.

Tasks¶

Import a Pull Request from GitHub¶

git-spice can recognize and manage GitHub Pull Requests that were not created using git-spice.

Steps:

Check the PR out locally. For example, if you're using the GitHub CLI:
```
gh pr checkout 123
```
Track the branch with git-spice.
```
gs branch track
```
Attempt to re-submit the branch. git-spice will automatically detect the existing open PR for it, and associate the branch with that PR.
```
gs branch submit
```

Track an existing stack¶

If you have an existing, manually managed stack of branches, you can import it into git-spice in one of two ways:

With gs downstack track (recommended)With gs branch track (manual)

Unreleased

The fastest way to track an existing stack is to use gs downstack track from the topmost branch.

Steps:

Check out the topmost branch.
```
git checkout feat3
```
Verify that the branches in the stack are reachable from each other in the correct order. You can use git log --graph or a visual tool for this.
```
git log --oneline --graph
```
Track the entire stack at once.
```
gs downstack track
```
This will look for branches down the commit history and prompt you to track branches as it encounters them.
You may now use git-spice to manage the stack as usual.

You can also track each branch individually with repeated use of gs branch track.

Steps:

Check out the base branch and initialize git-spice.
```
git checkout main
gs repo init
```
Check out the first branch in the stack and track it.
```
git checkout feat1
gs branch track
```

Repeat the previous step for each branch in the stack.

git checkout feat2
gs branch track
# ... repeat until done ...

You may now use git-spice to manage the stack as usual.