git-tag

List all tags

$ git tag

$ git tag [tag_name]

$ git tag [tag_name] [commit]

$ git tag [tag_name] [[-m|--message]] [tag_message]

$ git tag [[-d|--delete]] [tag_name]

$ git fetch [[-t|--tags]]

$ git push origin tag [tag_name]

$ git tag --contains [commit]

git tag [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] <tagname> [<commit> | <object>]
git tag -d <tagname>...
git tag [-l | --list] [--contains <commit>] [--no-contains <commit>] [--points-at <object>] [--sort=<key>] [<pattern>...]
git tag -v <tagname>...

<tagname>
    The name of the tag to create, delete, or verify.

<commit>
    The commit object the tag will point to. Defaults to HEAD if not specified.

-a, --annotate
    Create an annotated tag. This is recommended for releases as it stores metadata like tagger name, email, and date.

-s, --sign
    Create a GPG-signed tag. Requires a GPG key configured in Git. Ensures the integrity and authenticity of the tag.

-u <keyid>, --local-user=<keyid>
    Use the specified GPG key to sign the tag, instead of the default.

-m <msg>, --message=<msg>
    Use the given message as the tag message. If multiple -m options are given, their values are concatenated as separate paragraphs.

-F <file>, --file=<file>
    Take the tag message from the given file. Use - to read from standard input.

-d, --delete
    Delete the specified tags.

-f, --force
    Replace an existing tag with the new one (object or message). Use with caution as it rewrites history for others.

-l, --list
    List tags with optional patterns. This is the default action if no other options are given.

-v, --verify
    Verify the GPG signature of the given tags.

--contains <commit>
    Only list tags that contain the specified commit.

--no-contains <commit>
    Only list tags that do not contain the specified commit.

--points-at <object>
    Only list tags that point at the given object (e.g., a commit, tree, or blob).

--sort=<key>
    Sort the output of tags based on the specified key (e.g., version:refname, creatordate).

The git tag command is used to create, list, delete, and verify tags in a Git repository. Tags are permanent pointers to specific points in history, commonly used to mark release points (e.g., v1.0, v2.0). Unlike branches, tags are not meant to move once created. Git supports two main types of tags:

1. Lightweight Tags: These are simply pointers to a specific commit. They are like a branch that never moves, typically used for private or temporary tagging.
2. Annotated Tags: These are full Git objects stored in the Git database. They contain a tagger name, email, date, and a tagging message, and can be GPG-signed for verification. Annotated tags are recommended for public releases because they provide valuable metadata and ensure authenticity. They are immutable and point to a specific commit.

The command allows users to list existing tags, create new ones (either lightweight or annotated), delete obsolete tags, and verify the cryptographic signatures of signed tags, ensuring the integrity and origin of the tagged commit. Tags are crucial for navigation and stable release management in Git workflows.

• Tags are not automatically pushed: Unlike branches, Git tags are not automatically pushed to remote repositories when you run git push. You must explicitly push tags using git push --tags or git push origin <tagname>.
• Replacing tags with --force: Using the -f or --force option to overwrite an existing tag is generally discouraged, especially on shared repositories, as it can cause confusion and issues for other collaborators who might have already fetched the original tag. If a tag needs to be moved or corrected, it's often better to delete the old tag and create a new one, communicating the change.
• Annotated vs. Lightweight: Always prefer annotated tags for releases or public milestones. Lightweight tags lack important metadata (tagger, date, message) and cannot be signed, making them less suitable for formal releases and integrity checks.

Lightweight tags are simple pointers to a commit, similar to a local branch that doesn't move. They contain no extra information.

Annotated tags are full Git objects. They include the tagger's name, email, date, and a tagging message. They can also be GPG-signed, providing authenticity verification. For public releases or important milestones, annotated tags are strongly recommended due to their rich metadata and verifiability. Use -a for annotated, or -s for signed annotated tags.

When creating an annotated tag, you can sign it using your GPG key with the -s (--sign) option. This cryptographic signature ensures that the tag was indeed created by you and that its contents have not been tampered with. Others can then verify the tag's authenticity using git tag -v <tagname>, adding a layer of trust to your releases.

By default, git push does not push your tags to the remote repository. To share your tags, you must explicitly push them. You can push all local tags that are not yet on the remote using git push --tags. Alternatively, to push a specific tag, use git push <remote> <tagname>. Remember that once a tag is pushed, changing or deleting it on the remote requires extra care and coordination.

The concept of tagging specific points in history has been a fundamental feature of version control systems long before Git. In Git, tags were integral to its design from the outset, providing a stable, immutable reference for key project milestones like releases. The distinction between lightweight and annotated tags, with the latter being full Git objects capable of carrying metadata and GPG signatures, reflects Git's emphasis on data integrity and decentralized trust. While the core functionality has remained consistent, the command has seen enhancements in listing capabilities (e.g., --contains, --sort) and verification options to support complex repository histories and secure release management practices. Its usage remains central to publishing stable software versions.

git-branch(1), git-log(1), git-show(1), git-push(1), git-describe(1), git-verify-tag(1)