Managing Work in Progress with Git Stash

Introduction: The Challenge of Interruptions and Context Switching

When working on software development projects using Git, developers often encounter situations where they need to switch contexts or address urgent issues while in the middle of implementing a new feature or fixing a bug. Imagine you are diligently working on a new feature branch when a critical bug is reported in the main branch. You need to quickly switch to the main branch, fix the bug, and then return to your feature work.

However, your current changes for the feature might not be in a state ready to be committed. Creating a commit at this stage might lead to what are sometimes referred to as “dirty commits”—commits that contain unfinished, potentially broken, or unstable code. These commits can clutter the project history and make it difficult to track meaningful changes.

Dirty commits: Commits made with unfinished or unstable code, often created to save work in progress but not intended to be part of the permanent, clean project history. These can make the commit history less clear and harder to manage.

Fortunately, Git provides a powerful tool to handle such scenarios gracefully: Git Stash. This chapter will explore how to use Git Stash to temporarily shelve your changes, allowing you to switch contexts seamlessly and maintain a clean and organized project history.

Understanding Git Stash

Git Stash allows you to save your uncommitted changes—both staged and unstaged—and revert your working directory to a clean state, matching the last commit. Think of it as a temporary shelf where you can put aside your current work, allowing you to work on something else without committing incomplete changes. Later, you can retrieve your stashed changes and continue working where you left off.

Stash: A temporary storage area within Git for saving uncommitted changes. It allows you to clean your working directory and switch contexts without losing your work in progress.

Basic Stashing: git stash

Let’s illustrate the basic usage of git stash. Assume you are working on a project and have made some changes to a file, perhaps adding a new feature. Your working directory now deviates from the last commit.

To stash these changes, you simply open your command line or terminal in your project directory and execute the following command:

git stash

Command Line / Terminal: A text-based interface for interacting with your computer’s operating system. In the context of Git, it’s used to execute Git commands.

After running this command, you will observe the following:

• Your working directory will revert to the state of your last commit. Any changes you made will seemingly disappear from your working files.
• Git has created a new stash entry containing your saved changes.

To verify that your working directory is clean and reflects the last commit, you can use the git log command.

Git Log: A Git command that displays the commit history of the current branch. It provides information about commits, including commit messages, authors, dates, and the changes introduced.

git log --oneline

This command will show the commit history, and you should see that your working directory now matches the latest commit displayed.

Applying a Stash: git stash apply

To bring back the stashed changes into your working directory, you can use the git stash apply command. By default, git stash apply will apply the most recently created stash.

git stash apply

After executing this command:

• Your stashed changes will be reapplied to your working directory. You will see the feature you were working on reappear in your files.
• Crucially, the stash itself remains in the stash list. This means you can apply the same stash multiple times if needed.
• Your working directory will now contain the changes from the stash, but these changes are still uncommitted. You can now continue working on them, make further modifications, and eventually commit them.

Listing Stashes: git stash list

When you stash multiple times, Git keeps a list of your stashes. To see this list, use the command:

git stash list

This command will display a list of your stashes, each identified by an index number and a name. The most recent stash will be at the top of the list with index stash@{0}, the next most recent with stash@{1}, and so on.

Index (in stash list context): A numerical identifier assigned to each stash entry in the stash list. It’s used to reference specific stashes when applying, dropping, or popping them.

For example, the output might look like this:

stash@{0}: WIP on main: 5d2abf1 Starting code
stash@{1}: WIP on main: 5d2abf1 Starting code

Each stash entry also includes a brief description, often automatically generated, indicating the branch and commit the stash was created from.

Applying Specific Stashes: git stash apply <index>

If you have multiple stashes and want to apply a specific one that is not the most recent, you can use the index from the git stash list command. For example, to apply the stash with index 1 (the second most recent stash in the list), you would use:

git stash apply stash@{1}

This will apply the changes from the specified stash to your working directory, leaving the stash in the stash list.

Stashing with a Message: git stash push -m "<message>"

To make your stashes more descriptive and easier to identify later, you can add a message when creating a stash using the git stash push command with the -m flag.

Push (in stash push context): In the context of git stash push -m "<message>", it’s used to create a new stash and associate a descriptive message with it for easier identification. This is different from git push used to upload commits to a remote repository.

For example:

git stash push -m "feat: Add awesome feature"

This command will create a new stash and associate the message “feat: Add awesome feature” with it. When you run git stash list, you will see this message alongside the stash, making it much easier to remember what each stash contains.

Removing Stashes: git stash drop <index>

If you have stashes that you no longer need, you can permanently remove them from the stash list using the git stash drop command followed by the index of the stash you want to remove.

Drop: In the context of Git stash, to permanently delete a specific stash from the stash list.

For example, to remove the stash with index 1:

git stash drop stash@{1}

Git will confirm that the stash has been dropped. After dropping a stash, it is permanently deleted and cannot be recovered.

Applying and Removing a Stash in One Step: git stash pop <index>

The git stash pop command combines the actions of git stash apply and git stash drop. It applies a stash to your working directory and immediately removes it from the stash list. By default, git stash pop applies and removes the most recent stash (stash@{0}).

Pop: In the context of Git stash, to apply a stash to the working directory and simultaneously remove it from the stash list. It’s a convenient way to retrieve and clean up stashes in a single step.

git stash pop

You can also specify an index to pop a specific stash:

git stash pop stash@{1}

After using git stash pop, the specified stash will be applied to your working directory and removed from the stash list.

Clearing All Stashes: git stash clear

If you want to remove all stashes at once, you can use the git stash clear command.

Clear: In the context of Git stash, to remove all stashes from the stash list, effectively emptying the stash storage.

git stash clear

This command will remove all entries from your stash list, effectively cleaning up your stash storage. Use this command with caution, as it permanently deletes all stashed changes.

Conclusion: Efficiently Managing Interruptions with Git Stash

Git Stash is an invaluable tool for managing interruptions and context switching in your development workflow. It allows you to:

• Temporarily save uncommitted changes.
• Switch branches or work on other tasks without committing incomplete work.
• Maintain a clean working directory and commit history.
• Easily retrieve and reapply stashed changes when you are ready to resume your work.

By mastering Git Stash, you can significantly improve your efficiency and maintain a more organized and manageable Git repository, even when dealing with frequent interruptions and context shifts. This command is a cornerstone of effective Git usage for developers of all levels.