git tag -a / -d: Usage, Options & Common CI Errors

git tag -a creates an annotated release tag; git tag -d removes a tag from your local repo.

Annotated tags carry an author, date, message, and optional signature - the right choice for releases. Deletion is local only; the remote tag needs a separate push to remove.

What it does

git tag -a creates an annotated tag object (stored with tagger, date, and message), unlike a lightweight tag which is just a pointer. git tag -d removes the named tag from the local repository.

Common usage

Terminal

git tag -a v1.2.0 -m "Release 1.2.0"
git tag -a v1.2.0 <sha> -m "Release"     # tag a specific commit
git tag -d v1.2.0                         # delete locally
git push origin v1.2.0                    # publish the tag
git push origin :refs/tags/v1.2.0         # delete on the remote

Options

Flag	What it does
-a / --annotate	Create an annotated tag
-m <msg>	Tag message (implies annotated)
-s / --sign	GPG-sign the tag
-d / --delete	Delete a tag locally
-f / --force	Move an existing tag

Common errors in CI

fatal: tag 'vX' already exists - re-tagging needs -f locally and git push --force origin vX (or delete-then-push) on the remote. Deleting locally with -d does not remove the remote tag; push the :refs/tags/<name> deletion explicitly.

Related guides

git verify-tag: Usage, Options & Common CI Errorsgit verify-tag checks the signature on an annotated tag. Reference for --raw, -v, exit codes, and the lightwe… git tag: Usage, Options & Common CI Errorsgit tag creates and lists tags for releases. Reference for -a, -m, -d, pushing tags, and the "tag already exi… git describe: Usage, Options & Common CI Errorsgit describe produces a readable name from the nearest tag, ideal for build versions. Reference for --tags, -… git push: Usage, Options & Common CI Errorsgit push uploads local commits to a remote. Reference for -u, --force-with-lease, and tags, plus the rejected…