Git tag are used to manage software releases. They act as fixed points in your project’s history, much like branches that do not change. This is particularly useful for marking significant commits, such as public releases, ensuring they remain immutable.
Initial Example
In Git, tags are helpful, and you can use them to manage the release. You can think of a Git tag like a branch that will not change. It is significantly more important if you are making a public release.
$ git tag -a v1.0.0 -m "Release version 1.0.0"
TAG Options
| Option | Description |
|---|---|
-a, --annotate | Create an unsigned, annotated tag object. Annotated tags store additional metadata such as the tagger name, email, date, and a message. |
-s, --sign | Create a GPG-signed tag, using the default email address’s key. Tag GPG-signing is controlled by the tag.gpgSign configuration variable if it exists, or disabled otherwise. See git-config. |
--no-sign | Override the tag.gpgSign configuration variable, which forces each tag to be signed. This option creates a tag without a GPG signature. |
-u <key-id>, --local-user=<key-id> | Create a GPG-signed tag using the specified key. This allows you to sign tags with a specific key instead of the default one. |
-f, --force | Replace an existing tag with the given name instead of failing. Useful for updating tags to point to new commits. |
-d, --delete | Delete existing tags with the given names. This permanently removes the tag from the repository. |
-v, --verify | Verify the GPG signature of the specified tag names. This ensures the tag was created by a trusted source. |
-n<num> | Print <num> lines from the annotation when using -l. Implies --list. If no number is given, only the first line is printed. If the tag is not annotated, the commit message is displayed instead. |
-l, --list | List tags. Optionally, list tags matching specified patterns, e.g., git tag --list 'v-*'. |
--sort=<key> | Sort tags based on the specified key. Prefix with - to sort in descending order. Supports multiple keys and “version:refname” sort order. Defaults to tag.sort configuration if it exists or lexicographic order otherwise. |
--color[=<when>] | Respect any colors specified in the --format option. Values for <when> are always, never, or auto (default is always). |
-i, --ignore-case | Perform case-insensitive sorting and filtering of tags. |
--omit-empty | Do not print a newline after formatted refs where the format expands to an empty string. |
--column[=<options>], --no-column | Display tag listing in columns. See configuration variable column.tag for option syntax. --column and --no-column without options default to always and never, respectively. Applicable only when listing tags without annotation lines. |
--contains [<commit>] | Only list tags which contain the specified commit (defaults to HEAD if not specified). Implies --list. |
--no-contains [<commit>] | Only list tags which don’t contain the specified commit (defaults to HEAD if not specified). Implies --list. |
--merged [<commit>] | Only list tags whose commits are reachable from the specified commit (defaults to HEAD if not specified). |
--no-merged [<commit>] | Only list tags whose commits are not reachable from the specified commit (defaults to HEAD if not specified). |
--points-at <object> | Only list tags pointing to the given object (defaults to HEAD if not specified). Implies --list. |
-m <msg>, --message=<msg> | Use the given tag message instead of prompting. Multiple -m options concatenate their values as separate paragraphs. Implies -a if none of -a, -s, or -u <key-id> is given. |
-F <file>, --file=<file> | Take the tag message from the specified file. Use - to read the message from standard input. Implies -a if none of -a, -s, or -u <key-id> is given. |
--trailer <token>[(=|:)<value>] | Apply a specified trailer token and value to the tag message. Configuration variables define handling of duplicated trailers, appearance order, and other details. Trailers can be extracted with git tag --list --format="%(trailers)". |
-e, --edit | Edit the message taken from file with -F and command line with -m. |
--cleanup=<mode> | Set how the tag message is cleaned up. Modes: verbatim, whitespace, and strip (default). |
--create-reflog | Create a reflog for the tag. To enable globally, see core.logAllRefUpdates. Negated form --no-create-reflog overrides an earlier --create-reflog, but does not negate core.logAllRefUpdates setting. |
--format=<format> | Interpolate %(fieldname) from a tag ref and the object it points at. Defaults to %(refname:strip=2) if unspecified. |
Examples
1. Creating an Annotated Tag
This example demonstrates how to create an annotated tag with a message.
$ git tag -a v1.0.0 -m "Release version 1.0.0"
2. Listing All Tags
This example shows how to list all the tags in your repository.
$ git tag
3. Viewing Tag Details
This example illustrates how to view the details of a specific tag.
$ git show v1.0.0
4. Deleting a Tag
This example explains how to delete a tag from your repository.
$ git tag -d v1.0.0
5. Pushing Tags to Remote Repository
This example demonstrates how to push a tag to your remote repository.
$ git push origin v1.0.0
6. Pushing All Tags
This example shows how to push all tags to the remote repository.
$ git push origin --tags