Stashing, Tagging and Releases

Two tools that look unrelated and solve adjacent problems. Stashing sets unfinished work aside so you can do something else. Tagging puts a permanent, human-readable name on a commit so you can find it again years later.

One is for the next twenty minutes. The other is for the next five years.

# Something urgent has come up and your work is half-finished
git stash push -m "Half-done CSV export, missing header row"

# Your working directory is now clean
git status

# Deal with the urgent thing, then come back
git stash list

# Restore the most recent stash and remove it from the list
git stash pop

# Or restore it and keep it stashed as well
git stash apply stash@{0}

# Include untracked files, which stash ignores by default
git stash push -u -m "New exporter class, not yet added"

• git stash push records your uncommitted changes, then returns your working directory to the last commit. The -m message is optional and worth writing — an unlabelled stash is unidentifiable within a day.
• git stash list shows the stack, newest first. The stash@{0} notation is how you refer to an entry.
• pop restores and removes; apply restores and keeps. Use apply when you want to try the changes on a different branch without losing the stash if it goes badly.
• Without -u, new files that Git does not track yet are left behind in your working directory. This catches people out: they stash, switch branch, and find an unexpected file sitting there.

A tag is a name for one specific commit that does not move. A branch pointer advances as you work; a tag stays where it was put. That fixedness is the entire feature — six months after release 2.4.0, the tag still points at exactly what was shipped.

There are two kinds. A lightweight tag is a bare name pointing at a commit. An annotated tag is a stored object with its own author, date and message, and it can be signed. For anything that represents a release, use an annotated tag: you will want to know who created it and what it contained.

# Annotated tag on the current commit
git tag -a v2.4.0 -m "Release 2.4.0 - expense export and charity VAT rate"

# Tag a commit you forgot to tag at the time
git tag -a v2.3.1 9f3c2a1 -m "Release 2.3.1 - invoice rounding fix"

# Tags are not pushed by default
git push origin v2.4.0

# What has been released?
git tag --list "v2.*"

# What exactly was in that release?
git show v2.4.0

# What changed since the last release?
git log --oneline v2.3.1..v2.4.0

• -a makes it annotated. The message is a release note in miniature and is worth more than the version number alone.
• You can tag any commit by naming its identifier, which matters when you realise after the fact that a release was never tagged.
• git push sends branches, not tags. A tag that exists only on your machine helps nobody, and this is the step most often forgotten.
• The last command is how release notes get written: every commit between two tags, in order.