Stacked diffs

Use stacked diffs in the GitLab CLI to create small changes that build upon each other to ultimately deliver a feature. Each stack is separate, so you can:

• Continue building new features while earlier changes are reviewed.
• Respond to review feedback on specific diffs without affecting other work.
• Merge diffs independently as they’re approved.

The workflow for stacked diffs is:

1. Create changes: When you run glab stack save, the GitLab CLI:

   • Stages all your changes.
   • Creates a new commit with your message.
   • Creates a new branch for this commit.
   • Moves you to the new branch automatically.

2. Sync to GitLab: When you run glab stack sync, the GitLab CLI:

   • Pushes all branches in your stack to GitLab.
   • Creates a merge request for each diff that doesn’t have one yet.
   • Chains the merge requests together. Each merge request, except the first one, targets the previous diff branch.

The base command for this feature in the CLI is stack, which you then extend with other commands.

This feature is an experiment. We’d love to hear your feedback in issue 7473.

Create a stacked diff

Create a stacked diff when you want to break a large feature into smaller, reviewable changes.

Prerequisites:

• You must have the GitLab CLI installed and authenticated.

To create a stacked diff:

1. In your terminal, create a new stack and give it a name. For example:

   glab stack create add-authentication

2. Make your first set of changes in your editor.

3. Save your changes as the first diff:

   glab stack save

   When prompted, enter a commit message that describes this change.

4. Make your next set of changes and save these as a second diff:

   glab stack save

   Each time you run glab stack save, you create a new diff and branch. When prompted, enter a commit message that describes this change.

5. When you’re ready to push your changes to GitLab and create merge requests, run:

   glab stack sync

Your merge requests are available for review. You can continue creating more diffs in this stack, or switch to work on something else.

Add changes to a diff in a stack

To return to a specific point in the stack to add more changes to it:

1. Display a list of stacks:

   glab stack move

2. Select the stack you want to edit and press Enter.

3. Make your changes.

4. When you’re ready, save your changes, and run:

   glab stack amend

5. Optional. Change the description of the stack.

6. Push your changes:

   glab stack sync

When you sync an existing stack, GitLab:

• Updates the existing stack with your new changes.
• Rebases the other merge requests in the stack to bring in your latest changes.

Available commands

Use these commands to work with stacked diffs:

Choose between save and amend

Use the following commands for different purposes:

• glab stack save: Creates a new diff (commit and branch). Use this when you’re adding a new logical change to your stack.
• glab stack amend: Modifies the current diff. Use this when responding to review feedback or fixing the current change.