Setting Work Aside

You are halfway through changing the sightings layout when a club member messages: the meeting time on the home page is wrong again, and the meeting is tomorrow.

Your working directory is full of half-finished work. You do not want to commit it, because it does not work yet, and you do not want to throw it away either. git stash is the drawer: it takes your uncommitted changes off the desk, hands you a clean working directory, and gives them back whenever you ask.

Stashing

git stash push -m "half-finished sightings layout"
git status

Status comes back clean: no modified files, nothing staged. The project looks exactly as it did at your last commit, and the urgent fix can be made against a known state rather than on top of a mess.

The -m and its label are optional. They are also the difference between a drawer you can use and a drawer full of unlabelled envelopes, so use them.

Doing the urgent thing

git add index.html
git commit -m "Correct the meeting time to Thursday"

Getting it back

git stash pop

Your half-finished layout comes back into the working directory, and the stash is removed from the drawer. Carry on where you left off.

If there is more than one thing in there:

git stash list

stash@{0}: On main: half-finished sightings layout
stash@{1}: On main: experiment with the header colours

A plain git stash pop takes the newest. You can name a specific one — git stash pop stash@{1} — when the newest is not the one you want.

When a commit is the better tool

Stash is for minutes and hours. It is the wrong tool for days.

A stash is invisible in git log, unlabelled unless you labelled it, and easy to forget completely. Work that is coherent enough to describe should be committed instead — and once Chapter 6 gives you branches, "commit it on a branch and come back later" becomes the better answer to almost every version of this problem.

The honest rule: if you can write a commit message for it, commit it. If you cannot, and you need the desk clear for an hour, stash it.

The warning

Stashes are local. They are never pushed, never shared, and never part of the history. A forgotten stash is the most common way beginners "lose" work that is technically still there.

So when something you definitely wrote seems to have vanished, git stash list is worth running alongside git reflog from the last chapter. Between them they find nearly everything.

Pop and apply

One more word you will meet. git stash apply brings the work back and keeps the stash in the drawer; pop brings it back and removes it. Use pop unless you have a specific reason to want the copy kept, in which case you already know why.