Using Git Stash in Multi-Branch Workflows

Overview

In a collaborative development environment, you're likely to work with multiple branches for different features, bug fixes, and releases. While managing these branches, you might run into situations where you need to temporarily save your work without committing it, and later apply it on the same or even a different branch. Git's stash command can help you navigate these scenarios effectively. For more details about the git stash command, check out my posts from last weeks titled "Git Stash: Temporarily Saving Changes" and "Applying and Clearing Git Stashes".

1. Understanding Multi-Branch Workflows

In multi-branch workflows, developers typically work on different branches to isolate features, bug fixes, or releases. Here’s an example scenario:

• main: The main branch used for production code.
• feature-branch: A branch dedicated to developing a new feature.
• bugfix-branch: A branch dedicated to fixing a specific bug.

At any given point, you may need to switch between branches without committing your current work. This is where Git stash becomes essential—it allows you to save your uncommitted changes, switch branches, and reapply those changes when you're ready.

For instance, let’s say you’re working on feature-branch, but you need to switch to bugfix-branch to resolve an urgent issue. Instead of committing your incomplete work on feature-branch, you can stash it, switch to bugfix-branch, complete the fix, and then switch back to feature-branch to apply the stashed changes.

2. How to Stash Changes on One Branch and Apply Them on Another

The main advantage of Git stash in a multi-branch workflow is that stashes are not bound to a specific branch. You can stash changes on one branch and apply them to another.

Stashing Changes on the Current Branch

Let’s say you’re working on feature-branch and have some changes you want to save before switching branches. You can stash your changes with:

git stash push -m "WIP: Working on feature X"

This will save your changes in the stash list and allow you to switch branches without affecting your working directory.

Switching to Another Branch

Once your changes are stashed, you can switch to another branch without worrying about your uncommitted changes:

git checkout bugfix-branch

You can now work on the bugfix-branch as usual.

Applying the Stash on Another Branch

After completing your work on bugfix-branch, you might want to apply the stashed changes to another branch, like main or even a different feature branch.

You can do this by switching to the target branch:

git checkout main

Then, apply the stash:

git stash apply stash@{0}

This will reapply the stashed changes from feature-branch to main.

Example Scenario:

1. Work on feature-branch.
2. Stash the changes with git stash push -m "WIP: Feature development".
3. Switch to bugfix-branch and fix a bug.
4. After fixing the bug, switch to main or back to feature-branch.
5. Apply the stashed changes with git stash apply stash@{0}.

This allows you to seamlessly move between tasks without committing half-done work.

3. Handling Conflicts When Applying Stashes Across Branches

Sometimes, applying a stash to a different branch may lead to conflicts if the changes in the stash conflict with the code on the target branch. This is especially common when working with multiple branches that have overlapping changes.

When you apply a stash and Git detects conflicts, it will not apply the stash cleanly, and you’ll need to resolve the conflicts manually.

Example of a Conflict Scenario

1. You stash changes on feature-branch that modify a file, e.g., app.js.
2. You switch to bugfix-branch and make unrelated changes to the same file, app.js.
3. You apply the stash from feature-branch to bugfix-branch.

At this point, Git may warn you about conflicts in app.js. When this happens, Git will mark the conflict in the file using conflict markers (<<<<<<, ======, >>>>>>).

Resolving the Conflict

To resolve the conflict, open the conflicted file and manually edit the conflict markers to decide which changes to keep. After resolving the conflict, you can continue with the stash apply or complete the merge.

git status  # Check the conflict
git add <file>  # Add the resolved file
git commit -m "Resolved stash conflict"

You can always abort the stash apply process and start over using:

git stash apply --abort

This is especially helpful when the conflict resolution is too complex or unexpected.

4. Using stash apply and stash pop in Multi-Branch Workflows

As discussed in previous posts, Git provides two primary ways to apply stashes: git stash apply and git stash pop. Let’s briefly recap when to use each in multi-branch workflows.

git stash apply

The apply command applies the stashed changes without removing them from the stash list. This is useful when you want to keep the stash for future reference or reuse across branches.

git stash apply

For multi-branch workflows, this is particularly helpful when:

• You want to apply the stash to multiple branches without losing the stash.
• You’re unsure if you’ll need the stash again after applying it.

git stash pop

The pop command applies the stashed changes and removes the stash from the list, which is a good choice when you’re confident that you no longer need the stash.

git stash pop

This is useful when:

• You want to clean up the stash list after applying the changes.
• You only intend to apply the stash to a single branch.

In multi-branch workflows, it’s common to use apply first to ensure the stash works as expected. If all goes well, you can later manually clear the stash with git stash drop.

5. Managing Multiple Stashes Across Branches

As you switch between branches and stash changes, you might accumulate multiple stashes. Fortunately, Git provides tools to manage them effectively.

Viewing All Stashes

To see a list of all your saved stashes, use:

git stash list

You’ll see a list like this:

stash@{0}: WIP on feature-branch: feature development
stash@{1}: WIP on bugfix-branch: fixing login issue
stash@{2}: WIP on main: updating README

This helps you keep track of your stashes across different branches.

Naming Your Stashes

When stashing in a multi-branch environment, it’s important to name your stashes clearly so you can easily identify them later. You can do this by adding a message when stashing:

git stash push -m "WIP: Refactoring login feature"

This will add a more descriptive entry to your stash list, making it easier to locate and apply the correct stash later.

Dropping Stashes

If you no longer need a particular stash, you can drop it from the list:

git stash drop stash@{1}

Alternatively, if you want to clear all stashes, use:

git stash clear

6. Best Practices for Using Git Stash in Multi-Branch Workflows

1. Name Your Stashes

Always name your stashes with descriptive messages to make them easier to manage across branches. Avoid leaving stashes unnamed as they will only appear as "WIP" with no additional context.

2. Apply Stashes Selectively

Before applying a stash, review your working directory and branch to avoid conflicts or accidental overwriting. You can use git diff to review the changes in a stash before applying it:

git stash show stash@{0} -p

This command will show a diff of the stashed changes, helping you decide whether it’s safe to apply them.

3. Be Cautious with Pop

Use git stash pop with care, especially in multi-branch workflows. It’s generally safer to use git stash apply first, review the results, and then manually clear the stash if everything is in order.

4. Avoid Overusing Stashes

In a multi-branch workflow, it’s easy to accumulate many stashes, leading to clutter and confusion. Make it a habit to regularly clean up your stashes, either by applying and dropping them or by using git stash clear when they’re no longer needed.

5. Resolve Conflicts Promptly

When applying stashes across branches, resolve any conflicts immediately to avoid introducing bugs or inconsistencies into your project. Always run git status and git diff after applying a stash to ensure everything is in order.

Conclusion

In a multi-branch workflow, Git stash is an invaluable tool for managing uncommitted changes across branches. By learning how to stash, apply, pop, and clear stashes effectively, you can streamline your development process and switch between tasks without losing work.

In this post, we covered:

• Stashing changes on one branch and applying them to another.
• Handling conflicts when stashes span multiple branches.
• Using git stash apply and git stash pop in a multi-branch workflow.
• Best practices for managing stashes across branches.

By incorporating these techniques into your workflow, you'll be better equipped to manage complex, multi-branch development environments with ease.