When managing code with Git, have you ever encountered this situation: you’re deeply focused on developing a new feature, but suddenly need to fix an urgent production bug. If you commit your half-done code directly, it will disrupt your subsequent development workflow; yet if you don’t commit, you can’t switch to the branch where the bug needs fixing. This is where Git stash comes in handy! It temporarily saves your current work progress, allowing you to safely handle other tasks and return to your original work later.

Why Use Git stash?¶

Imagine these scenarios to understand the necessity of stash:

• Scenario 1: Urgent Branch Switch
  You’re developing a new feature on the dev branch, halfway through coding, when you discover a critical bug on the main branch that needs immediate fixing. Executing git checkout main will be rejected by Git (due to uncommitted changes). Here, stash lets you “freeze” your current progress, switch branches to fix the bug, and then resume later.

• Scenario 2: Temporary Progress Save
  You’re debugging a complex feature and need to temporarily handle a simple task (e.g., updating documentation). Using stash to save your current code allows you to resume your work later without retyping the code.

Basic Operations of Git stash¶

1. Save Current Changes¶

When you have uncommitted modifications (both in the working directory and staging area), use git stash save to temporarily save them.
Syntax: git stash save "message" (the message is optional but recommended for clarity).

Example:

# Suppose you're fixing a bug on the user login page, halfway through coding:
git stash save "Temporarily save progress on user login page bug fix"

After execution, Git packages your current changes and returns you to the last committed state. Running git status will now show a “clean” working directory (no uncommitted changes), allowing you to safely switch branches or handle other tasks.

2. View Saved Stash List¶

If you’ve saved multiple stashes or want to review previous saves, use git stash list:

Example:

git stash list

Sample Output:

stash@{0}: On dev: Temporarily save progress on user login page bug fix
stash@{1}: On feature/pay: WIP on feature/pay: a1b2c3d

Each stash has a unique identifier (e.g., stash@{0} is the most recent, stash@{1} is older) along with the associated branch and message.

3. Restore Stashed Content¶

After handling other tasks, you can restore your saved changes in two ways:

• Restore and Delete the Stash (most common): Use git stash pop.
  This restores the most recent stash (default stash@{0}) and removes it from the list.

Example:

  # After fixing the bug, switch back to the dev branch and restore the stash
  git stash pop

• Restore Without Deleting the Stash: If you want to keep the stash (e.g., for potential future restores), use git stash apply.
  This restores the specified stash without removing it from the list.

Example:

  # Restore stash@{1} (the second stash)
  git stash apply stash@{1}

Note: If conflicts arise during restoration (e.g., different stashes modify the same line of code), Git will display “Automatic merge failed.” Open the conflict files, resolve conflicts (marked with <<<<<<< HEAD etc.), and after resolving, run git add <conflict-file> followed by git stash pop (or apply) to complete the restoration.

4. Delete Unneeded Stashes¶

To remove a stash that’s no longer needed, use git stash drop:

Example:

# Delete stash@{1} (the second stash)
git stash drop stash@{1}

Important: git stash clear deletes all stashes—use this with caution!

Common Questions & Notes¶

• Scope of Stash:
  Git stash saves changes in the working directory and staging area but not untracked files (marked “untracked” in git status). To include untracked files, use git stash -u (or --include-untracked).

• Avoid Overusing Stash:
  Stash is ideal for temporary tasks. For long-term progress, commit your work (git commit) even if it’s a “work-in-progress” with a descriptive message, to ensure traceability.

Summary¶

Git stash acts as a “temporary storage bag,” safely preserving your coding progress when switching tasks or branches to prevent accidental data loss. Mastering core operations like stash save, stash list, stash pop, and stash drop will help you manage your development workflow more flexibly. Next time you need to “pause” your work, remember to use stash!