Recipes¶
Workflows¶
Create branches without committing¶
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.gs branch create my-branch --commit
Working with non-GitHub remotes¶
If you're using a Git hosting service that is not GitHub (e.g. GitLab, Bitbucket, 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 create GitHub Pull Requests 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 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.