Guide to Manually Create and Push a Git Tag

Tags in Git and GitHub mark specific milestones in a repository’s commit history, primarily used for release versions (e.g. v1.0.0, v2.4.1).

Here is a quick, reference guide to creating, pushing, and managing Git tags locally and on remote repositories.

1. Creating Git Tags

Annotated Tag (Recommended for Production Releases)

Annotated tags are stored as full objects in the Git database. They contain the tagger name, email, date, and a release message:

git tag -a v1.0.0 -m "Release version 1.0.0"

Lightweight Tag (Simple Pointer)

A lightweight tag is simply a pointer/bookmark to a specific commit without extra metadata:

git tag v1.0.0

2. Pushing Tags to GitHub / Remote

Git does not push tags automatically when running git push. You must explicitly push them:

Push a Specific Tag

git push origin v1.0.0

Push All Local Tags at Once

git push origin --tags

⚠️ Warning: Use git push origin --tags with caution! It will upload every local tag on your machine to the remote repository, including any old or test tags.

3. Updating and Force-Pushing a Tag

If you need to move a tag to a newer commit or fix a release tag:

git tag -f v1.0.0
git push -f origin v1.0.0

🛑 Caution: Force-pushing a tag overwrites the remote reference. Communicate with your team first to prevent sync conflicts for other developers.

4. Listing and Verifying Tags

List Tags Locally

git tag -n

Verify Tags on Remote (GitHub)

git ls-remote --tags origin

Best Practices Checklist

1. Always prefer annotated tags (-a) for official software releases so audit metadata is preserved.
2. Use Semantic Versioning (vMAJOR.MINOR.PATCH e.g., v1.2.0).
3. Never rely on automatic pushing — remember to run git push origin <tagname>.
4. Delete unwanted local tags before running bulk tag push:

   git tag -d <unwanted-tag>