SYNOPSIS
--------
-[verse]
-'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
+[synopsis]
+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>]
+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>...
+git tag -v [--format=<format>] <tagname>...
DESCRIPTION
-----------
-Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
+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.
OPTIONS
-------
--a::
---annotate::
+`-a`::
+`--annotate`::
Make an unsigned, annotated tag object
--s::
---sign::
+`-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::
+`--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>::
+`-u <key-id>`::
+`--local-user=<key-id>`::
Make a GPG-signed tag, using the given key.
--f::
---force::
+`-f`::
+`--force`::
Replace an existing tag with the given name (instead of failing)
--d::
---delete::
+`-d`::
+`--delete`::
Delete existing tags with the given names.
--v::
---verify::
+`-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`.
+`-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::
+`-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
+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=<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"
+ 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`.
Sort order defaults to the value configured for the `tag.sort`
variable if it exists, or lexicographic order otherwise. See
linkgit:git-config[1].
---color[=<when>]::
+`--color[=<when>]`::
Respect any colors specified in the `--format` option. The
- `<when>` field must be one of `always`, `never`, or `auto` (if
- `<when>` is absent, behave as if `always` was given).
+ _<when>_ field must be one of `always`, `never`, or `auto` (if
+ _<when>_ is absent, behave as if `always` was given).
--i::
---ignore-case::
+`-i`::
+`--ignore-case`::
Sorting and filtering tags are case insensitive.
---omit-empty::
+`--omit-empty`::
Do not print a newline after formatted refs where the format expands
to the empty string.
---column[=<options>]::
---no-column::
+`--column[=<options>]`::
+`--no-column`::
Display tag listing in columns. See configuration variable
`column.tag` for option syntax. `--column` and `--no-column`
- without options are equivalent to 'always' and 'never' respectively.
+ without options are equivalent to `always` and `never` respectively.
+
This option is only applicable when listing tags without annotation lines.
---contains [<commit>]::
- Only list tags which contain the specified commit (HEAD if not
+`--contains [<commit>]`::
+ Only list tags which contain _<commit>_ (`HEAD` if not
specified). Implies `--list`.
---no-contains [<commit>]::
- Only list tags which don't contain the specified commit (HEAD if
+`--no-contains [<commit>]`::
+ Only list tags which don't contain _<commit>_ (`HEAD` if
not specified). Implies `--list`.
---merged [<commit>]::
- Only list tags whose commits are reachable from the specified
- commit (`HEAD` if not specified).
+`--merged [<commit>]`::
+ Only list tags whose commits are reachable from
+ _<commit>_ (`HEAD` if not specified).
---no-merged [<commit>]::
- Only list tags whose commits are not reachable from the specified
- commit (`HEAD` if not specified).
+`--no-merged [<commit>]`::
+ Only list tags whose commits are not reachable from
+ _<commit>_ (`HEAD` if not specified).
---points-at <object>::
- Only list tags of the given object (HEAD if not
+`--points-at [<object>]`::
+ Only list tags of _<object>_ (`HEAD` if not
specified). Implies `--list`.
--m <msg>::
---message=<msg>::
- Use the given tag message (instead of prompting).
+`-m <msg>`::
+`--message=<msg>`::
+ Use _<msg>_ (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>`
is given.
--F <file>::
---file=<file>::
- Take the tag message from the given file. Use '-' to
+`-F <file>`::
+`--file=<file>`::
+ Take the tag message from _<file>_. Use `-` to
read the message from the standard input.
Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
---trailer <token>[(=|:)<value>]::
- Specify a (<token>, <value>) pair that should be applied as a
+`--trailer <token>[(=|:)<value>]`::
+ Specify a (_<token>_, _<value>_) pair that should be applied as a
trailer. (e.g. `git tag --trailer "Custom-Key: value"`
will add a "Custom-Key" trailer to the tag message.)
The `trailer.*` configuration variables
The trailers can be extracted in `git tag --list`, using
`--format="%(trailers)"` placeholder.
--e::
---edit::
- The message taken from file with `-F` and command line with
- `-m` are usually used as the tag message unmodified.
- This option lets you further edit the message taken from these sources.
+`-e`::
+`--edit`::
+ Let further edit the message taken from file with `-F` and command line with
+ `-m`.
---cleanup=<mode>::
- This option sets how the tag message is cleaned up.
- The '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'. The
- 'strip' mode is default. The 'verbatim' mode does not change message at
- all, 'whitespace' removes just leading/trailing whitespace lines and
- 'strip' removes both whitespace and commentary.
+`--cleanup=<mode>`::
+ Set how the tag message is cleaned up.
+ The _<mode>_ can be one of `verbatim`, `whitespace` and `strip`. The
+ `strip` mode is default. The `verbatim` mode does not change message at
+ all, `whitespace` removes just leading/trailing whitespace lines and
+ `strip` removes both whitespace and commentary.
---create-reflog::
+`--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`.
---format=<format>::
+`--format=<format>`::
A string that interpolates `%(fieldname)` from a tag ref being shown
and the object it points at. The format is the same as
that of linkgit:git-for-each-ref[1]. When unspecified,
defaults to `%(refname:strip=2)`.
-<tagname>::
+_<tagname>_::
The name of the tag to create, delete, or describe.
The new tag name must pass all checks defined by
linkgit:git-check-ref-format[1]. Some of these checks
may restrict the characters allowed in a tag name.
-<commit>::
-<object>::
+_<commit>_::
+_<object>_::
The object that the new tag will refer to, usually a commit.
- Defaults to HEAD.
+ Defaults to `HEAD`.
CONFIGURATION
-------------
-By default, 'git tag' in sign-with-default mode (-s) will use your
+By default, `git tag` in sign-with-default mode (`-s`) will use your
committer identity (of the form `Your Name <your@email.address>`) to
find a key. If you want to use a different default key, you can specify
it in the repository configuration as follows:
What should you do when you tag a wrong commit and you would
want to re-tag?
-If you never pushed anything out, just re-tag it. Use "-f" to
+If you never pushed anything out, just re-tag it. Use `-f` to
replace the old one. And you're done.
But if you have pushed things out (or others could just read
. The insane thing.
You really want to call the new version "X" too, 'even though'
- others have already seen the old one. So just use 'git tag -f'
+ others have already seen the old one. So just use `git tag -f`
again, as if you hadn't already published the old one.
However, Git does *not* (and it should not) change tags behind
users back. So if somebody already got the old tag, doing a
-'git pull' on your tree shouldn't just make them overwrite the old
+`git pull` on your tree shouldn't just make them overwrite the old
one.
If somebody got a release tag from you, you cannot just change
Often, "please pull" messages on the mailing list just provide
two pieces of information: a repo URL and a branch name; this
-is designed to be easily cut&pasted at the end of a 'git fetch'
+is designed to be easily cut&pasted at the end of a `git fetch`
command line:
------------
user in an editor session will be available in this file, but
may be overwritten by the next invocation of `git tag`.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.adoc[]
+
+:git-tag: 1
+include::config/tag.adoc[]
+
NOTES
-----
projects / thirdparty / git.git / commitdiff
