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>] [-m <msg> | -F <file>] <tagname> [<commit> | <object>]
git tag -d <tagname>...
git tag [-n[]] [--contains <commit>] [--no-contains <commit>] [--points-at <object>] [-l] [-f] [-v] [--sort=] [--merged []] [--no-merged []] [--force-if-includes]...

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

<commit>
    The commit or object to tag. Defaults to the current HEAD.

-a
    Create an annotated tag object.

-s
    Create a GPG-signed tag object.

-u <keyid>
    Sign the tag using the given GPG key.

-m <msg>
    Use the given tag message.

-F <file>
    Read the tag message from the given file.

-d <tagname>...
    Delete the given tags.

-l
    List tags. Can be combined with patterns (e.g., git tag -l v1.*).

-n[<num>]
    Show the tag message. <num> specifies the number of lines to show.

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

--no-contains <commit>
    Only list tags which don't contain the specified commit.

--points-at <object>
    Only list tags which points to the specified object.

-f
    Force tag creation (replace an existing tag).

-v
    Verify a tag's GPG signature.

--sort=<key>
    Sort tags according to the specified key (e.g., refname, version:refname).

--merged [<commit>]
    Only list tags that are reachable from the specified commit (defaults to HEAD).

--no-merged [<commit>]
    Only list tags that are not reachable from the specified commit (defaults to HEAD).

--force-if-includes
    Allow replacing an existing tag with a new one only if the new tag includes the existing one.

The git tag command is used to create, list, verify, and delete tags, which are references to specific points in a Git repository's history.

Tags are typically used to mark release points (e.g., v1.0, v2.0-beta) or important milestones in the development process. They provide a more human-readable and persistent way to refer to specific commits than using commit hashes directly. Tags can be either annotated (recommended), containing metadata like the tagger, date, and a message, or lightweight, which are simply pointers to a commit. Annotated tags are stored as full objects in the Git database, making them more robust and allowing for signing.

This command allows you to manage these tags, making them invaluable for version control and release management within your Git workflow. It supports creating, listing, deleting, and verifying tags.

Deleting a tag only removes the reference, not the commit it pointed to. Force-creating tags with -f can lead to unexpected behavior if the tag is already shared with others, especially if they have already based work on the tag. Always be careful when using the force option.

There are two main types of tags: lightweight and annotated. Lightweight tags are simply references to commits, while annotated tags are full Git objects that include a message, tagger information, and can be GPG signed. Annotated tags are generally preferred because they provide more context and security.

Using the -v option with git tag allows you to verify the GPG signature of an annotated tag, ensuring its authenticity. This is crucial for projects where security is paramount.

git-branch(1), git-checkout(1), git-describe(1)