# Git Tags, GitHub Releases and Semantic Versioning (v1.4.2 Explained)

Source: https://skills101.in/learn/git/git-tags-releases-semver — Skills101 free tutorial (Git & GitHub). Updated 2026-11-18.

A customer says "the invoice page broke after Tuesday's update". Which code was running on Tuesday? If your team **tags** every release, the answer takes one command. This lesson covers Git tags, how to number versions with **semantic versioning**, and how to publish a **release** on GitHub.

## 1. What is a tag?

A **branch** is a label that **moves** forward with every new commit. A **tag** is a label that **never moves**: it permanently names one commit, such as "this is version 1.1.0".

![Four commits in a row; tag v1.0.0 sits on commit b1e9528 and tag v1.1.0 on cb59cb8, while main and HEAD point at the newest commit 0417847. git describe --tags gives v1.1.0-2-g0417847](https://skills101.in/learn-img/git/tags-timeline.svg)

| | Branch | Tag |
|---|---|---|
| Moves when you commit? | yes | no |
| Typical name | `main`, `fix/login` | `v1.4.0` |
| Used for | ongoing work | marking releases and milestones |

## 2. Lightweight vs annotated tags

Git has two kinds of tags:

```bash
git tag v1.0.0 b1e9528                       # lightweight: just a name for a commit
git tag -a v1.1.0 -m "Release 1.1.0: coupons"  # annotated: a full tag object
```

An **annotated** tag is stored as its own object with the tagger's name, date and a message. You can check the type:

```bash
git cat-file -t v1.0.0
git cat-file -t v1.1.0
```

```text
commit
tag
```

The lightweight tag points straight at a commit; the annotated tag is a `tag` object. `git show v1.1.0 --no-patch` starts with the tag details, followed by the commit it points to:

```text
tag v1.1.0
Tagger: Asha <a@e.com>
Date:   Tue Nov 17 22:39:36 2026 +0530

Release 1.1.0: coupons
```

**Use annotated tags for releases.** They record who made the release and when, and many tools (including `git describe` without `--tags`) only look at annotated tags. Lightweight tags are fine for private bookmarks.

## 3. Working with tags

| Task | Command |
|---|---|
| List tags | `git tag` |
| List matching tags | `git tag -l "v1.*"` |
| Tag an older commit | `git tag -a v0.9.0 <commit> -m "…"` |
| Push one tag | `git push origin v1.1.0` |
| Push all tags | `git push origin --tags` |
| Delete a local tag | `git tag -d v1.1.0` |
| Delete a tag on GitHub | `git push origin --delete v1.1.0` |
| Look at the code of a release | `git switch --detach v1.0.0` |
| Start a fix branch from a release | `git switch -c hotfix/1.0.1 v1.0.0` |

**Important:** `git push` does **not** push tags by default. Forgetting to push them is the most common tag mistake.

Checking out a tag puts you in **detached HEAD** — you are on a commit, not a branch. That is fine for looking around. If you want to make changes, create a branch from the tag first (last row of the table).

## 4. Which version am I running? git describe

```bash
git describe --tags
```

```text
v1.1.0-2-g0417847
```

Read it in three parts:

- `v1.1.0` — the nearest tag behind the current commit
- `2` — the current commit is **2 commits** after that tag
- `g0417847` — `g` (for Git) plus the short id of the current commit

Many teams print this string in the app's footer or a `/version` endpoint, so a bug report can say exactly which build it came from. If the current commit is itself tagged, `git describe` prints just the tag name.

## 5. Semantic versioning: MAJOR.MINOR.PATCH

**Semantic versioning** (semver, defined at semver.org) gives each part of a version number a meaning:

![Starting from 2.4.1: a bug fix only makes 2.4.2, a new backward-compatible feature makes 2.5.0, and a breaking change makes 3.0.0; bumping a bigger part resets smaller parts to 0](https://skills101.in/learn-img/git/semver-bumps.svg)

| Part | Increase it when | Example change |
|---|---|---|
| **MAJOR** | you make a **breaking** change: old code using your API stops working | renaming an API field |
| **MINOR** | you **add** a feature that keeps old code working | adding UPI as a payment option |
| **PATCH** | you only **fix bugs**, without changing behaviour that users depend on | fixing a wrong GST total |

Rules worth remembering:

- Increasing one part **resets the smaller parts** to 0: `2.4.1` → `2.5.0`, not `2.5.1`.
- Versions starting with `0` (like `0.7.3`) mean **early development**: anything may change at any time.
- Extra labels mark pre-releases: `3.0.0-beta.1` comes **before** `3.0.0`.
- Git tags usually add a `v`: tag `v2.5.0` for version `2.5.0`.

Here is the bump rule as code:

```javascript
function bump(version, part) {
  let [major, minor, patch] = version.split(".").map(Number);
  if (part === "major") return `${major + 1}.0.0`;
  if (part === "minor") return `${major}.${minor + 1}.0`;
  return `${major}.${minor}.${patch + 1}`;
}

console.log(bump("2.4.1", "patch"));
console.log(bump("2.4.1", "minor"));
console.log(bump("2.4.1", "major"));
```

```text
2.4.2
2.5.0
3.0.0
```

### Why this matters in practice

In `package.json`, `"express": "^4.18.2"` means "any version from 4.18.2 up to, but not including, 5.0.0". npm trusts that minor and patch updates do not break your code. When a library breaks semver, thousands of projects break at once — which is why getting the version number right is a real responsibility.

### Versions are numbers, not text

Sorting tags as plain text gives the wrong order, because `"1" < "2"` character by character:

```javascript
const tags = ["v1.10.0", "v1.2.0", "v1.9.3"];
console.log([...tags].sort());
const asNumbers = (t) => t.slice(1).split(".").map(Number);
console.log([...tags].sort((a, b) => {
  const x = asNumbers(a), y = asNumbers(b);
  return x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
}));
```

```text
[ 'v1.10.0', 'v1.2.0', 'v1.9.3' ]
[ 'v1.2.0', 'v1.9.3', 'v1.10.0' ]
```

Git has the same problem: plain `git tag` sorts as text. Use `git tag --sort=v:refname` to sort by version.

## 6. GitHub releases and changelogs

A **tag** is a Git feature. A **release** is a GitHub page built on a tag, with:

- a title and **release notes** (what changed, in plain words)
- downloadable files (for example a built `.apk` or `.zip`)
- automatic source-code archives

To create one: repository → **Releases** → **Draft a new release** → choose or create a tag → write notes → **Publish**. GitHub can also **generate release notes** from the merged pull requests since the previous tag.

Many projects also keep a `CHANGELOG.md` with sections per version:

```text
## 2.5.0
### Added
- UPI payments at checkout
### Fixed
- GST total rounded wrongly on invoices
```

## 7. A simple release routine

```bash
git switch main && git pull
# make sure tests pass and the version number in package.json is updated
git tag -a v2.5.0 -m "Release 2.5.0: UPI payments"
git push origin main
git push origin v2.5.0
# then create the GitHub release from tag v2.5.0
```

Automated pipelines (for example GitHub Actions) are often set to **deploy whenever a tag starting with `v` is pushed**, so the tag itself becomes the "ship it" button.

## Common mistakes

- Creating a tag but never pushing it (`git push` skips tags).
- Moving or re-using a tag that others already fetched — create a new version instead.
- Bumping PATCH for a breaking change, so users' code breaks on a "safe" update.
- Making changes in detached HEAD after checking out a tag, then losing them; create a branch first.

## Quick recap

- A tag is a fixed label on a commit; branches move, tags do not.
- Use **annotated** tags (`git tag -a v1.2.0 -m "…"`) for releases; push them explicitly.
- `git describe --tags` → nearest tag, commits since it, and the current short id.
- Semver: MAJOR (breaking) . MINOR (new, compatible) . PATCH (fixes); bigger bumps reset smaller parts to 0.
- A GitHub release = a tag + notes + files; keep a changelog.


Practice quiz and free certificate: https://skills101.in/learn/git/git-tags-releases-semver