--------
[verse]
'git tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
- <name> [<commit> | <object>]
-'git tag' -d <name>...
-'git tag' [-n[<num>]] -l [<pattern>]
-'git tag' -v <name>...
+ <tagname> [<commit> | <object>]
+'git tag' -d <tagname>...
+'git tag' [-n[<num>]] -l [
--contains <commit>] [<pattern>]
+'git tag' -v <tagname>...
DESCRIPTION
-----------
-Adds a 'tag' reference in `.git/refs/tags/`
-Unless `-f` is given, the tag must not yet exist in
+Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given
+to delete, list or verify tags.
+
+Unless `-f` is given, the tag to be created must not yet exist in the
`.git/refs/tags/` directory.
If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
-creates a 'tag' object, and requires the tag message. Unless
+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>`
are absent, `-a` is implied.
-Otherwise just the SHA1 object name of the commit object is
-written (i.e. a lightweight tag).
+Otherwise just a tag reference for the SHA1 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
Make a GPG-signed tag, using the given key
-f::
+--force::
Replace an existing tag with the given name (instead of failing)
-d::
List tags with names that match the given pattern (or all if no pattern is given).
Typing "git tag" without arguments, also lists all tags.
+--contains <commit>::
+ Only list tags which contain the specified commit.
+
-m <msg>::
Use the given tag message (instead of prompting).
If multiple `-m` options are given, their values are
Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
is given.
+<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.
+
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:
. 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
~~~~~~~~~~~~~~~~~~~~~~
If you are following somebody else's tree, you are most likely
-using tracking branches (`refs/heads/origin` in traditional
+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.
You would notice "please pull" messages on the mailing list says
repo URL and branch name alone. This is designed to be easily
-cut&pasted to a 'git-fetch' command line:
+cut&pasted to a 'git fetch' command line:
------------
Linus, please pull from
It may well be that among networking people, they may want to
exchange the tags internal to their group, but in that workflow
they are most likely tracking with each other's progress by
-having tracking branches. Again, the heuristic to automatically
+having remote-tracking branches. Again, the heuristic to automatically
follow such tags is a good thing.
------------
+SEE ALSO
+--------
+linkgit:git-check-ref-format[1].
+
Author
------
Written by Linus Torvalds <torvalds@osdl.org>,