IntermediateLesson 17 of 306 min read

Stash, Tags and Releases

Put unfinished work aside with stash, mark important commits with tags, and understand how releases and version numbers fit together.

In this lesson you will

  • Stash and restore unfinished work
  • Create annotated tags
  • Read git describe output
  • Choose a version number by rule

About 30 minutes

Interrupted halfway

Nia is in the middle of adding carrots to the plan when Dev asks for a quick fix to the rota. Her carrots are not ready to commit, and she does not want to throw them away. She also cannot easily switch to a different task with a half finished edit lying around. What she needs is a drawer to put the work in, and Git has one. It is called the stash.

Stash: a drawer for unfinished work

The command git stash push takes your uncommitted changes, saves them safely, and returns your folder to the last commit. You can now do something else, and later git stash pop brings the changes back and removes them from the drawer. The -m option gives each stash a short label, which helps when there are several.

$ mkdir garden-notes
$ cd garden-notes
$ git init
Initialized empty Git repository in /home/nia/garden-notes/.git/
$ printf "Beans: row 1\n" > plan.txt
$ printf "Mon: Nia\n" > rota.txt
$ git add .
$ git commit -m "Add plan and rota"
[main (root-commit) a43202a] Add plan and rota
 2 files changed, 2 insertions(+)
 create mode 100644 plan.txt
 create mode 100644 rota.txt
$ echo "Carrots: row 2" >> plan.txt
$ git status -s
 M plan.txt
$ git stash push -m "carrots in progress"
Saved working directory and index state On main: carrots in progress
$ git status -s
$ echo "Tue: Dev" >> rota.txt
$ git commit -am "Add Tuesday to the rota"
[main a48562b] Add Tuesday to the rota
 1 file changed, 1 insertion(+)
$ git stash list
stash@{0}: On main: carrots in progress
$ git stash pop -q
$ git status -s
 M plan.txt
$ cat plan.txt
Beans: row 1
Carrots: row 2

Follow the file through the session. After the stash, the status is empty: the carrots line is gone from the folder, but not lost. Nia makes an urgent commit to the rota. The stash list shows the saved work with its label. The pop command brings the carrots back, and the status shows the file modified again. The stash is a place for short interruptions. Anything you want to keep for longer belongs on a branch, with a commit.

Tags: names for special moments

A branch moves every time you commit. A tag is a label that stays put. You use one to mark a commit that matters, such as the version you handed to the club. There are two kinds. A lightweight tag is just a name pointing at a commit. An annotated tag is a small object of its own, with a message, a date and an author, and it is the better choice for releases. The command git describe then answers a handy question: “how far am I from the last tag?”.

$ git commit -am "Add carrots"
[main a124ba1] Add carrots
 1 file changed, 1 insertion(+)
$ git tag v0.1.0
$ git tag -a v0.2.0 -m "Plan and rota ready for the club"
$ echo "Peas: row 3" >> plan.txt
$ git commit -am "Add peas"
[main ba834fd] Add peas
 1 file changed, 1 insertion(+)
$ git tag
v0.1.0
v0.2.0
$ git tag -n
v0.1.0          Add carrots
v0.2.0          Plan and rota ready for the club
$ git describe
v0.2.0-1-gba834fd
$ cd ..
$ git init --bare origin.git
Initialized empty Git repository in /home/nia/origin.git/
$ cd garden-notes
$ git remote add origin ../origin.git
$ git push -u origin main
To ../origin.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.
$ git push origin v0.2.0
To ../origin.git
 * [new tag]         v0.2.0 -> v0.2.0
$ cd ..
$ git clone origin.git club-copy
Cloning into 'club-copy'...
done.
$ cd club-copy
$ git tag
v0.2.0

Look at the end of the session. The tag list shows both tags, and the note view shows the message of the annotated one. The describe output names the newest tag, then how many commits sit on top of it, then a short code for the current commit. A tag does not travel by itself. Only the tag that Nia pushed by name reached the shared copy, and a fresh clone of that copy sees just that tag. Pushing all tags at once is possible, but it is worth choosing deliberately.

Releases and version numbers

A release on GitHub is a published version of your project, such as a packaged download with notes. GitHub builds releases on top of Git tags. No tag means no release. You can write the notes by hand, or ask the site to draft them from the changes merged since the last release. The screens change over time, so this is a pattern to check against GitHub’s current help.

Many projects number their releases in three parts: major, minor and patch. This is called semantic versioning. A fix that changes nothing visible raises the last number. A new feature raises the middle number and resets the last. A change that breaks existing users raises the first number and resets the rest. The tiny program below applies those rules, first to an example number and then to a list of four changes.

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.lstrip("v").split("."))
    if kind == "breaking": return "v%d.0.0" % (major + 1)
    if kind == "feature":  return "v%d.%d.0" % (major, minor + 1)
    return "v%d.%d.%d" % (major, minor, patch + 1)

for kind in ["fix", "feature", "breaking"]:
    print(kind + ": v1.4.2 ->", bump("v1.4.2", kind))
changes = ["fix", "fix", "feature", "fix"]
rank = {"fix": 0, "feature": 1, "breaking": 2}
biggest = max(changes, key=rank.get)
print("changes since last release:", len(changes))
print("biggest kind:", biggest)
print("next release:", bump("v0.2.0", biggest))
fix: v1.4.2 -> v1.4.3
feature: v1.4.2 -> v1.5.0
breaking: v1.4.2 -> v2.0.0
changes since last release: 4
biggest kind: feature
next release: v0.3.0

Out of 4 changes since the last release, the biggest kind was a feature, so the next release is v0.3.0. One feature outweighs any number of fixes, so the middle number moves and the last resets to zero. Having a rule like this means nobody argues about numbers.

When to use which tool

Need Tool
Put work down for a few minutes Stash
Keep work for days A branch and commits
Mark a version for ever An annotated tag
Publish a version with notes A release on GitHub
Common mistake: a drawer full of forgotten work

Leaving things in the stash for weeks and forgetting them. A stash is easy to lose track of, so commit longer lived work to a branch with a clear name.

A convention, not a law

The files and versions are made up. The release feature, its screens and its note drafting are described from GitHub’s help pages and may change. The version rule shown is a common convention, not something Git enforces.

Stash a change in a practice repository, make an unrelated commit, and bring the stash back. Then tag your latest commit with a message and run describe after one more commit.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

What does git stash push do?

  1. Uploads the project
  2. Deletes the project
  3. Saves uncommitted changes and returns the folder to the last commit
  4. Creates a release

The status was empty after the stash, and the carrots came back with pop.

What is the difference between a branch and a tag?

  1. A branch moves when you commit; a tag stays on its commit
  2. A tag moves; a branch stays
  3. They are identical
  4. Tags cannot have names

Tags mark a moment such as a release.

Which kind of tag carries a message, date and author?

  1. A lightweight tag
  2. A branch
  3. An annotated tag
  4. A stash

The second tag in the lesson used a message.

What are GitHub releases built on?

  1. Git tags
  2. Stashes
  3. Forks
  4. Issues

No tag means no release.

Which change raises the middle number in semantic versioning?

  1. A typo fix
  2. A new feature that does not break users
  3. A change that breaks users
  4. A new README

Fixes raise the last number and breaking changes raise the first.

Summary

  • Stash is a drawer for short interruptions; longer work belongs on a branch.
  • A tag is a fixed label on a commit; annotated tags carry a message.
  • Tags do not travel unless you push them.
  • Releases on GitHub are built on tags, and semantic versions follow a simple rule.

Next lesson

Lesson 18 looks at team workflows and protecting the main branch.

Questions

Can I have several stashes?

Yes. They stack, and each has a label if you give one. Use git stash list to see them.

Can I move or delete a tag?

You can, but doing so after sharing it confuses everyone who already has it. Treat a pushed tag as permanent and make a new one instead.

Do I need releases for a small project?

No. Tags are enough for small projects. Releases help when other people download your work and want notes.

Progress is saved in this browser.