Why Use Git stash?¶

Imagine you’re working on a feature, and halfway through, you suddenly get an urgent bug fix task that requires switching to the bug branch. But you haven’t committed your current changes yet. If you switch branches directly, these changes will be overwritten or cause conflicts. That’s where Git stash comes in! It allows you to “temporarily save” your “uncommitted work” so you can switch branches, handle the urgent task, and then return to your original work later.

What is Git stash?¶

Git stash is a “temporary storage” tool provided by Git, specifically designed to save changes in the working directory and staging area (but does not save branch information). After saving, your working directory will revert to the exact state it was in after the last commit, allowing you to switch branches, pull code, or perform other operations cleanly. Later, you can restore your previous changes using stash.

Common Git stash Commands¶

1. Save Current Changes (Most Common)¶

Command: git stash
Purpose: Packages all changes in the working directory and staging area and saves them. By default, it comes with an auto-generated description (e.g., WIP on branch-name: commit-hash brief-description).
Example:

# Currently on the dev branch, with uncommitted changes
$ git status  # Check status, shows uncommitted modifications
$ git stash   # Execute stash to save changes
Saved working directory and index state WIP on dev: a1b2c3d Modify login page

2. List All Stash Records¶

Command: git stash list
Purpose: Lists all previously saved stashes (in reverse chronological order), with each record containing a number (e.g., stash@{0}) and a description.
Example:

$ git stash list
stash@{0}: WIP on dev: a1b2c3d Modify login page
stash@{1}: WIP on dev: 4e5f6g7 Add user list

3. Apply Stash (Without Deleting)¶

Command: git stash apply [stash-number]
Purpose: Restores the specified stash record (defaults to the most recent stash@{0}), but does not delete the record.
Example:

# Restore the most recent stash (stash@{0})
$ git stash apply
On branch dev
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   a.txt

4. Pop Stash (With Deletion)¶

Command: git stash pop [stash-number]
Purpose: Restores the specified stash and deletes the record (recommended, as stashes are temporary).
Example:

# Restore stash@{0} and delete it
$ git stash pop
On branch dev
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   a.txt
Dropped refs/stash@{0} (f123456...)

5. Drop a Specific Stash¶

Command: git stash drop [stash-number]
Purpose: Deletes the specified stash record (use apply if you want to keep the record; use drop if you want to delete it).
Example:

# Delete stash@{1}
$ git stash drop stash@{1}
Dropped stash@{1} (f234567...)

6. Clear All Stashes¶

Command: git stash clear
Purpose: Deletes all stash records (use with caution!).
Example:

$ git stash clear
All stashes removed.

Practical Scenarios¶

Scenario: Temporarily Switch Branches to Fix a Bug¶

1. Current Workspace Has Uncommitted Changes:

   $ git status  # Shows modified files, e.g., a.txt
   $ git stash   # Save the changes
   Saved working directory and index state WIP on dev: a1b2c3d Developing feature

2. Switch to the Bug Branch to Fix the Issue:

   $ git checkout bugfix  # Switch branches (workspace is now clean)
   $ git commit -m "Fix login bug"  # Commit the fix

3. After Fixing, Restore the Previous Stash:

   $ git checkout dev  # Switch back to the dev branch
   $ git stash pop     # Restore and delete the stash record
   On branch dev
   Changes to be committed:
     modified:   a.txt

Notes¶

1. Stash is Temporary: Use stash only for temporary storage. Do not keep important content in stashes long-term.
2. Potential Conflicts on Restore: If conflicts occur during restoration, Git will prompt “Automatic merge failed.” You need to manually edit the files to resolve conflicts.
3. Post-Restoration State: Both pop and apply restore changes to the working directory, but pop deletes the stash while apply keeps it.
4. Stash Does Not Save Branches: Stash only saves a snapshot of changes, not a branch. It cannot be switched like a branch.

Summary¶

Git stash is a powerful tool for handling “temporary unfinished work.” It helps you avoid conflicts when switching branches or pulling code while keeping your workspace clean. Master the core commands: git stash, git stash apply, and git stash pop to handle most temporary modification scenarios. Remember: use stashes temporarily and clean them up afterward to avoid accumulation!