Sometimes, you’re in the middle of implementing a feature when an urgent bug fix comes up. Your current changes are half-baked, or maybe they’re just not ready to be committed. You need a way to set those changes aside temporarily without losing them.

Enter git stash. This command allows you to save your work in progress without committing it, giving you the flexibility to switch contexts quickly and efficiently.

What is Git Stash?

At its core, git stash allows you to safely store unfinished changes in a separate stack. You can then return to a clean working directory, allowing you to work on something else without losing your current progress.

When you run git stash, Git creates a new stash entry that consists of:

This operation is crucial for maintaining workflow efficiency, especially in collaborative environments where context switching is frequent.

How Git Stash Works Under the Hood

To appreciate how git stash operates, it’s helpful to understand what happens when you run the command.

When you execute git stash, Git performs a series of operations:

The stash is basically a combination of commits that Git references, allowing you to retrieve your work later. Visualizing this can help clarify the process:

Basic Usage of Git Stash

Using git stash is quite simple. Here are the core commands to get you started:

Stashing Changes

The most common command is:

This command saves your modified and staged changes. If you want to include untracked files as well, you can use:

This command stashes both tracked and untracked files, which is useful for situations where new files are part of your work in progress.

Listing Stash Entries

To see your existing stash entries, use:

This will display a list of all stashes in the format:

Each entry is indexed and can be referenced later.

Applying Stash Changes

When you’re ready to return to your stashed changes, you can apply them back to your working directory with:

This will apply the most recent stash but won't remove it from the stash list. If you want to apply a specific stash, you can specify it like this:

Dropping Stash Entries

If you no longer need a specific stash entry, you can remove it using:

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

Real-World Applications of Git Stash

In practice, git stash is incredibly useful in various scenarios. Here are a few real-world situations where it can save the day:

Context Switching

Imagine you’re working on a new feature, and your manager asks you to fix a bug in the production code. Instead of committing your half-finished work, you can stash it:

You can then switch to the main branch, fix the bug, and return to your feature branch without losing your progress.

Collaborating with Team Members

When working in a team, you may need to pull changes from a remote branch while having local changes. Stashing your work allows you to pull without merging conflicts:

This sequence ensures that you have the latest changes without the fear of merging your unfinished work.

Experimenting Safely

Sometimes, you may want to explore a new approach without committing your current work. Stashing allows you to quickly switch branches and try something out. If it doesn’t work out, you can return to your original branch and restore your stashed changes.

Common Pitfalls and Nuances

While git stash is powerful, there are some nuances and common pitfalls to be aware of:

Stashing Untracked Files

By default, untracked files are not stashed. If you find yourself needing to stash those as well, remember to use the -u flag. If you have ignored files in your .gitignore, they will also not be included in the stash.

Applying Without Dropping

Using git stash apply does not remove the stash entry. This can be useful but may lead to confusion if you forget that the stash still exists. If you want to apply and remove it simultaneously, use:

Conflicts When Applying Stash

When applying a stash, you may encounter merge conflicts if the files have changed in the meantime. In this case, resolve the conflicts as you would during a merge, and then proceed with your work.

Check for Stash Changes

Before applying a stash, it’s good practice to check what changes you are about to bring back. You can do this with:

This command shows you the changes included in the specified stash, giving you insight into what will be reapplied to your working directory.

Best Practices for Using Git Stash

To make the best use of git stash, consider these best practices:

Now that you understand the fundamentals and practical applications of git stash, you are ready to explore Stash Operations. In the next chapter, we will look at how to manage stash entries effectively, including applying, dropping, and using advanced options for a better workflow.