Introduction
You are halfway through a feature when an urgent bug report arrives. Committing half-finished work is messy, and switching branches with uncommitted changes can be refused. git stash puts your changes aside safely in a moment. Later, when a feature is finished and released, tags give that exact commit a permanent name such as v2.1.0, so anyone can return to it.
How it works
Stash saves your uncommitted changes (staged and unstaged) on a stack and restores the working tree to HEAD:
git stash push -m "add login" # save and clean (plain git stash also works)
git stash list # stash@{0}: On main: add login
git stash pop # reapply the newest stash and remove it
git stash apply stash@{1} # reapply without removing
git stash drop stash@{0} # discard a stash
git stash -u # also stash untracked files
stash@{0} is the newest entry. Applying a stash can conflict if the files changed in the meantime, just like a merge.
Tags name commits permanently. A lightweight tag is just a ref; an annotated tag is an object with a tagger, a date and a message, and is what releases should use. Tags must be pushed explicitly.
git tag v1.4.0 # lightweight tag at HEAD
git tag -a v1.4.0 -m "Release 1.4.0" # annotated tag
git push origin v1.4.0 # share a tag
git describe # v1.4.0-3-g1a2b3c4
Semantic versioning writes versions as MAJOR.MINOR.PATCH. Raise MAJOR for incompatible changes, MINOR for new features that keep compatibility, PATCH for bug fixes. Versions are compared number by number: 1.10.0 is newer than 1.9.3, though as text "1.10" sorts before "1.9". A pre-release such as 2.0.0-rc.1 comes before 2.0.0; pre-release parts compare numerically when they are numbers and alphabetically otherwise, and numbers come before words.
git describe names a commit relative to the nearest tag: v1.4.0-3-g1a2b3c4 means three commits after v1.4.0, at commit 1a2b3c4 (the g stands for Git). On a tagged commit it prints just the tag.
Example
stash, work = [], {"app.py": "v1"}
head = {"app.py": "v1"}
def changes():
return {p: c for p, c in work.items() if head.get(p) != c}
work["app.py"] = "half-done"
stash.insert(0, ("WIP on main: add login", changes()))
work = dict(head)
print("after git stash:", work, "| stashes:", [s[0] for s in stash])
work["README.md"] = "hotfix"
head = dict(work)
print("fixed something urgent and committed:", head)
message, saved = stash.pop(0)
work.update(saved)
print("after git stash pop:", work, "| stashes:", len(stash))
def semver_key(tag):
core, _, pre = tag.lstrip("v").partition("-")
nums = tuple(int(x) for x in core.split("."))
if not pre:
return nums + (1, ())
ids = tuple((0, int(p), "") if p.isdigit() else (1, 0, p) for p in pre.split("."))
return nums + (0, ids)
tags = ["v1.10.0", "v1.2.0", "v2.0.0-rc.1", "v1.2.0-beta", "v2.0.0", "v1.9.3"]
print("tags in version order:", sorted(tags, key=semver_key))Line by line
- The half-done change to app.py is stashed, and the working tree goes back to HEAD.
- With a clean tree, an urgent fix is committed.
git stash popbrings the unfinished change back on top of the fix.semver_keyturns a tag into numbers, with a final release ranking above its pre-releases.- Sorted properly, v1.9.3 comes before v1.10.0, and v2.0.0-rc.1 before v2.0.0.
Expected result
after git stash: {'app.py': 'v1'} | stashes: ['WIP on main: add login']
fixed something urgent and committed: {'app.py': 'v1', 'README.md': 'hotfix'}
after git stash pop: {'app.py': 'half-done', 'README.md': 'hotfix'} | stashes: 0
tags in version order: ['v1.2.0-beta', 'v1.2.0', 'v1.9.3', 'v1.10.0', 'v2.0.0-rc.1', 'v2.0.0']
In the real world
Package managers such as npm, pip and Cargo rely on semantic versions to decide which updates are safe, and GitHub Releases are built on tags. Build tools often embed git describe output into programs so that every build knows exactly which commit it came from. Release automation creates tags and changelogs from commit messages, as the last module shows.
Common mistakes
- Forgetting stashed work for weeks; stashes are easy to lose track of, so prefer short-lived stashes or a work-in-progress commit on a branch.
- Expecting git push to send tags; push them explicitly or with
--follow-tags. - Sorting versions as text, which puts 1.10.0 before 1.9.0.
- Moving a published tag to another commit, which confuses everyone who fetched it.
Best practices
- Give stashes a message with
git stash push -m. - Use annotated tags for releases and follow semantic versioning.
- Never reuse a version number; publish a new one instead.
Summary
git stash saves uncommitted changes on a stack and cleans the working tree; pop and apply bring them back. Tags give commits permanent names, and annotated tags suit releases. Semantic versions compare part by part, with pre-releases before their final version, and git describe names a commit by its nearest tag.
Quick check
Key takeaways
- git stash saves your changes and cleans the working tree; git stash pop brings them back.
- Tags never move, unlike branches, so they mark releases permanently.
- Versions compare number by number, not as text: 1.10.0 is newer than 1.9.3, and 2.0.0-rc.1 comes before 2.0.0.
Practice problems for this lesson
My notes
Write down what you want to remember from this lesson. Notes are saved on this device as you type, and appear on your dashboard.