Why stashing saves work temporarily in Git - Why It Works This Way

Overview - Why stashing saves work temporarily

What is it?

Stashing in git is a way to save your current changes temporarily without committing them. It allows you to clear your working area so you can switch tasks or branches without losing your work. Later, you can bring back those saved changes exactly as they were. This helps keep your work safe while you handle other urgent tasks.

Why it matters

Without stashing, you might have to commit unfinished or broken work just to switch tasks, cluttering your project history. Or you might lose your changes if you switch branches carelessly. Stashing solves this by giving you a safe, quick way to pause your work and come back to it later, keeping your project clean and your progress intact.

Where it fits

Before learning stashing, you should understand basic git commands like add, commit, and branch switching. After mastering stashing, you can explore more advanced git workflows like rebasing, cherry-picking, and resolving merge conflicts efficiently.

Mental Model

Core Idea

Stashing is like putting your current work in a temporary drawer so you can clear your desk and work on something else without losing anything.

Think of it like...

Imagine you are drawing on a sketchpad but suddenly need to use the table for a different project. Instead of finishing or throwing away your drawing, you slide the sketchpad into a drawer to keep it safe and free the table. Later, you pull it out and continue exactly where you left off.

┌─────────────┐       ┌─────────────┐       ┌─────────────┐
│ Working    │       │ Stash       │       │ Working    │
│ Directory  │──────▶│ (Temporary) │──────▶│ Directory  │
│ (Changes)  │       │ Storage     │       │ (Restored) │
└─────────────┘       └─────────────┘       └─────────────┘

Build-Up - 6 Steps

1

Foundation

What is git stash and why use it

Concept: Introduce the basic idea of git stash as a temporary save for uncommitted changes.

Git stash saves your current changes (both staged and unstaged) away so you can work on something else without committing. It’s like a clipboard for your work-in-progress code.

Result

Your working directory becomes clean, allowing you to switch branches or pull updates without conflicts.

Understanding stash as a temporary holding place helps you avoid committing incomplete work just to switch tasks.

2

Foundation

How to create and apply a stash

Concept: Learn the basic commands to save and restore changes using stash.

Use 'git stash push' to save changes and 'git stash pop' to restore them. 'git stash list' shows saved stashes. For example: $ git stash push -m "WIP feature" $ git stash list $ git stash pop

Result

Changes are saved away and then restored exactly as they were when you pop the stash.

Knowing these commands lets you pause and resume work smoothly without losing progress.

3

Intermediate

What changes does stash save exactly

🤔Before reading on: do you think stash saves only staged changes, only unstaged changes, or both? Commit to your answer.

Concept: Understand that stash saves both staged and unstaged changes, but not untracked files by default.

Git stash saves tracked files that are modified or staged. It does not save new untracked files unless you use the '--include-untracked' option. Example: $ git stash push --include-untracked

Result

You can save almost all your work, but untracked files need special flags to be included.

Knowing what stash saves prevents surprises when you restore and find some files missing.

4

Intermediate

Multiple stashes and managing them

🤔Before reading on: do you think git stash can hold only one stash or multiple? Commit to your answer.

Concept: Git stash can hold multiple saved states, each with a name and index.

Each time you stash, git adds a new stash entry. Use 'git stash list' to see all. You can apply or drop specific stashes by name or index: $ git stash apply stash@{1} $ git stash drop stash@{0}

Result

You can manage multiple saved works and choose which to restore or discard.

Understanding stash management helps you juggle multiple tasks without losing track.

5

Advanced

Stashing with untracked and ignored files

🤔Before reading on: do you think git stash saves ignored files by default? Commit to your answer.

Concept: Learn how to stash untracked and ignored files using special options.

By default, git stash ignores untracked and ignored files. To include untracked files: $ git stash push --include-untracked To include ignored files as well: $ git stash push --all

Result

You can save absolutely all your work, including new and ignored files, for complete safety.

Knowing these options prevents accidental loss of new or ignored files during stash.

6

Expert

How stash works internally and its limitations

🤔Before reading on: do you think stash creates commits or just saves files somewhere? Commit to your answer.

Concept: Git stash internally creates hidden commits to save your changes, but this can cause conflicts or confusion if misused.

Git stash creates two commits: one for the index (staged changes) and one for the working directory (unstaged changes). These commits are stored in the refs/stash reference. When you apply or pop, git tries to merge these commits back. Conflicts can occur if the code changed meanwhile. Also, stash is not a substitute for proper commits or branches.

Result

You understand stash is a powerful but temporary tool with internal complexity and possible pitfalls.

Knowing stash internals helps you troubleshoot conflicts and decide when to use stash versus branches.

Under the Hood

Git stash works by creating two hidden commits: one capturing the staged changes (index) and another capturing the unstaged changes (working directory). These commits are stored in a special reference called refs/stash. When you apply or pop a stash, git attempts to merge these commits back into your current branch, restoring your saved changes. This mechanism allows git to save your work without affecting your branch history until you decide to apply the stash.

Why designed this way?

Stash was designed to be a quick, temporary save without cluttering the commit history. Using hidden commits leverages git's existing commit and merge infrastructure, making stash reliable and efficient. Alternatives like temporary branches were more cumbersome and risked polluting the project history. The hidden commit approach balances safety, speed, and simplicity.

Working Directory Changes
       │
       ▼
┌───────────────────┐
│ git stash command │
└───────────────────┘
       │
       ▼
┌─────────────────────────────┐
│ Create hidden commits:       │
│ - Commit 1: staged changes   │
│ - Commit 2: unstaged changes │
└─────────────────────────────┘
       │
       ▼
┌─────────────────────────────┐
│ Store commits in refs/stash  │
└─────────────────────────────┘
       │
       ▼
┌─────────────────────────────┐
│ git stash apply/pop merges  │
│ commits back to working dir │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: does git stash save untracked files by default? Commit yes or no.

Common Belief: Git stash saves all my current changes including new untracked files automatically.

Reality: By default, git stash only saves tracked files that are modified or staged. Untracked files are not saved unless you use the '--include-untracked' option.

Why it matters: If you rely on stash to save untracked files without the option, you might lose new files when switching branches or cleaning your working directory.

Quick: does git stash create permanent commits in your branch history? Commit yes or no.

Common Belief: Stashing creates commits that appear in my branch history like normal commits.

Reality: Stash creates hidden commits stored separately and does not affect your branch history unless you explicitly commit them later.

Why it matters: Misunderstanding this can lead to confusion about project history and when changes are actually saved permanently.

Quick: can you safely stash changes and then pull updates without conflicts every time? Commit yes or no.

Common Belief: Stashing guarantees no conflicts when switching branches or pulling updates.

Reality: Conflicts can still occur when applying a stash if the codebase changed in conflicting ways since the stash was created.

Why it matters: Assuming stash prevents all conflicts can cause unexpected merge problems and lost work.

Quick: does popping a stash remove it from the stash list automatically? Commit yes or no.

Common Belief: Using 'git stash pop' always removes the stash from the list after applying it.

Reality: 'git stash pop' removes the stash only if the apply succeeds without conflicts. If conflicts occur, the stash remains for safety.

Why it matters: Expecting the stash to disappear can lead to confusion about whether your changes were restored or not.

Expert Zone

1

Stash entries are stored as commits but are not part of any branch until applied, which means they can be garbage collected if not referenced.

2

Using stash with untracked and ignored files requires explicit flags, but including ignored files can sometimes stash unwanted files like build artifacts.

3

Applying a stash does a three-way merge internally, so understanding git merge mechanics helps resolve stash conflicts effectively.

When NOT to use

Avoid using stash for long-term storage or sharing work; use branches instead. Also, do not rely on stash to save untracked files unless you use the correct flags. For complex task switching, creating feature branches is safer and clearer.

Production Patterns

In professional workflows, stash is often used to quickly save work before pulling updates or switching branches. Developers use descriptive stash messages to track multiple stashes. Some teams discourage stash use in favor of feature branches to keep history clean and collaboration transparent.

Connections

Version Control Branching

Stashing complements branching by allowing temporary saves without committing to a branch.

Understanding stash helps grasp how git separates temporary work from permanent branch history, improving task switching.

Undo and Redo in Text Editors

Stashing is like an advanced undo buffer that saves multiple states outside the main file.

Knowing stash is a temporary save outside normal commits helps relate it to undo systems that keep work safe but reversible.

Memory Paging in Operating Systems

Stashing is similar to paging out memory to disk temporarily to free RAM for other tasks.

This cross-domain link shows how temporarily saving state to free resources is a common pattern in computing.

Common Pitfalls

#1 Expecting stash to save new untracked files without options.

Wrong approach:

git stash push
# Then switching branches and losing new files

Correct approach:

git stash push --include-untracked
# Saves new files too

Root cause:

Misunderstanding that stash only saves tracked files by default.

#2 Using stash as a permanent backup instead of commits or branches.

Wrong approach:

git stash push
# Leaving work only in stash for days or sharing with others

Correct approach:

git commit or git branch for permanent or shared work

Root cause:

Confusing stash as a permanent storage rather than a temporary holding place.

#3 Popping stash without checking for conflicts and losing changes.

Wrong approach:

git stash pop
# Ignoring conflict messages and overwriting work

Correct approach:

git stash apply
# Resolve conflicts manually
# Then git stash drop if successful

Root cause:

Assuming stash pop always succeeds cleanly without conflicts.

Key Takeaways

Git stash temporarily saves your uncommitted changes so you can switch tasks without losing work.

By default, stash saves tracked changes but not untracked or ignored files unless you use special options.

Stash creates hidden commits internally, keeping your branch history clean and allowing safe restoration.

Managing multiple stashes with descriptive messages helps juggle several tasks efficiently.

Stash is a temporary tool; for long-term or shared work, use commits and branches instead.