git-tag(1)
==========

NAME
----
git-tag - Create, list, delete or verify a tag object signed with GPG


SYNOPSIS
--------
[verse]
'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
	[(--trailer <token>[(=|:)<value>])...]
	<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
	[--points-at <object>] [--column[=<options>] | --no-column]
	[--create-reflog] [--sort=<key>] [--format=<format>]
	[--merged <commit>] [--no-merged <commit>] [<pattern>...]
'git tag' -v [--format=<format>] <tagname>...

DESCRIPTION
-----------

Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
to delete, list or verify tags.

Unless `-f` is given, the named tag must not yet exist.

If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
creates a 'tag' object, and requires a tag message.  Unless
`-m <msg>` or `-F <file>` is given, an editor is started for the user to type
in the tag message.

If `-m <msg>` or `-F <file>` or `--trailer <token>[=<value>]` is given
and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied.

Otherwise, a tag reference that points directly at the given object
(i.e., a lightweight tag) is created.

A GnuPG signed tag object will be created when `-s` or `-u
<key-id>` is used.  When `-u <key-id>` is not used, the
committer identity for the current user is used to find the
GnuPG key for signing. 	The configuration variable `gpg.program`
is used to specify custom GnuPG binary.

Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
tags; they contain a creation date, the tagger name and e-mail, a
tagging message, and an optional GnuPG signature. Whereas a
"lightweight" tag is simply a name for an object (usually a commit
object).

Annotated tags are meant for release while lightweight tags are meant
for private or temporary object labels. For this reason, some git
commands for naming objects (like `git describe`) will ignore
lightweight tags by default.


OPTIONS
-------
-a::
--annotate::
	Make an unsigned, annotated tag object

-s::
--sign::
	Make a GPG-signed tag, using the default e-mail address's key.
	The default behavior of tag GPG-signing is controlled by `tag.gpgSign`
	configuration variable if it exists, or disabled otherwise.
	See linkgit:git-config[1].

--no-sign::
	Override `tag.gpgSign` configuration variable that is
	set to force each and every tag to be signed.

-u <key-id>::
--local-user=<key-id>::
	Make a GPG-signed tag, using the given key.

-f::
--force::
	Replace an existing tag with the given name (instead of failing)

-d::
--delete::
	Delete existing tags with the given names.

-v::
--verify::
	Verify the GPG signature of the given tag names.

-n<num>::
	<num> specifies how many lines from the annotation, if any,
	are printed when using -l. Implies `--list`.
+
The default is not to print any annotation lines.
If no number is given to `-n`, only the first line is printed.
If the tag is not annotated, the commit message is displayed instead.

-l::
--list::
	List tags. With optional `<pattern>...`, e.g. `git tag --list
	'v-*'`, list only the tags that match the pattern(s).
+
Running "git tag" without arguments also lists all tags. The pattern
is a shell wildcard (i.e., matched using fnmatch(3)). Multiple
patterns may be given; if any of them matches, the tag is shown.
+
This option is implicitly supplied if any other list-like option such
as `--contains` is provided. See the documentation for each of those
options for details.

--sort=<key>::
	Sort based on the key given.  Prefix `-` to sort in
	descending order of the value. You may use the --sort=<key> option
	multiple times, in which case the last key becomes the primary
	key. Also supports "version:refname" or "v:refname" (tag
	names are treated as versions). The "version:refname" sort
	order can also be affected by the "versionsort.suffix"
	configuration variable.
	The keys supported are the same as those in `git for-each-ref`.