1. Home
  2. Blog
  3. DevOps

DevOps

Git Tag Explained: Create, Push and Delete Release Tags

A git tag is a permanent name for one commit, usually a release such as v1.0.0. Learn annotated vs lightweight tags, how to list, push and delete them, why git push skips tags by default, and how git describe builds version strings, with output from a tested repository.

8 min read
Git tag explained: create, push and delete release tags

Key takeaways

  • A git tag is a fixed name for a commit. Unlike a branch, it does not move when you add commits.
  • Use annotated tags (git tag -a v1.0.0 -m "...") for releases. They store the tagger, date and message.
  • git push does not send tags. Use git push origin v1.0.0, --tags, or --follow-tags.
  • Deleting is two steps: git tag -d locally and git push origin --delete on the remote.

When a bug report says “broken since version 1.1”, you need to know exactly which code shipped as 1.1. Commit hashes like b1c0a8b are precise but meaningless to humans. A git tag gives that commit a name you can type, share and build from. CI pipelines often trigger releases when a tag is pushed, and package managers read versions from tags.

We tested every command in a throwaway repository with a local bare remote, using Git 2.56 and a demo identity. Hashes shown come from that repository.

What is a git tag?

A tag is a reference that points at a commit and stays there. A branch is a moving pointer that advances with every new commit; a tag is a bookmark. Tags live under refs/tags/, just as branches live under refs/heads/. New to these ideas? Our Git tutorial for beginners explains commits and branches first.

Annotated vs lightweight tags

Git has two kinds of tag, and the difference is real. We created one of each on the same commit, then asked Git what each name points to:

git tag v1.0.0-light
git tag -a v1.0.0 -m "Release 1.0.0"
git cat-file -t v1.0.0-light    # commit
git cat-file -t v1.0.0          # tag

A lightweight tag is just a name pointing straight at a commit. An annotated tag is a full object in the Git database, with its own author, date and message, and it points at the commit.

Lightweight Annotated
Command git tag NAME git tag -a NAME -m MSG
Stores tagger and date No Yes
Message No Yes
Can be signed No Yes, with -s
Used by git describe by default No Yes
Pushed by --follow-tags No Yes
Best for Private, temporary markers Releases

The Git book recommends annotated tags for anything you share, and the last two rows show why: several tools ignore lightweight tags by default.

Creating tags

After two more commits we tagged a second release:

git commit -qam "Fix typo"
git commit -qam "Add export"
git tag -a v1.1.0 -m "Release 1.1.0"

Without -m, Git opens your editor for the message. Tag names cannot be reused. Trying again gave:

git tag -a v1.0.0 -m x
fatal: tag 'v1.0.0' already exists

Use -f to force a move only on tags nobody has pulled yet. Moving a published tag confuses everyone who already fetched the old one.

Listing and sorting tags

git tag -l
v1.0.0
v1.0.0-light
v1.1.0

git tag -l "v1.1*"
v1.1.0

git tag -n
v1.0.0          Release 1.0.0
v1.0.0-light    First release
v1.1.0          Release 1.1.0

-n shows the first line of each annotation. For a lightweight tag, Git shows the commit message instead. Plain listing sorts alphabetically, so v1.10.0 would appear before v1.2.0. Sort by version instead:

git tag -l --sort=-v:refname
v1.1.0
v1.0.0-light
v1.0.0

Notice v1.0.0-light sorted above v1.0.0. Version sort treats the suffix as part of a later version. If you use pre-release names such as v2.0.0-rc1, set versionsort.suffix so they sort before the final release.

Inspecting a tag

git show v1.0.0 --no-patch
tag v1.0.0
Tagger: Demo <demo@example.com>
Date:   Mon Nov 16 10:00:00 2026

Release 1.0.0

The tag header is followed by the commit it points to. For the lightweight tag, git show goes straight to the commit, because there is no tag object to show.

Pushing tags to a remote

This is the step most people miss. We pushed the branch, then listed the remote’s tags:

git push origin main
git ls-remote --tags origin
(no output)

Nothing. git push sends branches, not tags. You have three options:

  • git push origin v1.1.0 pushes one tag. Safest.
  • git push origin --tags pushes all local tags, including stray experiments.
  • git push --follow-tags pushes the branch plus annotated tags on the pushed commits.
git push --follow-tags origin main
git ls-remote --tags origin
refs/tags/v1.0.0
refs/tags/v1.0.0^{}
refs/tags/v1.1.0
refs/tags/v1.1.0^{}

--follow-tags sent both annotated tags and skipped v1.0.0-light. The ^{} lines are the commits that the annotated tag objects point to. To make it the default, run git config push.followTags true.

Deleting tags

We pushed the lightweight tag by name, then removed it in both places:

git tag -d v1.0.0-light
Deleted tag 'v1.0.0-light' (was b4c82db)
git push origin --delete v1.0.0-light

After that, git ls-remote listed only the two annotated tags again. Local and remote tags are separate, so deleting one does not delete the other. The older syntax git push origin :refs/tags/NAME does the same thing. Teammates who already fetched the tag keep their copy until they run git fetch --prune --prune-tags.

Tagging an older commit

Forgot to tag a release? Pass the commit as an argument:

git tag -a v0.9.0 HEAD~2 -m "Backfilled"

Any commit reference works: a hash, HEAD~2 or a branch name. To find which tags contain a given commit, useful when checking whether a fix shipped, use git tag --contains COMMIT. In our repo, git tag --contains HEAD~1 returned only v1.1.0.

git describe: versions from tags

git describe names a commit relative to the nearest annotated tag, which makes a handy build version:

git describe
v1.1.0
git describe HEAD~1
v1.0.0-1-ga68e163

On a tagged commit you get the tag alone. Otherwise you get the tag, the number of commits since it (1), and g plus the short hash (a68e163). Add --tags to consider lightweight tags too, and --dirty to flag uncommitted changes. Many build tools embed this string in version output so testers can tell exactly which build they have.

Checking out a tag

git checkout v1.0.0
git status
HEAD detached at v1.0.0

You get a detached HEAD, because a tag cannot move to follow new commits. That is fine for building or testing an old release. To make a hotfix, create a branch from the tag: git switch -c hotfix-1.0.1 v1.0.0. For more on recovering work, see our guides on reset vs revert and git bisect, which pairs nicely with tags to find the release that introduced a bug.

Best practices

  • Use annotated tags for every release, and follow semantic versioning such as v2.3.1.
  • Pick one style for the prefix, with or without v, and stick to it.
  • Never move or reuse a published tag. Make a new version instead.
  • Push tags one at a time, or enable push.followTags.
  • Sign release tags with git tag -s if your project verifies releases.
  • Trigger CI release jobs on tag pushes, as described in our GitHub Actions guide.

Common git tag errors and fixes

Pushing a tag that already exists on the remote

We deleted v1.1.0 locally, recreated it on a different commit and tried to push:

git push origin v1.1.0
 ! [rejected]        v1.1.0 -> v1.1.0 (already exists)
hint: Updates were rejected because the tag already exists in the remote.

Git protects published tags. This is a feature: if a tag could silently move, two people could build “v1.1.0” from different code. The right fix is almost always a new version number. Forcing with git push --force origin v1.1.0 works but leaves everyone who already fetched the old tag out of sync.

Missing tags after a clone or pull

git clone fetches tags, and git pull fetches tags that point into the history it downloads. Tags on other branches or added later may be missing. Run git fetch --tags to get them all. In our repo, after deleting the bad local tag, git fetch origin --tags brought v1.1.0 back from the remote, pointing at the right commit.

A tag and a branch with the same name

If you create a branch called v1.0.0, commands such as git checkout v1.0.0 become ambiguous and Git warns about it. Use full names such as refs/tags/v1.0.0 to be explicit, and keep version numbers for tags only.

Tags in CI pipelines

Many pipelines publish a release when a tag matching v* is pushed. Shallow CI checkouts often fetch no tags, so git describe fails with “No names found”. Fetch full history or tags in the checkout step before building version strings.

Final thoughts

A git tag is a small feature with big value: it turns a hash into a release name everyone understands. Create annotated tags with git tag -a, remember that tags need their own push, delete them in both places, and use git describe for build versions. With those habits, “which version has this bug?” becomes a question you can answer in seconds.

FAQ

What is the difference between a git tag and a branch?

A branch moves forward with each new commit. A tag stays fixed on one commit, which makes it ideal for marking releases.

Why are my git tags not on GitHub?

Git push does not send tags by default. Push them with git push origin and the tag name, or use the tags or follow-tags options.

Should I use annotated or lightweight tags?

Use annotated tags for releases because they store the tagger, date and message and work with git describe and follow-tags. Lightweight tags suit private markers.

How do I delete a remote git tag?

Run git push origin with the delete option and the tag name. Also delete your local copy with git tag and the d option.

Can I move a git tag to another commit?

Yes, with the force option, but avoid it for published tags. Others keep the old tag, so create a new version tag instead.

Keep learning

Work with Stack Quora

Need help with testing, WordPress or SEO?

We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.

Keep reading

More guides on testing, AI & modern development

Enjoyed this article? Pick a topic and jump straight into our newest tutorials.

Artificial Intelligence

Jaccard Similarity: Formula, Python, MinHash

Jaccard similarity measures overlap between two sets as intersection over union. Work the formula, compute it in Python for words…

Read article →
Software Development

Unix Timestamp Explained: Seconds vs ms

A Unix timestamp counts seconds since 1 January 1970 UTC. Learn seconds vs milliseconds, converting in Python, JavaScript and SQL,…

Read article →
DevOps

Git Hooks: Pre-commit and Commit-msg Examples

Git hooks run scripts at key moments such as commit and push. See tested pre-commit, commit-msg and prepare-commit-msg hooks, sharing…

Read article →
Test Automation

API Testing in Python: Pytest + Requests Suite

Build an API testing suite in Python with pytest and requests: fixtures, status codes, headers, JSON schema validation, CRUD flows,…

Read article →
Software Testing

Test Design Techniques: 9 Methods + Examples

Test design techniques help you write fewer tests that catch more bugs. Learn 9 black-box, white-box and experience-based methods with…

Read article →
Databases & SQL

SQL Temporary Table: Create, Use and Drop It

SQL temporary tables store interim results for one session. Learn syntax for SQL Server, PostgreSQL, MySQL, Oracle and SQLite, session…

Read article →
Databases & SQL

SQL CROSS JOIN: Every Combination + Examples

SQL CROSS JOIN returns every combination of rows from two tables. See the row math, product variants, calendar grids that…

Read article →
Software Development

JavaScript Date: Format, Parse, Timezone Bugs

JavaScript Date explained with tested Node.js code: zero-based months, the date-only UTC parsing trap, toISOString, getTimezoneOffset, Intl formatting, date math…

Read article →
Software Development

Python Requests: GET, POST, Timeouts, Retries

Python requests explained with code tested against a local API: GET with params, POST json vs data, headers and auth,…

Read article →
Software Development

Python Deepcopy vs Copy: Fix Nested Lists

Python deepcopy vs shallow copy explained with tested code: aliasing, nested lists, the [[0]*3]*3 trap, memo and cycles, custom __deepcopy__,…

Read article →
Artificial Intelligence

TF-IDF Explained: Formula and Worked Example

TF-IDF scores a word by how often it appears in a document and how rare it is across all documents….

Read article →
Software Development

Base64 Encoding Explained, With Python Code

Base64 encoding turns bytes into 64 safe text characters. See the bit-level steps, padding, URL-safe base64, the 33% size cost,…

Read article →
DevOps

Git Tag: Create, Push and Delete Release Tags

Git tag explained with tested commands: annotated vs lightweight tags, listing and sorting, pushing with follow-tags, deleting local and remote…

Read article →
Test Automation

Pytest Coverage: pytest-cov and Branch Gaps

Measure pytest coverage with pytest-cov: term-missing reports, branch coverage, HTML reports, pyproject settings and a fail-under gate for CI, with…

Read article →
Software Testing

Error Guessing in Testing: Checklist + Demo

Error guessing uses tester experience to predict where code breaks. Get a ready checklist of risky inputs, a step by…

Read article →
Databases & SQL

SQL LAG and LEAD: Compare Rows, 5 Examples

SQL LAG and LEAD read values from the previous or next row without a self join. Five tested examples: change,…

Read article →
Databases & SQL

SQL STRING_AGG: Combine Rows Into One String

SQL STRING_AGG joins values from many rows into one string per group. See syntax for PostgreSQL, SQL Server, MySQL GROUP_CONCAT,…

Read article →
Software Development

JavaScript Classes: Private Fields and Extends

JavaScript classes explained with tested Node.js code: constructors, methods, #private fields, getters, static members, extends and super, plus the errors…

Read article →
Artificial Intelligence

BM25 Explained: How Keyword Search Ranks Results, With Python Code and Hybrid Search

BM25 explained with a pure Python implementation we ran: the formula, IDF, term saturation, the k1 and b parameters, why…

Read article →
DevOps

Git Bisect Explained: Find the Commit That Broke Your Code, Manually or Automatically

Git bisect explained with a tested repository: find the one bad commit among 41 in 5 test runs, automate it…

Read article →
Test Automation

pytest Markers Explained: Custom Marks, skip, skipif, xfail and -m Filters

pytest markers explained with a tested suite: register custom marks, run only smoke tests with -m, combine filters with and,…

Read article →
Software Testing

Positive vs Negative Testing: Differences, 24 Real Test Cases and a Checklist

Positive vs negative testing explained with a real signup form: 6 positive and 18 negative test cases run in pytest,…

Read article →
Databases & SQL

SQL ORDER BY Multiple Columns: ASC, DESC, NULLS LAST, Case and Custom Order

SQL ORDER BY with multiple columns explained with tested queries: mixed ASC and DESC, tie-breakers, NULLS FIRST and LAST, case-insensitive…

Read article →
Databases & SQL

SQL Running Total: SUM OVER, Per-Group Totals, Moving Sums and the RANGE Trap

How to calculate a SQL running total with SUM() OVER: per-group totals, daily cumulative sums, moving sums, percent of total,…

Read article →
Artificial Intelligence

Cosine Similarity Explained: Formula, Worked Example and Python Code

Cosine similarity explained simply: the formula, a worked example by hand, pure Python and NumPy code, cosine vs Euclidean distance…

Read article →
DevOps

Git Squash Commits: 4 Easy Ways, Tested Step by Step (rebase -i, reset, merge)

Git squash commits explained with 4 tested methods: interactive rebase, reset –soft, merge –squash and fixup with autosquash. Before-and-after logs,…

Read article →
Test Automation

pytest parametrize Explained: 7 Patterns with Tested Examples

pytest parametrize explained with 7 tested patterns: basic cases, readable ids, stacked decorators, pytest.param with xfail and skip, indirect fixtures…

Read article →
Software Testing

Retesting vs Regression Testing: 8 Key Differences with a Real Bug Fix Example

Retesting vs regression testing explained with a real bug fix run in pytest: retesting confirmed the fix, the regression run…

Read article →
Artificial Intelligence

RAG Chunking Strategies Explained: Fixed, Overlap, Sentence, Recursive and Headings, Measured

RAG chunking strategies compared on one document with tiktoken 0.14: fixed-size, overlap, sentence packing, recursive splitting and heading-based chunks, measuring…

Read article →
DevOps

Git Stash Explained: Save, Apply, Pop and Untracked Files, Tested

Git stash explained with commands we ran on Git 2.56: push with a message, untracked files, list and show, apply…

Read article →
Software Testing

Pairwise Testing Explained: How All-Pairs Cuts 216 Tests to 13, Tested

Pairwise testing explained with a generator we ran in Python 3.13: a checkout with 216 combinations covered by 13 tests,…

Read article →
Test Automation

Test Doubles Explained: Dummy, Stub, Spy, Mock and Fake, with Tested Python Code

Test doubles explained with one Python example run in pytest 9.2: dummy, stub, spy, mock and fake, when to use…

Read article →
Artificial Intelligence

LLM Context Window Explained: Tokens, Limits and How to Fit More, Measured

The LLM context window explained with token counts we measured using tiktoken: words vs tokens for prose, code and Hindi,…

Read article →
DevOps

Git Cherry-Pick Explained: Copy the Commit You Need, Safely, Tested

Git cherry-pick explained with commands we ran in Git 2.56: copying a hotfix to a release branch, new hashes and…

Read article →
Test Automation

Snapshot Testing Explained: How It Works, When It Helps and When It Hurts

Snapshot testing explained with a pytest and syrupy demo we ran: creating snapshots, reading the diff after a code change,…

Read article →
Software Testing

Mutation Testing Explained: Why 100% Coverage Still Missed Our Bug

Mutation testing explained with a small mutation tool we built and ran: 14 mutants, a test suite with 100% line…

Read article →