Your first stack

With git-spice installed, start experimenting with stacking.

Initialize git-spice

1. Start by creating an new Git repository to play inside.

   mkdir repo
   cd repo
   git init
   git commit --allow-empty -m "Initial commit"
   

2. Initialize git-spice in the repository. This will set up the internal storage for git-spice in your repository.

   gs repo init
   

   Info

   This step isn't absolutely required. git-spice will initialize itself automatically when needed.

Track a branch

Next, stack a branch on top of main.

1. Create a new branch and make some changes:

   git checkout -b feat1
   echo "Hello, world!" > hello.txt
   git add hello.txt
   git commit -m "Add hello.txt"
   

2. Add the branch to git-spice.

   gs branch track
   

This results in a single branch stacked on top of main.

The above operations are frequently done together. git-spice provides a command to do all of them in one go: gs branch create.

Use gs branch create

Stack another branch on top of feat1 with gs branch create.

1. Check out feat1 and prepare another change:

   echo "This project is cool!" > README.md
   git add README.md
   

2. Create a new branch, commit the staged changes, and add the branch to git-spice.

   gs branch create feat2
   

   Tip

   Use gs branch create -a to automatically stage changes to tracked files. This behaves similarly to git commit -a.

This results in a stack that looks like this:

Modify mid-stack

Time to modify a branch in the middle of the stack.

1. Check out feat1:

   gs down
   

   Info

   The gs down command moves us "down" the stack, as opposed to gs up which moves us "up".

2. Make a change to hello.txt and commit it:

   echo "How are you?" >> hello.txt
   git add hello.txt
   git commit -m "Add a question to hello.txt"
   

3. Restack branches that are out of sync with the current branch.

   gs upstack restack
   

   Tip

   You can use gs commit create to combine the commit and restack steps.

4. Go back to feat2 and verify:

   gs up
   cat hello.txt
   

Summary

This section covered:

• gs branch create is a shortcut for creating a branch, committing to it, and tracking it with git-spice.
• gs up and gs down provide relative navigation through the stack.
• gs upstack restack updates branches that are out of sync with the current branch.

Next steps

• Use gs commit create to combine the commit and restack steps
• Explore different flags of gs branch create
• Create your first stacked pull requests