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 whose ancestors include a given commit
$ git tag --contains [commit]
copy

SYNOPSIS

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]...

PARAMETERS

<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.

DESCRIPTION

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.

CAVEATS

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.

TAG TYPES

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.

TAG VERIFICATION

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.

SEE ALSO

Copied to clipboard