2005-09-08 00:26:23 +00:00
|
|
|
git-tag(1)
|
|
|
|
==========
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
NAME
|
|
|
|
----
|
2007-01-20 18:47:41 +00:00
|
|
|
git-tag - Create, list, delete or verify a tag object signed with GPG
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
--------
|
2006-02-17 12:04:39 +00:00
|
|
|
[verse]
|
2015-09-19 07:47:48 +00:00
|
|
|
'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>]
|
2009-08-22 00:45:18 +00:00
|
|
|
<tagname> [<commit> | <object>]
|
|
|
|
'git tag' -d <tagname>...
|
2017-05-15 12:23:31 +00:00
|
|
|
'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
|
2017-03-24 18:40:58 +00:00
|
|
|
[--points-at <object>] [--column[=<options>] | --no-column]
|
|
|
|
[--create-reflog] [--sort=<key>] [--format=<format>]
|
|
|
|
[--[no-]merged [<commit>]] [<pattern>...]
|
2017-01-17 23:37:21 +00:00
|
|
|
'git tag' -v [--format=<format>] <tagname>...
|
2005-05-10 21:32:30 +00:00
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
-----------
|
2009-08-05 21:20:32 +00:00
|
|
|
|
2012-08-06 20:36:47 +00:00
|
|
|
Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
|
2011-02-15 13:09:10 +00:00
|
|
|
to delete, list or verify tags.
|
2005-07-25 06:17:16 +00:00
|
|
|
|
2012-08-06 20:36:47 +00:00
|
|
|
Unless `-f` is given, the named tag must not yet exist.
|
2005-07-25 06:17:16 +00:00
|
|
|
|
2015-09-19 07:47:48 +00:00
|
|
|
If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
|
2011-02-15 13:09:10 +00:00
|
|
|
creates a 'tag' object, and requires a tag message. Unless
|
2007-07-19 23:42:28 +00:00
|
|
|
`-m <msg>` or `-F <file>` is given, an editor is started for the user to type
|
2005-10-06 21:10:39 +00:00
|
|
|
in the tag message.
|
2005-07-25 06:17:16 +00:00
|
|
|
|
2015-09-19 07:47:48 +00:00
|
|
|
If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
|
2008-03-24 19:43:08 +00:00
|
|
|
are absent, `-a` is implied.
|
|
|
|
|
2013-04-15 17:49:04 +00:00
|
|
|
Otherwise just a tag reference for the SHA-1 object name of the commit object is
|
2011-02-15 13:09:10 +00:00
|
|
|
created (i.e. a lightweight tag).
|
2005-10-06 21:10:39 +00:00
|
|
|
|
|
|
|
A GnuPG signed tag object will be created when `-s` or `-u
|
2015-09-19 07:47:48 +00:00
|
|
|
<keyid>` is used. When `-u <keyid>` is not used, the
|
2005-10-06 21:10:39 +00:00
|
|
|
committer identity for the current user is used to find the
|
2011-11-29 20:29:48 +00:00
|
|
|
GnuPG key for signing. The configuration variable `gpg.program`
|
|
|
|
is used to specify custom GnuPG binary.
|
|
|
|
|
2014-10-04 16:27:16 +00:00
|
|
|
Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
|
2013-07-26 19:06:02 +00:00
|
|
|
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.
|
|
|
|
|
2005-05-10 21:32:30 +00:00
|
|
|
|
2005-12-08 23:28:05 +00:00
|
|
|
OPTIONS
|
|
|
|
-------
|
|
|
|
-a::
|
2011-08-28 14:54:29 +00:00
|
|
|
--annotate::
|
2005-12-08 23:28:05 +00:00
|
|
|
Make an unsigned, annotated tag object
|
|
|
|
|
|
|
|
-s::
|
2011-08-28 14:54:29 +00:00
|
|
|
--sign::
|
2011-11-29 20:29:48 +00:00
|
|
|
Make a GPG-signed tag, using the default e-mail address's key.
|
2005-12-08 23:28:05 +00:00
|
|
|
|
2015-09-19 07:47:48 +00:00
|
|
|
-u <keyid>::
|
|
|
|
--local-user=<keyid>::
|
2011-11-29 20:29:48 +00:00
|
|
|
Make a GPG-signed tag, using the given key.
|
2005-12-08 23:28:05 +00:00
|
|
|
|
|
|
|
-f::
|
2009-08-29 09:05:00 +00:00
|
|
|
--force::
|
2005-12-08 23:28:05 +00:00
|
|
|
Replace an existing tag with the given name (instead of failing)
|
|
|
|
|
|
|
|
-d::
|
2011-08-28 14:54:29 +00:00
|
|
|
--delete::
|
2007-01-20 18:47:41 +00:00
|
|
|
Delete existing tags with the given names.
|
2005-12-08 23:28:05 +00:00
|
|
|
|
2007-01-03 12:59:00 +00:00
|
|
|
-v::
|
2011-08-28 14:54:29 +00:00
|
|
|
--verify::
|
2016-06-16 22:15:44 +00:00
|
|
|
Verify the GPG signature of the given tag names.
|
2007-01-03 12:59:00 +00:00
|
|
|
|
2008-04-09 11:07:14 +00:00
|
|
|
-n<num>::
|
2007-06-03 00:05:39 +00:00
|
|
|
<num> specifies how many lines from the annotation, if any,
|
tag: implicitly supply --list given another list-like option
Change the "tag" command to implicitly turn on its --list mode when
provided with a list-like option such as --contains, --points-at etc.
This is for consistency with how "branch" works. When "branch" is
given a list-like option, such as --contains, it implicitly provides
--list. Before this change "tag" would error out on those sorts of
invocations. I.e. while both of these worked for "branch":
git branch --contains v2.8.0 <pattern>
git branch --list --contains v2.8.0 <pattern>
Only the latter form worked for "tag":
git tag --contains v2.8.0 '*rc*'
git tag --list --contains v2.8.0 '*rc*'
Now "tag", like "branch", will implicitly supply --list when a
list-like option is provided, and no other conflicting non-list
options (such as -d) are present on the command-line.
Spelunking through the history via:
git log --reverse -p -G'only allowed with' -- '*builtin*tag*c'
Reveals that there was no good reason for not allowing this in the
first place. The --contains option added in 32c35cfb1e ("git-tag: Add
--contains option", 2009-01-26) made this an error. All the other
subsequent list-like options that were added copied its pattern of
making this usage an error.
The only tests that break as a result of this change are tests that
were explicitly checking that this "branch-like" usage wasn't
permitted. Change those failing tests to check that this invocation
mode is permitted, add extra tests for the list-like options we
weren't testing, and tests to ensure that e.g. we don't toggle the
list mode in the presence of other conflicting non-list options.
With this change errors messages such as "--contains option is only
allowed with -l" don't make sense anymore, since options like
--contain turn on -l. Instead we error out when list-like options such
as --contain are used in conjunction with conflicting options such as
-d or -v.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-24 18:40:55 +00:00
|
|
|
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.
|
2007-06-03 00:05:39 +00:00
|
|
|
|
2017-03-24 18:40:54 +00:00
|
|
|
-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.
|
tag: implicitly supply --list given another list-like option
Change the "tag" command to implicitly turn on its --list mode when
provided with a list-like option such as --contains, --points-at etc.
This is for consistency with how "branch" works. When "branch" is
given a list-like option, such as --contains, it implicitly provides
--list. Before this change "tag" would error out on those sorts of
invocations. I.e. while both of these worked for "branch":
git branch --contains v2.8.0 <pattern>
git branch --list --contains v2.8.0 <pattern>
Only the latter form worked for "tag":
git tag --contains v2.8.0 '*rc*'
git tag --list --contains v2.8.0 '*rc*'
Now "tag", like "branch", will implicitly supply --list when a
list-like option is provided, and no other conflicting non-list
options (such as -d) are present on the command-line.
Spelunking through the history via:
git log --reverse -p -G'only allowed with' -- '*builtin*tag*c'
Reveals that there was no good reason for not allowing this in the
first place. The --contains option added in 32c35cfb1e ("git-tag: Add
--contains option", 2009-01-26) made this an error. All the other
subsequent list-like options that were added copied its pattern of
making this usage an error.
The only tests that break as a result of this change are tests that
were explicitly checking that this "branch-like" usage wasn't
permitted. Change those failing tests to check that this invocation
mode is permitted, add extra tests for the list-like options we
weren't testing, and tests to ensure that e.g. we don't toggle the
list mode in the presence of other conflicting non-list options.
With this change errors messages such as "--contains option is only
allowed with -l" don't make sense anymore, since options like
--contain turn on -l. Instead we error out when list-like options such
as --contain are used in conjunction with conflicting options such as
-d or -v.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-24 18:40:55 +00:00
|
|
|
+
|
|
|
|
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.
|
2006-02-17 12:04:39 +00:00
|
|
|
|
2015-09-11 15:06:16 +00:00
|
|
|
--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
|
2015-04-23 12:27:47 +00:00
|
|
|
names are treated as versions). The "version:refname" sort
|
versioncmp: generalize version sort suffix reordering
The 'versionsort.prereleaseSuffix' configuration variable, as its name
suggests, is supposed to only deal with tagnames with prerelease
suffixes, and allows sorting those prerelease tags in a user-defined
order before the suffixless main release tag, instead of sorting them
simply lexicographically.
However, the previous changes in this series resulted in an
interesting and useful property of version sort:
- The empty string as a configured suffix matches all tagnames,
including tagnames without any suffix, but
- tagnames containing a "real" configured suffix are still ordered
according to that real suffix, because any longer suffix takes
precedence over the empty string.
Exploiting this property we can easily generalize suffix reordering
and specify the order of tags with given suffixes not only before but
even after a main release tag by using the empty suffix to denote the
position of the main release tag, without any algorithm changes:
$ git -c versionsort.prereleaseSuffix=-alpha \
-c versionsort.prereleaseSuffix=-beta \
-c versionsort.prereleaseSuffix="" \
-c versionsort.prereleaseSuffix=-gamma \
-c versionsort.prereleaseSuffix=-delta \
tag -l --sort=version:refname 'v3.0*'
v3.0-alpha1
v3.0-beta1
v3.0
v3.0-gamma1
v3.0-delta1
Since 'versionsort.prereleaseSuffix' is not a fitting name for a
configuration variable to control this more general suffix reordering,
introduce the new variable 'versionsort.suffix'. Still keep the old
configuration variable name as a deprecated alias, though, to avoid
suddenly breaking setups already using it. Ignore the old variable if
both old and new configuration variables are set, but emit a warning
so users will be aware of it and can fix their configuration. Extend
the documentation to describe and add a test to check this more
general behavior.
Note: since the empty suffix matches all tagnames, tagnames with
suffixes not included in the configuration are listed together with
the suffixless main release tag, ordered lexicographically right after
that, i.e. before tags with suffixes listed in the configuration
following the empty suffix.
Signed-off-by: SZEDER Gábor <szeder.dev@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-12-08 14:24:01 +00:00
|
|
|
order can also be affected by the "versionsort.suffix"
|
|
|
|
configuration variable.
|
2015-09-11 15:06:16 +00:00
|
|
|
The keys supported are the same as those in `git for-each-ref`.
|
2016-06-08 17:23:16 +00:00
|
|
|
Sort order defaults to the value configured for the `tag.sort`
|
2015-04-23 12:27:47 +00:00
|
|
|
variable if it exists, or lexicographic order otherwise. See
|
|
|
|
linkgit:git-config[1].
|
2014-02-27 12:56:52 +00:00
|
|
|
|
2016-12-04 02:52:25 +00:00
|
|
|
-i::
|
|
|
|
--ignore-case::
|
|
|
|
Sorting and filtering tags are case insensitive.
|
|
|
|
|
2012-04-13 10:54:41 +00:00
|
|
|
--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.
|
|
|
|
+
|
|
|
|
This option is only applicable when listing tags without annotation lines.
|
|
|
|
|
2014-02-04 02:56:26 +00:00
|
|
|
--contains [<commit>]::
|
|
|
|
Only list tags which contain the specified commit (HEAD if not
|
tag: implicitly supply --list given another list-like option
Change the "tag" command to implicitly turn on its --list mode when
provided with a list-like option such as --contains, --points-at etc.
This is for consistency with how "branch" works. When "branch" is
given a list-like option, such as --contains, it implicitly provides
--list. Before this change "tag" would error out on those sorts of
invocations. I.e. while both of these worked for "branch":
git branch --contains v2.8.0 <pattern>
git branch --list --contains v2.8.0 <pattern>
Only the latter form worked for "tag":
git tag --contains v2.8.0 '*rc*'
git tag --list --contains v2.8.0 '*rc*'
Now "tag", like "branch", will implicitly supply --list when a
list-like option is provided, and no other conflicting non-list
options (such as -d) are present on the command-line.
Spelunking through the history via:
git log --reverse -p -G'only allowed with' -- '*builtin*tag*c'
Reveals that there was no good reason for not allowing this in the
first place. The --contains option added in 32c35cfb1e ("git-tag: Add
--contains option", 2009-01-26) made this an error. All the other
subsequent list-like options that were added copied its pattern of
making this usage an error.
The only tests that break as a result of this change are tests that
were explicitly checking that this "branch-like" usage wasn't
permitted. Change those failing tests to check that this invocation
mode is permitted, add extra tests for the list-like options we
weren't testing, and tests to ensure that e.g. we don't toggle the
list mode in the presence of other conflicting non-list options.
With this change errors messages such as "--contains option is only
allowed with -l" don't make sense anymore, since options like
--contain turn on -l. Instead we error out when list-like options such
as --contain are used in conjunction with conflicting options such as
-d or -v.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-24 18:40:55 +00:00
|
|
|
specified). Implies `--list`.
|
2009-01-26 14:13:25 +00:00
|
|
|
|
ref-filter: add --no-contains option to tag/branch/for-each-ref
Change the tag, branch & for-each-ref commands to have a --no-contains
option in addition to their longstanding --contains options.
This allows for finding the last-good rollout tag given a known-bad
<commit>. Given a hypothetically bad commit cf5c7253e0, the git
version to revert to can be found with this hacky two-liner:
(git tag -l 'v[0-9]*'; git tag -l --contains cf5c7253e0 'v[0-9]*') |
sort | uniq -c | grep -E '^ *1 ' | awk '{print $2}' | tail -n 10
With this new --no-contains option the same can be achieved with:
git tag -l --no-contains cf5c7253e0 'v[0-9]*' | sort | tail -n 10
As the filtering machinery is shared between the tag, branch &
for-each-ref commands, implement this for those commands too. A
practical use for this with "branch" is e.g. finding branches which
were branched off between v2.8.0 and v2.10.0:
git branch --contains v2.8.0 --no-contains v2.10.0
The "describe" command also has a --contains option, but its semantics
are unrelated to what tag/branch/for-each-ref use --contains for. A
--no-contains option for "describe" wouldn't make any sense, other
than being exactly equivalent to not supplying --contains at all,
which would be confusing at best.
Add a --without option to "tag" as an alias for --no-contains, for
consistency with --with and --contains. The --with option is
undocumented, and possibly the only user of it is
Junio (<xmqqefy71iej.fsf@gitster.mtv.corp.google.com>). But it's
trivial to support, so let's do that.
The additions to the the test suite are inverse copies of the
corresponding --contains tests. With this change --no-contains for
tag, branch & for-each-ref is just as well tested as the existing
--contains option.
In addition to those tests, add a test for "tag" which asserts that
--no-contains won't find tree/blob tags, which is slightly
unintuitive, but consistent with how --contains works & is documented.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2017-03-24 18:40:57 +00:00
|
|
|
--no-contains [<commit>]::
|
|
|
|
Only list tags which don't contain the specified commit (HEAD if
|
|
|
|
not specified). Implies `--list`.
|
|
|
|
|
2017-03-21 12:58:47 +00:00
|
|
|
--merged [<commit>]::
|
2017-03-21 12:58:48 +00:00
|
|
|
Only list tags whose commits are reachable from the specified
|
2017-03-21 12:58:49 +00:00
|
|
|
commit (`HEAD` if not specified), incompatible with `--no-merged`.
|
2017-03-21 12:58:47 +00:00
|
|
|
|
|
|
|
--no-merged [<commit>]::
|
2017-03-21 12:58:48 +00:00
|
|
|
Only list tags whose commits are not reachable from the specified
|
2017-03-21 12:58:49 +00:00
|
|
|
commit (`HEAD` if not specified), incompatible with `--merged`.
|
2017-03-21 12:58:46 +00:00
|
|
|
|
2012-02-08 23:03:43 +00:00
|
|
|
--points-at <object>::
|
2017-03-24 18:40:56 +00:00
|
|
|
Only list tags of the given object (HEAD if not
|
|
|
|
specified). Implies `--list`.
|
2012-02-08 23:03:43 +00:00
|
|
|
|
2005-12-08 23:28:05 +00:00
|
|
|
-m <msg>::
|
2011-08-28 14:54:29 +00:00
|
|
|
--message=<msg>::
|
2007-11-23 07:16:51 +00:00
|
|
|
Use the given tag message (instead of prompting).
|
2008-12-27 19:49:03 +00:00
|
|
|
If multiple `-m` options are given, their values are
|
2007-11-23 07:16:51 +00:00
|
|
|
concatenated as separate paragraphs.
|
2015-09-19 07:47:48 +00:00
|
|
|
Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
|
2008-03-24 19:43:08 +00:00
|
|
|
is given.
|
2005-12-08 23:28:05 +00:00
|
|
|
|
2006-12-21 14:13:02 +00:00
|
|
|
-F <file>::
|
2011-08-28 14:54:29 +00:00
|
|
|
--file=<file>::
|
2006-12-21 14:13:02 +00:00
|
|
|
Take the tag message from the given file. Use '-' to
|
|
|
|
read the message from the standard input.
|
2015-09-19 07:47:48 +00:00
|
|
|
Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
|
2008-03-24 19:43:08 +00:00
|
|
|
is given.
|
2005-05-10 21:32:30 +00:00
|
|
|
|
2011-12-07 03:01:45 +00:00
|
|
|
--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.
|
|
|
|
|
2015-07-21 21:04:55 +00:00
|
|
|
--create-reflog::
|
2017-01-27 10:09:47 +00:00
|
|
|
Create a reflog for the tag. To globally enable reflogs for tags, see
|
|
|
|
`core.logAllRefUpdates` in linkgit:git-config[1].
|
2017-02-01 22:07:27 +00:00
|
|
|
The negated form `--no-create-reflog` only overrides an earlier
|
|
|
|
`--create-reflog`, but currently does not negate the setting of
|
|
|
|
`core.logallrefupdates`.
|
2015-07-21 21:04:55 +00:00
|
|
|
|
2009-08-22 00:45:18 +00:00
|
|
|
<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.
|
|
|
|
|
2013-04-03 14:27:14 +00:00
|
|
|
<commit>::
|
|
|
|
<object>::
|
|
|
|
The object that the new tag will refer to, usually a commit.
|
|
|
|
Defaults to HEAD.
|
|
|
|
|
2015-09-11 15:06:46 +00:00
|
|
|
<format>::
|
2017-08-18 14:51:22 +00:00
|
|
|
A string that interpolates `%(fieldname)` from a tag ref being shown
|
|
|
|
and the object it points at. The format is the same as
|
2015-09-11 15:06:46 +00:00
|
|
|
that of linkgit:git-for-each-ref[1]. When unspecified,
|
tag: do not show ambiguous tag names as "tags/foo"
Since b7cc53e9 (tag.c: use 'ref-filter' APIs, 2015-07-11),
git-tag has started showing tags with ambiguous names (i.e.,
when both "heads/foo" and "tags/foo" exists) as "tags/foo"
instead of just "foo". This is both:
- pointless; the output of "git tag" includes only
refs/tags, so we know that "foo" means the one in
"refs/tags".
and
- ambiguous; in the original output, we know that the line
"foo" means that "refs/tags/foo" exists. In the new
output, it is unclear whether we mean "refs/tags/foo" or
"refs/tags/tags/foo".
The reason this happens is that commit b7cc53e9 switched
git-tag to use ref-filter's "%(refname:short)" output
formatting, which was adapted from for-each-ref. This more
general code does not know that we care only about tags, and
uses shorten_unambiguous_ref to get the short-name. We need
to tell it that we care only about "refs/tags/", and it
should shorten with respect to that value.
In theory, the ref-filter code could figure this out by us
passing FILTER_REFS_TAGS. But there are two complications
there:
1. The handling of refname:short is deep in formatting
code that does not even have our ref_filter struct, let
alone the arguments to the filter_ref struct.
2. In git v2.7.0, we expose the formatting language to the
user. If we follow this path, it will mean that
"%(refname:short)" behaves differently for "tag" versus
"for-each-ref" (including "for-each-ref refs/tags/"),
which can lead to confusion.
Instead, let's add a new modifier to the formatting
language, "strip", to remove a specific set of prefix
components. This fixes "git tag", and lets users invoke the
same behavior from their own custom formats (for "tag" or
"for-each-ref") while leaving ":short" with its same
consistent meaning in all places.
We introduce a test in t7004 for "git tag", which fails
without this patch. We also add a similar test in t3203 for
"git branch", which does not actually fail. But since it is
likely that "branch" will eventually use the same formatting
code, the test helps defend against future regressions.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2016-01-26 03:00:05 +00:00
|
|
|
defaults to `%(refname:strip=2)`.
|
2013-04-03 14:27:14 +00:00
|
|
|
|
2007-01-26 14:13:46 +00:00
|
|
|
CONFIGURATION
|
|
|
|
-------------
|
2010-01-09 23:33:00 +00:00
|
|
|
By default, 'git tag' in sign-with-default mode (-s) will use your
|
2015-05-13 05:06:21 +00:00
|
|
|
committer identity (of the form `Your Name <your@email.address>`) to
|
2007-01-26 14:13:46 +00:00
|
|
|
find a key. If you want to use a different default key, you can specify
|
|
|
|
it in the repository configuration as follows:
|
|
|
|
|
2007-05-01 07:24:59 +00:00
|
|
|
-------------------------------------
|
2007-01-26 14:13:46 +00:00
|
|
|
[user]
|
2015-09-19 07:47:48 +00:00
|
|
|
signingKey = <gpg-keyid>
|
2007-05-01 07:24:59 +00:00
|
|
|
-------------------------------------
|
2007-01-26 14:13:46 +00:00
|
|
|
|
2017-08-02 19:40:53 +00:00
|
|
|
`pager.tag` is only respected when listing tags, i.e., when `-l` is
|
2017-08-02 19:40:54 +00:00
|
|
|
used or implied. The default is to use a pager.
|
2017-08-02 19:40:53 +00:00
|
|
|
See linkgit:git-config[1].
|
2007-02-12 06:29:12 +00:00
|
|
|
|
|
|
|
DISCUSSION
|
|
|
|
----------
|
|
|
|
|
|
|
|
On Re-tagging
|
|
|
|
~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
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
|
|
|
|
replace the old one. And you're done.
|
|
|
|
|
|
|
|
But if you have pushed things out (or others could just read
|
|
|
|
your repository directly), then others will have already seen
|
|
|
|
the old tag. In that case you can do one of two things:
|
|
|
|
|
|
|
|
. The sane thing.
|
|
|
|
Just admit you screwed up, and use a different name. Others have
|
|
|
|
already seen one tag-name, and if you keep the same name, you
|
|
|
|
may be in the situation that two people both have "version X",
|
|
|
|
but they actually have 'different' "X"'s. So just call it "X.1"
|
|
|
|
and be done with it.
|
|
|
|
|
|
|
|
. The insane thing.
|
|
|
|
You really want to call the new version "X" too, 'even though'
|
2010-01-09 23:33:00 +00:00
|
|
|
others have already seen the old one. So just use 'git tag -f'
|
2007-02-12 06:29:12 +00:00
|
|
|
again, as if you hadn't already published the old one.
|
|
|
|
|
2007-10-09 21:00:03 +00:00
|
|
|
However, Git does *not* (and it should not) change tags behind
|
2008-06-30 22:17:07 +00:00
|
|
|
users back. So if somebody already got the old tag, doing a
|
2010-01-09 23:33:00 +00:00
|
|
|
'git pull' on your tree shouldn't just make them overwrite the old
|
2007-02-12 06:29:12 +00:00
|
|
|
one.
|
|
|
|
|
|
|
|
If somebody got a release tag from you, you cannot just change
|
|
|
|
the tag for them by updating your own one. This is a big
|
|
|
|
security issue, in that people MUST be able to trust their
|
|
|
|
tag-names. If you really want to do the insane thing, you need
|
|
|
|
to just fess up to it, and tell people that you messed up. You
|
|
|
|
can do that by making a very public announcement saying:
|
|
|
|
|
|
|
|
------------
|
|
|
|
Ok, I messed up, and I pushed out an earlier version tagged as X. I
|
|
|
|
then fixed something, and retagged the *fixed* tree as X again.
|
|
|
|
|
|
|
|
If you got the wrong tag, and want the new one, please delete
|
|
|
|
the old one and fetch the new one by doing:
|
|
|
|
|
|
|
|
git tag -d X
|
|
|
|
git fetch origin tag X
|
|
|
|
|
|
|
|
to get my updated tag.
|
|
|
|
|
|
|
|
You can test which tag you have by doing
|
|
|
|
|
|
|
|
git rev-parse X
|
|
|
|
|
|
|
|
which should return 0123456789abcdef.. if you have the new version.
|
|
|
|
|
2011-03-28 15:11:49 +00:00
|
|
|
Sorry for the inconvenience.
|
2007-02-12 06:29:12 +00:00
|
|
|
------------
|
|
|
|
|
|
|
|
Does this seem a bit complicated? It *should* be. There is no
|
2011-03-28 15:11:49 +00:00
|
|
|
way that it would be correct to just "fix" it automatically.
|
|
|
|
People need to know that their tags might have been changed.
|
2007-02-12 06:29:12 +00:00
|
|
|
|
|
|
|
|
|
|
|
On Automatic following
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
If you are following somebody else's tree, you are most likely
|
2016-10-20 13:21:44 +00:00
|
|
|
using remote-tracking branches (eg. `refs/remotes/origin/master`).
|
|
|
|
You usually want the tags from the other end.
|
2007-02-12 06:29:12 +00:00
|
|
|
|
|
|
|
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
|
|
|
|
get tags from there. This happens more often for people near
|
|
|
|
the toplevel but not limited to them. Mere mortals when pulling
|
|
|
|
from each other do not necessarily want to automatically get
|
|
|
|
private anchor point tags from the other person.
|
|
|
|
|
2011-03-28 15:11:49 +00:00
|
|
|
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'
|
|
|
|
command line:
|
2007-02-12 06:29:12 +00:00
|
|
|
|
|
|
|
------------
|
|
|
|
Linus, please pull from
|
|
|
|
|
|
|
|
git://git..../proj.git master
|
|
|
|
|
|
|
|
to get the following updates...
|
|
|
|
------------
|
|
|
|
|
|
|
|
becomes:
|
|
|
|
|
|
|
|
------------
|
|
|
|
$ git pull git://git..../proj.git master
|
|
|
|
------------
|
|
|
|
|
2011-03-28 15:11:49 +00:00
|
|
|
In such a case, you do not want to automatically follow the other
|
|
|
|
person's tags.
|
2007-02-12 06:29:12 +00:00
|
|
|
|
2013-01-21 19:17:53 +00:00
|
|
|
One important aspect of Git is its distributed nature, which
|
2011-03-28 15:11:49 +00:00
|
|
|
largely means there is no inherent "upstream" or
|
2007-02-12 06:29:12 +00:00
|
|
|
"downstream" in the system. On the face of it, the above
|
|
|
|
example might seem to indicate that the tag namespace is owned
|
2011-03-28 15:11:49 +00:00
|
|
|
by the upper echelon of people and that tags only flow downwards, but
|
2007-02-12 06:29:12 +00:00
|
|
|
that is not the case. It only shows that the usage pattern
|
|
|
|
determines who are interested in whose tags.
|
|
|
|
|
|
|
|
A one-shot pull is a sign that a commit history is now crossing
|
|
|
|
the boundary between one circle of people (e.g. "people who are
|
2008-12-27 19:49:03 +00:00
|
|
|
primarily interested in the networking part of the kernel") who may
|
2007-02-12 06:29:12 +00:00
|
|
|
have their own set of tags (e.g. "this is the third release
|
|
|
|
candidate from the networking group to be proposed for general
|
|
|
|
consumption with 2.6.21 release") to another circle of people
|
|
|
|
(e.g. "people who integrate various subsystem improvements").
|
|
|
|
The latter are usually not interested in the detailed tags used
|
|
|
|
internally in the former group (that is what "internal" means).
|
|
|
|
That is why it is desirable not to follow tags automatically in
|
|
|
|
this case.
|
|
|
|
|
|
|
|
It may well be that among networking people, they may want to
|
|
|
|
exchange the tags internal to their group, but in that workflow
|
2011-03-28 15:11:49 +00:00
|
|
|
they are most likely tracking each other's progress by
|
2010-11-02 15:31:23 +00:00
|
|
|
having remote-tracking branches. Again, the heuristic to automatically
|
2007-02-12 06:29:12 +00:00
|
|
|
follow such tags is a good thing.
|
|
|
|
|
|
|
|
|
2007-10-15 17:51:30 +00:00
|
|
|
On Backdating Tags
|
|
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
If you have imported some changes from another VCS and would like
|
|
|
|
to add tags for major releases of your work, it is useful to be able
|
2011-03-28 15:11:49 +00:00
|
|
|
to specify the date to embed inside of the tag object; such data in
|
2007-10-15 17:51:30 +00:00
|
|
|
the tag object affects, for example, the ordering of tags in the
|
|
|
|
gitweb interface.
|
|
|
|
|
|
|
|
To set the date used in future tag objects, set the environment
|
2011-03-28 15:11:49 +00:00
|
|
|
variable GIT_COMMITTER_DATE (see the later discussion of possible
|
|
|
|
values; the most common form is "YYYY-MM-DD HH:MM").
|
2007-10-15 17:51:30 +00:00
|
|
|
|
2011-03-28 15:11:49 +00:00
|
|
|
For example:
|
2007-10-15 17:51:30 +00:00
|
|
|
|
|
|
|
------------
|
2008-04-11 20:52:07 +00:00
|
|
|
$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
|
2007-10-15 17:51:30 +00:00
|
|
|
------------
|
|
|
|
|
2011-03-28 15:11:49 +00:00
|
|
|
include::date-formats.txt[]
|
2007-10-15 17:51:30 +00:00
|
|
|
|
2009-08-22 00:45:18 +00:00
|
|
|
SEE ALSO
|
|
|
|
--------
|
|
|
|
linkgit:git-check-ref-format[1].
|
2014-07-16 21:48:02 +00:00
|
|
|
linkgit:git-config[1].
|
2009-08-22 00:45:18 +00:00
|
|
|
|
2005-05-10 21:32:30 +00:00
|
|
|
GIT
|
|
|
|
---
|
2008-06-06 07:07:32 +00:00
|
|
|
Part of the linkgit:git[1] suite
|