Git Course 0%

Shelve, stash, Local History

Intermediate IntelliJ UI ≈ 8 min

Before this lesson

What you will learn

  • The difference between shelving and stashing
  • What Local History records that Git does not
  • Which to use for which situation

After this lesson you can

  • I can park work safely and recover an edit Git never saw

Why this matters

Two of these three are IntelliJ's own inventions, and one of them, Local History, can recover work that Git genuinely cannot. That makes this a short lesson with a high payoff.

The three

Shelve Stash Local History
Made by IntelliJ Git IntelliJ
Visible to Git No Yes, git stash list No
Selective Yes: choose individual files or changes No: everything uncommitted n/a
Where The Shelf tab The Stash tab Right-click → Local History
For Parking part of your work Parking all of it, compatibly Recovering something you never committed

Shelving

Right-click a file or changelist in the Commit window → Shelve Changes, or the Shelf tab's own actions. You give it a name, and it appears on the Shelf.

The advantage over stashing is selectivity: you can shelve two files out of five, or one changelist, and keep working on the rest. The disadvantage is that Git cannot see it, so a colleague looking at your repository, or you in a terminal, will find nothing.

Unshelve puts it back, optionally into a specific changelist, and can leave the shelf entry in place rather than removing it.

Smart Checkout uses shelving behind the scenes when you switch branches with uncommitted work (lesson 16.6).

Stashing

Git → Uncommitted Changes → Stash Changes, and the Stash tab to bring it back with Apply or Pop (command page).

This is Git's own stash, so git stash list shows it, and anything you stash from the terminal appears in the tab. Use it when you want compatibility, or when instructions from a colleague say "stash it".

The two tabs can be combined into one in Settings → Version Control, which is worth doing if the distinction stops mattering to you.

Local History

This is the feature with no Git equivalent, and it is the one to remember.

IntelliJ records every save, refactoring and IDE action on a file or folder, independently of Git. Right-click a file, folder or the project → Local History → Show History opens a timeline with diffs, and any version can be restored.

What it can recover that Git cannot:

  • An edit you discarded before committing, with Rollback or git restore (lesson 12.9).
  • A file deleted before it was ever added.
  • The state before a large refactoring that went wrong.
  • Changes lost to a git reset --hard with uncommitted work open.

Its limits: it lives on your machine only, it is not shared, and it expires after a while (a few days by default, configurable). It is a safety net, not a backup, and not a substitute for committing.

Which to use

Situation Use
"I need to switch branches for ten minutes" Shelve, or let Smart Checkout do it
"Park just these two files" Shelve
"A colleague told me to stash it" Stash
"I want it visible from the terminal" Stash
"I discarded something I needed" Local History
"I want it kept properly" Commit it on a branch

That last row is worth stating plainly. Shelving and stashing are for minutes and hours. Anything you would be upset to lose belongs in a commit, even a scruffy one on a throwaway branch.

How to do it

Terminal
$ git stash push -m "faq draft"
$ git stash list
$ git stash pop

The stash tab and these commands are the same objects. Shelves and Local History have no terminal equivalent at all.

Common mistakes

  • Treating the Shelf as storage. Entries accumulate and get forgotten; commit anything that matters.
  • Expecting a shelf to be visible to Git or to a colleague.
  • Forgetting Local History exists at the exact moment it would help.
  • Relying on Local History as a backup. It expires and it is local.
  • Stashing untracked files by accident, or failing to. Git's stash needs -u for those.

Try it yourself

Goal: use all three, and see which the terminal can see.

  1. Make changes to two files. Shelve one of them with Shelve Changes.
  2. Run git status and git stash list in the terminal: the shelved file is simply gone from the working tree, and no stash exists.
  3. Unshelve it, then stash everything with Git → Uncommitted Changes → Stash Changes, and run git stash list again. This time it is there.
  4. Pop the stash.
  5. Now discard a change with Rollback, then recover it with Local History → Show History.

Expected result: three parking places used, with the terminal seeing exactly one of them, and one recovery of work Git never recorded.

Show solution

Step 2 and step 3 are the comparison that matters. Shelving is invisible to Git, which is fine until you or a colleague looks from the terminal and finds nothing. Step 5 is the one to remember: Local History is the only tool in this course that can recover uncommitted work, and it is the reason IntelliJ users get away with committing less often than they should.

Check yourself

1. Which of these can git stash list see?
2. You discarded an edit you never committed. What can recover it?
3. When should work go into a commit rather than a shelf or a stash?

Key terms

Stash Working tree Reflog

Related