LinuxCommandLibrary

git-tag

Create, list, or delete Git tags

TLDR

List all tags

$ git tag
copy

Create a tag with the given name pointing to the current commit
$ git tag [tag_name]
copy

Create a tag with the given name pointing to a given commit
$ git tag [tag_name] [commit]
copy

Create an annotated tag with the given message
$ git tag [tag_name] [[-m|--message]] [tag_message]
copy

Delete the tag with the given name
$ git tag [[-d|--delete]] [tag_name]
copy

Get updated tags from remote
$ git fetch [[-t|--tags]]
copy

Push a tag to remote
$ git push origin tag [tag_name]
copy

List all tags which contain a given commit (HEAD if not specified)
$ git tag --contains [commit]
copy

SYNOPSIS

git tag [options...] [tagname] [commitish]
git tag -l [pattern...]
git tag -d tagname...
git tag --verify tagname...
git tag --list-tags [pattern]

PARAMETERS

-a, --annotate
    Create annotated tag object

-s, --sign
    Create GPG-signed tag object

-u , --local-user=
    Use specified key for signing

-f, --force
    Overwrite existing tag

-d, --delete
    Delete specified tags

-l [], --list []
    List tags matching pattern

-n[]
    List with num lines of tag annotation

-m , --message=
    Use given tag message

-F , --file=
    Read message from file

-e, --edit
    Open editor for tag message

--verify
    Verify GPG signature of tags

--contains []
    List tags containing commit

--no-contains
    List tags not containing commit

--points-at
    List tags pointing at object

--merged []
    List tags merged into commit

--no-merged []
    List tags not merged into commit

--sort=
    Sort tags by key (e.g., version:refname)

--format=
    Format output

--count[=]
    Limit to first n tags

--column[=]
    Display in columns

--no-column
    Disable columnar output

--create-reflog
    Create reflog for tag updates

--cleanup[=]
    How to strip spaces from message

--list-tags []
    Porcelain format tag list

-v, --verbose
    Verbose output

-q, --quiet
    Suppress output

DESCRIPTION

The git tag command manages tags in a Git repository. Tags are fixed references to specific commits, ideal for marking releases, versions, or milestones. There are two main types: lightweight tags (simple pointers, like branches but immovable) and annotated tags (full objects with tagger name, email, date, and message, stored permanently in the Git database).

Annotated tags can also be signed with GPG for verification. Common workflow: create a tag with git tag -a v1.0.0 -m "Release 1.0.0", list with git tag -l, push with git push origin v1.0.0. Tags do not move with new commits, ensuring stability.

Use git tag --list --sort=-v:refname for version-sorted lists, or git tag -d tagname to delete locally. Verify signed tags with git tag --verify. Tags enhance release management and are often used in CI/CD pipelines for deployment triggers. Unlike branches, tags are not updated automatically.

CAVEATS

Tags are immutable; deleting pushed tags requires git push --delete or force-push, rewriting shared history.
Lightweight tags are refs only, not pushed by default with git push --tags needed for all.
Signed tags require GPG setup; invalid keys cause failures.

TAG TYPES

Lightweight: git tag tagname – simple ref pointer.
Annotated: git tag -a tagname -m "msg" – object with metadata.
Signed: git tag -s tagname – annotated + GPG signature.

EXAMPLES

git tag v1.0.0 HEAD (lightweight)
git tag -a v1.0.0 -m "Release" (annotated)
git tag -l 'v1.*' (list)
git push origin --tags (push all)

HISTORY

Introduced in Git 1.0.0 (April 2005) by Linus Torvalds. Annotated tags added early for metadata. Signing support in v1.7.9 (2011). Listing/sort/format enhancements in v1.8+ (2012-). Version sorting (--sort=version:refname) in v2.0 (2014). Now essential for semantic versioning in open-source projects.

SEE ALSO

git-branch(1), git-for-each-ref(1), git-show(1), git-log(1), git-push(1)

Copied to clipboard