SYNOPSIS
--------
[verse]
-'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
+'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>]
<tagname> [<commit> | <object>]
'git tag' -d <tagname>...
-'git tag' [-n[<num>]] -l [--contains <commit>] [--points-at <object>]
- [--column[=<options>] | --no-column] [<pattern>...]
-'git tag' -v <tagname>...
+'git tag' [-n[<num>]] -l [--contains <commit>] [--contains <commit>]
+ [--points-at <object>] [--column[=<options>] | --no-column]
+ [--create-reflog] [--sort=<key>] [--format=<format>]
+ [--[no-]merged [<commit>]] [<pattern>...]
+'git tag' -v [--format=<format>] <tagname>...
DESCRIPTION
-----------
Unless `-f` is given, the named tag must not yet exist.
-If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
+If one of `-a`, `-s`, or `-u <keyid>` 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>` is given and `-a`, `-s`, and `-u <key-id>`
+If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
are absent, `-a` is implied.
Otherwise just a tag reference for the SHA-1 object name of the commit object is
created (i.e. a lightweight tag).
A GnuPG signed tag object will be created when `-s` or `-u
-<key-id>` is used. When `-u <key-id>` is not used, the
+<keyid>` is used. When `-u <keyid>` 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.
--sign::
Make a GPG-signed tag, using the default e-mail address's key.
--u <key-id>::
---local-user=<key-id>::
+-u <keyid>::
+--local-user=<keyid>::
Make a GPG-signed tag, using the given key.
-f::
-v::
--verify::
- Verify the gpg signature of the given tag names.
+ 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.
- 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 <pattern>::
---list <pattern>::
- List tags with names that match the given pattern (or all if no
- pattern is given). 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.
-
---sort=<type>::
- Sort in a specific order. Supported type is "refname"
- (lexicographic order), "version:refname" or "v:refname" (tag
+ 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.prereleaseSuffix" configuration variable. Prepend
- "-" to reverse sort order. When this option is not given, the
- sort order defaults to the value configured for the 'tag.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`.
+ Sort order defaults to the value configured for the `tag.sort`
variable if it exists, or lexicographic order otherwise. See
linkgit:git-config[1].
+-i::
+--ignore-case::
+ Sorting and filtering tags are case insensitive.
+
--column[=<options>]::
--no-column::
Display tag listing in columns. See configuration variable
--contains [<commit>]::
Only list tags which contain the specified commit (HEAD if not
- specified).
+ specified). Implies `--list`.
+
+--no-contains [<commit>]::
+ Only list tags which don't contain the specified commit (HEAD if
+ not specified). Implies `--list`.
+
+--merged [<commit>]::
+ Only list tags whose commits are reachable from the specified
+ commit (`HEAD` if not specified), incompatible with `--no-merged`.
+
+--no-merged [<commit>]::
+ Only list tags whose commits are not reachable from the specified
+ commit (`HEAD` if not specified), incompatible with `--merged`.
--points-at <object>::
- Only list tags of the given object.
+ Only list tags of the given object (HEAD if not
+ specified). Implies `--list`.
-m <msg>::
--message=<msg>::
Use the given tag message (instead of prompting).
If multiple `-m` options are given, their values are
concatenated as separate paragraphs.
- Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
is given.
-F <file>::
--file=<file>::
Take the tag message from the given file. Use '-' to
read the message from the standard input.
- Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
+ Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
is given.
--cleanup=<mode>::
all, 'whitespace' removes just leading/trailing whitespace lines and
'strip' removes both whitespace and commentary.
+--create-reflog::
+ Create a reflog for the tag. To globally enable reflogs for tags, see
+ `core.logAllRefUpdates` in linkgit:git-config[1].
+ The negated form `--no-create-reflog` only overrides an earlier
+ `--create-reflog`, but currently does not negate the setting of
+ `core.logallrefupdates`.
+
<tagname>::
The name of the tag to create, delete, or describe.
The new tag name must pass all checks defined by
The object that the new tag will refer to, usually a commit.
Defaults to HEAD.
+<format>::
+ A string that interpolates `%(fieldname)` from the object
+ pointed at by a ref being shown. The format is the same as
+ that of linkgit:git-for-each-ref[1]. When unspecified,
+ defaults to `%(refname:strip=2)`.
CONFIGURATION
-------------
-------------------------------------
[user]
- signingKey = <gpg-key-id>
+ signingKey = <gpg-keyid>
-------------------------------------
~~~~~~~~~~~~~~~~~~~~~~
If you are following somebody else's tree, you are most likely
-using remote-tracking branches (`refs/heads/origin` in traditional
-layout, or `refs/remotes/origin/master` in the separate-remote
-layout). You usually want the tags from the other end.
+using remote-tracking branches (eg. `refs/remotes/origin/master`).
+You usually want the tags from the other end.
On the other hand, if you are fetching because you would want a
one-shot merge from somebody else, you typically do not want to