Local development with branch stacks¶
Stacking branches¶
Starting at the trunk branch, any number of branches may be stacked on top. git-spice learns about the relationships between branches by 'tracking' them in an internal data store. Branches may be tracked manually or automatically:
Automatic stacking¶
The preferred way to create and track a stacked branch is with gs branch create. The steps are simple:
- Modify your code and prepare your changes to be committed with
git add. - Run gs branch create.
This will create a new branch stacked on top of the current branch,
commit the staged files to it, and track it with the current branch as base.
An editor will open to let you write a commit message
if one was not provided with the -m/--message flag.
But I use git commit -a
If you prefer to use git commit -a to automatically stage files
before committing, use gs branch create -a to do the same with git-spice.
Explore the full list of options at gs branch create.
Creating branches without committing
If you prefer a workflow where you create branches first and then work on them, you can configure git-spice to never commit by default. See Create branches without committing.
Manual stacking¶
git-spice does not require to change your workflow too drastically. If you prefer to use your usual workflow to create branches and commit changes, use gs branch track to inform git-spice of the branch after creating it.
For example, you may:
- Create a new branch with
git checkout -b. - Make changes and commit them with
git commit. - Run gs branch track to track the branch.
The gs branch track command automatically guesses the base branch
for the newly tracked branch.
Use the --base option to set it manually.
Naming branches¶
We advise picking descriptive names for branches. You don't need to remember the exact names as git-spice provides a number of utilities to help navigate and manipulate the stack. Most places where a branch name is required provide shell completion and fuzzy-searchable lists.
Can't think of a branch name?
If you can't think of a name for a branch, run gs branch create without any arguments. git-spice will use the commit message to generate a branch name for you.
Navigating the stack¶
git-spice offers the following commands to navigate within a stack of branches:
- gs down checks out the branch below the current branch
- gs up checks out a branch stacked on top of the current branch, prompting to pick one if there are multiple
- gs bottom moves to the bottommost branch in the stack, right above the trunk
- gs top moves to the topmost branch in the stack, prompting to pick one if there are multiple
- gs trunk checks out the trunk branch
- gs branch checkout checks out any branch in the repository
These commands allow for relative movement within the stack, so that you don't have to remember exact branch names or their positions in the stack.
What's the value of gs branch checkout?