Why is Stashing Changes Needed?¶

When developing with Git, you might encounter a situation where you’re modifying code on one branch (e.g., dev) and suddenly need to switch to another branch (e.g., bugfix) to fix an urgent issue. If you directly run git checkout bugfix, Git will warn you that “your local changes would be overwritten, either commit them or stash them.” Committing a “temporary fix” and then having to undo it later is cumbersome.

What is Git Stash?¶

stash acts like a “temporary safe,” allowing you to temporarily save uncommitted changes (including both working directory and staging area modifications). This restores your working directory to a clean state (matching the HEAD version), enabling you to safely switch branches. Once you finish the task on the target branch, you can retrieve the stashed changes.

Step-by-Step Operations (with Examples)¶

Suppose you’re developing a new feature on the dev branch, having modified file1.txt and file2.txt but not yet committed:

1. Check Current Modifications¶

First, confirm there are uncommitted changes with:

git status

The output will look similar to:

On branch dev
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   file1.txt
        modified:   file2.txt

no changes added to commit (use "git add" and/or "git commit -a")

2. Stash Current Changes (Execute git stash)¶

Run git stash to save all uncommitted changes and clean your working directory:

git stash

The output will be similar to:

Saved working directory and index state WIP on dev: a1b2c3d Add feature x

After running git status again, your working directory will be clean:

On branch dev
nothing to commit, working tree clean

3. Switch to the Target Branch¶

Now you can safely switch to the branch needing fixes (e.g., bugfix):

git checkout bugfix

You can now focus on resolving the issue without worrying about overwriting changes.

4. Retrieve Stashed Changes After Completing the Target Task¶

After fixing the bugfix branch issue, first switch back to the original branch (dev):

git checkout dev

Then execute git stash pop to restore the previously stashed changes:

git stash pop

This restores the stashed changes and deletes the stash record (“pop” means “restore and remove”). The output will resemble:

On branch dev
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

        modified:   file1.txt
        modified:   file2.txt

Additional: Common Stash Commands¶

• View all stash records: git stash list
  Output example: stash@{0}: WIP on dev: a1b2c3d Add feature x
  Each stash@{n} corresponds to a stashed record.

• Apply stash without deleting the record: git stash apply
  To restore a specific stash (e.g., stash@{1}), use:
  git stash apply stash@{1} (the record remains afterward).

• Delete a specific stash record: git stash drop stash@{n}
  To discard a stashed record, use drop, e.g., git stash drop stash@{0}.

Note: Handling Conflicts¶

If conflicts arise when restoring stashed changes (e.g., code conflicts between the original branch and stashed modifications), Git will prompt Automatic merge failed. In this case:
1. Manually open the conflict file (marked with <<<<<<< HEAD).
2. Resolve the conflict.
3. Run git add <conflict-file>.
4. Re-execute git stash pop to complete the process.

Summary¶

stash is a highly useful Git tool, acting as a “temporary storage station” to safely save uncommitted changes when switching branches, preventing code loss. The core commands git stash (stash) and git stash pop (restore) are simple and essential for Git beginners. Remember to promptly restore stashed changes after completing tasks to maintain a clean workflow!