1 <?xml version=
"1.0" encoding=
"UTF-8"?>
2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.1//EN"
3 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
4 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en">
6 <meta http-equiv=
"Content-Type" content=
"application/xhtml+xml; charset=UTF-8" />
7 <meta name=
"generator" content=
"AsciiDoc 10.2.0" />
8 <title>git-tag(
1)
</title>
9 <style type=
"text/css">
10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
14 font-family: Georgia,serif;
18 h1, h2, h3, h4, h5, h6,
19 div.title, caption.title,
20 thead, p.table.header,
22 #author, #revnumber, #revdate, #revremark,
24 font-family: Arial,Helvetica,sans-serif;
28 margin:
1em
5%
1em
5%;
33 text-decoration: underline;
49 h1, h2, h3, h4, h5, h6 {
57 border-bottom:
2px solid silver;
77 border:
1px solid silver;
88 ul
> li { color: #aaa; }
89 ul
> li
> * { color: black; }
91 .monospaced, code, pre {
92 font-family:
"Courier New", Courier, monospace;
99 white-space: pre-wrap;
109 #revnumber, #revdate, #revremark {
114 border-top:
2px solid silver;
120 padding-bottom:
0.5em;
124 padding-bottom:
0.5em;
129 margin-bottom:
1.5em;
131 div.imageblock, div.exampleblock, div.verseblock,
132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
133 div.admonitionblock {
135 margin-bottom:
1.5em;
137 div.admonitionblock {
139 margin-bottom:
2.0em;
144 div.content { /* Block element content. */
148 /* Block element titles. */
149 div.title, caption.title {
154 margin-bottom:
0.5em;
160 td div.title:first-child {
163 div.content div.title:first-child {
166 div.content + div.title {
170 div.sidebarblock
> div.content {
172 border:
1px solid #dddddd;
173 border-left:
4px solid #f0f0f0;
177 div.listingblock
> div.content {
178 border:
1px solid #dddddd;
179 border-left:
5px solid #f0f0f0;
184 div.quoteblock, div.verseblock {
188 border-left:
5px solid #f0f0f0;
192 div.quoteblock
> div.attribution {
197 div.verseblock
> pre.content {
198 font-family: inherit;
201 div.verseblock
> div.attribution {
205 /* DEPRECATED: Pre version
8.2.7 verse style literal block. */
206 div.verseblock + div.attribution {
210 div.admonitionblock .icon {
214 text-decoration: underline;
216 padding-right:
0.5em;
218 div.admonitionblock td.content {
220 border-left:
3px solid #dddddd;
223 div.exampleblock
> div.content {
224 border-left:
3px solid #dddddd;
228 div.imageblock div.content { padding-left:
0; }
229 span.image img { border-style: none; vertical-align: text-bottom; }
230 a.image:visited { color: white; }
234 margin-bottom:
0.8em;
247 list-style-position: outside;
250 list-style-type: decimal;
253 list-style-type: lower-alpha;
256 list-style-type: upper-alpha;
259 list-style-type: lower-roman;
262 list-style-type: upper-roman;
265 div.compact ul, div.compact ol,
266 div.compact p, div.compact p,
267 div.compact div, div.compact div {
269 margin-bottom:
0.1em;
281 margin-bottom:
0.8em;
284 padding-bottom:
15px;
286 dt.hdlist1.strong, td.hdlist1.strong {
292 padding-right:
0.8em;
298 div.hdlist.compact tr {
307 .footnote, .footnoteref {
311 span.footnote, span.footnoteref {
312 vertical-align: super;
316 margin:
20px
0 20px
0;
320 #footnotes div.footnote {
326 border-top:
1px solid silver;
335 padding-right:
0.5em;
336 padding-bottom:
0.3em;
344 #footer-badges { display: none; }
348 margin-bottom:
2.5em;
356 margin-bottom:
0.1em;
359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
376 span.aqua { color: aqua; }
377 span.black { color: black; }
378 span.blue { color: blue; }
379 span.fuchsia { color: fuchsia; }
380 span.gray { color: gray; }
381 span.green { color: green; }
382 span.lime { color: lime; }
383 span.maroon { color: maroon; }
384 span.navy { color: navy; }
385 span.olive { color: olive; }
386 span.purple { color: purple; }
387 span.red { color: red; }
388 span.silver { color: silver; }
389 span.teal { color: teal; }
390 span.white { color: white; }
391 span.yellow { color: yellow; }
393 span.aqua-background { background: aqua; }
394 span.black-background { background: black; }
395 span.blue-background { background: blue; }
396 span.fuchsia-background { background: fuchsia; }
397 span.gray-background { background: gray; }
398 span.green-background { background: green; }
399 span.lime-background { background: lime; }
400 span.maroon-background { background: maroon; }
401 span.navy-background { background: navy; }
402 span.olive-background { background: olive; }
403 span.purple-background { background: purple; }
404 span.red-background { background: red; }
405 span.silver-background { background: silver; }
406 span.teal-background { background: teal; }
407 span.white-background { background: white; }
408 span.yellow-background { background: yellow; }
410 span.big { font-size:
2em; }
411 span.small { font-size:
0.6em; }
413 span.underline { text-decoration: underline; }
414 span.overline { text-decoration: overline; }
415 span.line-through { text-decoration: line-through; }
417 div.unbreakable { page-break-inside: avoid; }
427 margin-bottom:
1.5em;
429 div.tableblock
> table {
430 border:
3px solid #
527bbd;
432 thead, p.table.header {
439 /* Because the table frame attribute is overridden by CSS in most browsers. */
440 div.tableblock
> table[
frame=
"void"] {
443 div.tableblock
> table[
frame=
"hsides"] {
444 border-left-style: none;
445 border-right-style: none;
447 div.tableblock
> table[
frame=
"vsides"] {
448 border-top-style: none;
449 border-bottom-style: none;
460 margin-bottom:
1.5em;
462 thead, p.tableblock.header {
473 border-color: #
527bbd;
474 border-collapse: collapse;
476 th.tableblock, td.tableblock {
480 border-color: #
527bbd;
483 table.tableblock.frame-topbot {
484 border-left-style: hidden;
485 border-right-style: hidden;
487 table.tableblock.frame-sides {
488 border-top-style: hidden;
489 border-bottom-style: hidden;
491 table.tableblock.frame-none {
492 border-style: hidden;
495 th.tableblock.halign-left, td.tableblock.halign-left {
498 th.tableblock.halign-center, td.tableblock.halign-center {
501 th.tableblock.halign-right, td.tableblock.halign-right {
505 th.tableblock.valign-top, td.tableblock.valign-top {
508 th.tableblock.valign-middle, td.tableblock.valign-middle {
509 vertical-align: middle;
511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
512 vertical-align: bottom;
523 padding-bottom:
0.5em;
524 border-top:
2px solid silver;
525 border-bottom:
2px solid silver;
530 body.manpage div.sectionbody {
535 body.manpage div#toc { display: none; }
540 <script type=
"text/javascript">
542 var asciidoc = { // Namespace.
544 /////////////////////////////////////////////////////////////////////
545 // Table Of Contents generator
546 /////////////////////////////////////////////////////////////////////
548 /* Author: Mihai Bazon, September
2002
549 * http://students.infoiasi.ro/~mishoo
551 * Table Of Content generator
554 * Feel free to use this script under the terms of the GNU General Public
555 * License, as long as you do not remove or alter this notice.
558 /* modified by Troy D. Hanson, September
2006. License: GPL */
559 /* modified by Stuart Rackham,
2006,
2009. License: GPL */
562 toc: function (toclevels) {
564 function getText(el) {
566 for (var i = el.firstChild; i != null; i = i.nextSibling) {
567 if (i.nodeType ==
3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
569 else if (i.firstChild != null)
575 function TocEntry(el, text, toclevel) {
578 this.toclevel = toclevel;
581 function tocEntries(el, toclevels) {
582 var result = new Array;
583 var re = new RegExp('[hH]([
1-'+(toclevels+
1)+'])');
584 // Function that scans the DOM tree for header elements (the DOM2
585 // nodeIterator API would be a better technique but not supported by all
587 var iterate = function (el) {
588 for (var i = el.firstChild; i != null; i = i.nextSibling) {
589 if (i.nodeType ==
1 /* Node.ELEMENT_NODE */) {
590 var mo = re.exec(i.tagName);
591 if (mo && (i.getAttribute(
"class") || i.getAttribute(
"className")) !=
"float") {
592 result[result.length] = new TocEntry(i, getText(i), mo[
1]-
1);
602 var toc = document.getElementById(
"toc");
607 // Delete existing TOC entries in case we're reloading the TOC.
608 var tocEntriesToRemove = [];
610 for (i =
0; i < toc.childNodes.length; i++) {
611 var entry = toc.childNodes[i];
612 if (entry.nodeName.toLowerCase() == 'div'
613 && entry.getAttribute(
"class")
614 && entry.getAttribute(
"class").match(/^toclevel/))
615 tocEntriesToRemove.push(entry);
617 for (i =
0; i < tocEntriesToRemove.length; i++) {
618 toc.removeChild(tocEntriesToRemove[i]);
621 // Rebuild TOC entries.
622 var entries = tocEntries(document.getElementById(
"content"), toclevels);
623 for (var i =
0; i < entries.length; ++i) {
624 var entry = entries[i];
625 if (entry.element.id ==
"")
626 entry.element.id =
"_toc_" + i;
627 var a = document.createElement(
"a");
628 a.href =
"#" + entry.element.id;
629 a.appendChild(document.createTextNode(entry.text));
630 var div = document.createElement(
"div");
632 div.className =
"toclevel" + entry.toclevel;
633 toc.appendChild(div);
635 if (entries.length ==
0)
636 toc.parentNode.removeChild(toc);
640 /////////////////////////////////////////////////////////////////////
641 // Footnotes generator
642 /////////////////////////////////////////////////////////////////////
644 /* Based on footnote generation code from:
645 * http://www.brandspankingnew.net/archive/
2005/
07/format_footnote.html
648 footnotes: function () {
649 // Delete existing footnote entries in case we're reloading the footnodes.
651 var noteholder = document.getElementById(
"footnotes");
655 var entriesToRemove = [];
656 for (i =
0; i < noteholder.childNodes.length; i++) {
657 var entry = noteholder.childNodes[i];
658 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute(
"class") ==
"footnote")
659 entriesToRemove.push(entry);
661 for (i =
0; i < entriesToRemove.length; i++) {
662 noteholder.removeChild(entriesToRemove[i]);
665 // Rebuild footnote entries.
666 var cont = document.getElementById(
"content");
667 var spans = cont.getElementsByTagName(
"span");
670 for (i=
0; i
<spans.length; i++) {
671 if (spans[i].className ==
"footnote") {
673 var note = spans[i].getAttribute(
"data-note");
675 // Use [\s\S] in place of . so multi-line matches work.
676 // Because JavaScript has no s (dotall) regex flag.
677 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[
1];
679 "[<a id='_footnoteref_" + n +
"' href='#_footnote_" + n +
680 "' title='View footnote' class='footnote'>" + n +
"</a>]";
681 spans[i].setAttribute(
"data-note", note);
683 noteholder.innerHTML +=
684 "<div class='footnote' id='_footnote_" + n +
"'>" +
685 "<a href='#_footnoteref_" + n +
"' title='Return to text'>" +
686 n +
"</a>. " + note +
"</div>";
687 var id =spans[i].getAttribute(
"id");
688 if (id != null) refs[
"#"+id] = n;
692 noteholder.parentNode.removeChild(noteholder);
694 // Process footnoterefs.
695 for (i=
0; i
<spans.length; i++) {
696 if (spans[i].className ==
"footnoteref") {
697 var href = spans[i].getElementsByTagName(
"a")[
0].getAttribute(
"href");
698 href = href.match(/#.*/)[
0]; // Because IE return full URL.
701 "[<a href='#_footnote_" + n +
702 "' title='View footnote' class='footnote'>" + n +
"</a>]";
708 install: function(toclevels) {
711 function reinstall() {
712 asciidoc.footnotes();
714 asciidoc.toc(toclevels);
718 function reinstallAndRemoveTimer() {
719 clearInterval(timerId);
723 timerId = setInterval(reinstall,
500);
724 if (document.addEventListener)
725 document.addEventListener(
"DOMContentLoaded", reinstallAndRemoveTimer, false);
727 window.onload = reinstallAndRemoveTimer;
735 <body class=
"manpage">
738 git-tag(
1) Manual Page
741 <div class=
"sectionbody">
743 Create, list, delete or verify a tag object signed with GPG
749 <h2 id=
"_synopsis">SYNOPSIS
</h2>
750 <div class=
"sectionbody">
751 <div class=
"verseblock">
752 <pre class=
"content"><em>git tag
</em> [-a | -s | -u
<key-id
>] [-f] [-m
<msg
> | -F
<file
>] [-e]
753 [(--trailer
<token
>[(=|:)
<value
>])
…]
754 <tagname
> [
<commit
> |
<object
>]
755 <em>git tag
</em> -d
<tagname
>…
756 <em>git tag
</em> [-n[
<num
>]] -l [--contains
<commit
>] [--no-contains
<commit
>]
757 [--points-at
<object
>] [--column[=
<options
>] | --no-column]
758 [--create-reflog] [--sort=
<key
>] [--format=
<format
>]
759 [--merged
<commit
>] [--no-merged
<commit
>] [
<pattern
>…]
760 <em>git tag
</em> -v [--format=
<format
>]
<tagname
>…</pre>
761 <div class=
"attribution">
766 <h2 id=
"_description">DESCRIPTION
</h2>
767 <div class=
"sectionbody">
768 <div class=
"paragraph"><p>Add a tag reference in
<code>refs/tags/
</code>, unless
<code>-d/-l/-v
</code> is given
769 to delete, list or verify tags.
</p></div>
770 <div class=
"paragraph"><p>Unless
<code>-f
</code> is given, the named tag must not yet exist.
</p></div>
771 <div class=
"paragraph"><p>If one of
<code>-a
</code>,
<code>-s
</code>, or
<code>-u
<key-id
></code> is passed, the command
772 creates a
<em>tag
</em> object, and requires a tag message. Unless
773 <code>-m
<msg
></code> or
<code>-F
<file
></code> is given, an editor is started for the user to type
774 in the tag message.
</p></div>
775 <div class=
"paragraph"><p>If
<code>-m
<msg
></code> or
<code>-F
<file
></code> or
<code>--trailer
<token
>[=
<value
>]
</code> is given
776 and
<code>-a
</code>,
<code>-s
</code>, and
<code>-u
<key-id
></code> are absent,
<code>-a
</code> is implied.
</p></div>
777 <div class=
"paragraph"><p>Otherwise, a tag reference that points directly at the given object
778 (i.e., a lightweight tag) is created.
</p></div>
779 <div class=
"paragraph"><p>A GnuPG signed tag object will be created when
<code>-s
</code> or
<code>-u
780 <key-id
></code> is used. When
<code>-u
<key-id
></code> is not used, the
781 committer identity for the current user is used to find the
782 GnuPG key for signing. The configuration variable
<code>gpg.program
</code>
783 is used to specify custom GnuPG binary.
</p></div>
784 <div class=
"paragraph"><p>Tag objects (created with
<code>-a
</code>,
<code>-s
</code>, or
<code>-u
</code>) are called
"annotated"
785 tags; they contain a creation date, the tagger name and e-mail, a
786 tagging message, and an optional GnuPG signature. Whereas a
787 "lightweight" tag is simply a name for an object (usually a commit
789 <div class=
"paragraph"><p>Annotated tags are meant for release while lightweight tags are meant
790 for private or temporary object labels. For this reason, some git
791 commands for naming objects (like
<code>git describe
</code>) will ignore
792 lightweight tags by default.
</p></div>
796 <h2 id=
"_options">OPTIONS
</h2>
797 <div class=
"sectionbody">
798 <div class=
"dlist"><dl>
807 Make an unsigned, annotated tag object
818 Make a GPG-signed tag, using the default e-mail address
’s key.
819 The default behavior of tag GPG-signing is controlled by
<code>tag.gpgSign
</code>
820 configuration variable if it exists, or disabled otherwise.
821 See
<a href=
"git-config.html">git-config(
1)
</a>.
829 Override
<code>tag.gpgSign
</code> configuration variable that is
830 set to force each and every tag to be signed.
837 --local-user=
<key-id
>
841 Make a GPG-signed tag, using the given key.
852 Replace an existing tag with the given name (instead of failing)
863 Delete existing tags with the given names.
874 Verify the GPG signature of the given tag names.
882 <num
> specifies how many lines from the annotation, if any,
883 are printed when using -l. Implies
<code>--list
</code>.
885 <div class=
"paragraph"><p>The default is not to print any annotation lines.
886 If no number is given to
<code>-n
</code>, only the first line is printed.
887 If the tag is not annotated, the commit message is displayed instead.
</p></div>
897 List tags. With optional
<code><pattern
>...
</code>, e.g.
<code>git tag --list
898 'v-*'
</code>, list only the tags that match the pattern(s).
900 <div class=
"paragraph"><p>Running
"git tag" without arguments also lists all tags. The pattern
901 is a shell wildcard (i.e., matched using fnmatch(
3)). Multiple
902 patterns may be given; if any of them matches, the tag is shown.
</p></div>
903 <div class=
"paragraph"><p>This option is implicitly supplied if any other list-like option such
904 as
<code>--contains
</code> is provided. See the documentation for each of those
905 options for details.
</p></div>
912 Sort based on the key given. Prefix
<code>-
</code> to sort in
913 descending order of the value. You may use the --sort=
<key
> option
914 multiple times, in which case the last key becomes the primary
915 key. Also supports
"version:refname" or
"v:refname" (tag
916 names are treated as versions). The
"version:refname" sort
917 order can also be affected by the
"versionsort.suffix"
918 configuration variable.
919 The keys supported are the same as those in
<code>git for-each-ref
</code>.
920 Sort order defaults to the value configured for the
<code>tag.sort
</code>
921 variable if it exists, or lexicographic order otherwise. See
922 <a href=
"git-config.html">git-config(
1)
</a>.
926 --color[=
<when
>]
930 Respect any colors specified in the
<code>--format
</code> option. The
931 <code><when
></code> field must be one of
<code>always
</code>,
<code>never
</code>, or
<code>auto
</code> (if
932 <code><when
></code> is absent, behave as if
<code>always
</code> was given).
943 Sorting and filtering tags are case insensitive.
951 Do not print a newline after formatted refs where the format expands
956 --column[=
<options
>]
963 Display tag listing in columns. See configuration variable
964 <code>column.tag
</code> for option syntax.
<code>--column
</code> and
<code>--no-column
</code>
965 without options are equivalent to
<em>always
</em> and
<em>never
</em> respectively.
967 <div class=
"paragraph"><p>This option is only applicable when listing tags without annotation lines.
</p></div>
970 --contains [
<commit
>]
974 Only list tags which contain the specified commit (HEAD if not
975 specified). Implies
<code>--list
</code>.
979 --no-contains [
<commit
>]
983 Only list tags which don
’t contain the specified commit (HEAD if
984 not specified). Implies
<code>--list
</code>.
988 --merged [
<commit
>]
992 Only list tags whose commits are reachable from the specified
993 commit (
<code>HEAD
</code> if not specified).
997 --no-merged [
<commit
>]
1001 Only list tags whose commits are not reachable from the specified
1002 commit (
<code>HEAD
</code> if not specified).
1005 <dt class=
"hdlist1">
1006 --points-at
<object
>
1010 Only list tags of the given object (HEAD if not
1011 specified). Implies
<code>--list
</code>.
1014 <dt class=
"hdlist1">
1017 <dt class=
"hdlist1">
1018 --message=
<msg
>
1022 Use the given tag message (instead of prompting).
1023 If multiple
<code>-m
</code> options are given, their values are
1024 concatenated as separate paragraphs.
1025 Implies
<code>-a
</code> if none of
<code>-a
</code>,
<code>-s
</code>, or
<code>-u
<key-id
></code>
1029 <dt class=
"hdlist1">
1032 <dt class=
"hdlist1">
1037 Take the tag message from the given file. Use
<em>-
</em> to
1038 read the message from the standard input.
1039 Implies
<code>-a
</code> if none of
<code>-a
</code>,
<code>-s
</code>, or
<code>-u
<key-id
></code>
1043 <dt class=
"hdlist1">
1044 --trailer
<token
>[(=|:)
<value
>]
1048 Specify a (
<token
>,
<value
>) pair that should be applied as a
1049 trailer. (e.g.
<code>git tag --trailer
"Custom-Key: value"</code>
1050 will add a
"Custom-Key" trailer to the tag message.)
1051 The
<code>trailer.*
</code> configuration variables
1052 (
<a href=
"git-interpret-trailers.html">git-interpret-trailers(
1)
</a>) can be used to define if
1053 a duplicated trailer is omitted, where in the run of trailers
1054 each trailer would appear, and other details.
1055 The trailers can be extracted in
<code>git tag --list
</code>, using
1056 <code>--format=
"%(trailers)"</code> placeholder.
1059 <dt class=
"hdlist1">
1062 <dt class=
"hdlist1">
1067 The message taken from file with
<code>-F
</code> and command line with
1068 <code>-m
</code> are usually used as the tag message unmodified.
1069 This option lets you further edit the message taken from these sources.
1072 <dt class=
"hdlist1">
1073 --cleanup=
<mode
>
1077 This option sets how the tag message is cleaned up.
1078 The
<em><mode
></em> can be one of
<em>verbatim
</em>,
<em>whitespace
</em> and
<em>strip
</em>. The
1079 <em>strip
</em> mode is default. The
<em>verbatim
</em> mode does not change message at
1080 all,
<em>whitespace
</em> removes just leading/trailing whitespace lines and
1081 <em>strip
</em> removes both whitespace and commentary.
1084 <dt class=
"hdlist1">
1089 Create a reflog for the tag. To globally enable reflogs for tags, see
1090 <code>core.logAllRefUpdates
</code> in
<a href=
"git-config.html">git-config(
1)
</a>.
1091 The negated form
<code>--no-create-reflog
</code> only overrides an earlier
1092 <code>--create-reflog
</code>, but currently does not negate the setting of
1093 <code>core.logAllRefUpdates
</code>.
1096 <dt class=
"hdlist1">
1097 --format=
<format
>
1101 A string that interpolates
<code>%(fieldname)
</code> from a tag ref being shown
1102 and the object it points at. The format is the same as
1103 that of
<a href=
"git-for-each-ref.html">git-for-each-ref(
1)
</a>. When unspecified,
1104 defaults to
<code>%(refname:strip=
2)
</code>.
1107 <dt class=
"hdlist1">
1112 The name of the tag to create, delete, or describe.
1113 The new tag name must pass all checks defined by
1114 <a href=
"git-check-ref-format.html">git-check-ref-format(
1)
</a>. Some of these checks
1115 may restrict the characters allowed in a tag name.
1118 <dt class=
"hdlist1">
1121 <dt class=
"hdlist1">
1126 The object that the new tag will refer to, usually a commit.
1134 <h2 id=
"_configuration">CONFIGURATION
</h2>
1135 <div class=
"sectionbody">
1136 <div class=
"paragraph"><p>By default,
<em>git tag
</em> in sign-with-default mode (-s) will use your
1137 committer identity (of the form
<code>Your Name
<your@email.address
></code>) to
1138 find a key. If you want to use a different default key, you can specify
1139 it in the repository configuration as follows:
</p></div>
1140 <div class=
"listingblock">
1141 <div class=
"content">
1143 signingKey =
<gpg-key-id
></code></pre>
1145 <div class=
"paragraph"><p><code>pager.tag
</code> is only respected when listing tags, i.e., when
<code>-l
</code> is
1146 used or implied. The default is to use a pager.
1147 See
<a href=
"git-config.html">git-config(
1)
</a>.
</p></div>
1151 <h2 id=
"_discussion">DISCUSSION
</h2>
1152 <div class=
"sectionbody">
1154 <h3 id=
"_on_re_tagging">On Re-tagging
</h3>
1155 <div class=
"paragraph"><p>What should you do when you tag a wrong commit and you would
1156 want to re-tag?
</p></div>
1157 <div class=
"paragraph"><p>If you never pushed anything out, just re-tag it. Use
"-f" to
1158 replace the old one. And you
’re done.
</p></div>
1159 <div class=
"paragraph"><p>But if you have pushed things out (or others could just read
1160 your repository directly), then others will have already seen
1161 the old tag. In that case you can do one of two things:
</p></div>
1162 <div class=
"olist arabic"><ol class=
"arabic">
1166 Just admit you screwed up, and use a different name. Others have
1167 already seen one tag-name, and if you keep the same name, you
1168 may be in the situation that two people both have
"version X",
1169 but they actually have
<em>different
</em> "X"'s. So just call it
"X.1"
1170 and be done with it.
1176 You really want to call the new version
"X" too,
<em>even though
</em>
1177 others have already seen the old one. So just use
<em>git tag -f
</em>
1178 again, as if you hadn
’t already published the old one.
1182 <div class=
"paragraph"><p>However, Git does
<strong>not
</strong> (and it should not) change tags behind
1183 users back. So if somebody already got the old tag, doing a
1184 <em>git pull
</em> on your tree shouldn
’t just make them overwrite the old
1186 <div class=
"paragraph"><p>If somebody got a release tag from you, you cannot just change
1187 the tag for them by updating your own one. This is a big
1188 security issue, in that people MUST be able to trust their
1189 tag-names. If you really want to do the insane thing, you need
1190 to just fess up to it, and tell people that you messed up. You
1191 can do that by making a very public announcement saying:
</p></div>
1192 <div class=
"listingblock">
1193 <div class=
"content">
1194 <pre><code>Ok, I messed up, and I pushed out an earlier version tagged as X. I
1195 then fixed something, and retagged the *fixed* tree as X again.
1197 If you got the wrong tag, and want the new one, please delete
1198 the old one and fetch the new one by doing:
1201 git fetch origin tag X
1203 to get my updated tag.
1205 You can test which tag you have by doing
1209 which should return
0123456789abcdef.. if you have the new version.
1211 Sorry for the inconvenience.
</code></pre>
1213 <div class=
"paragraph"><p>Does this seem a bit complicated? It
<strong>should
</strong> be. There is no
1214 way that it would be correct to just
"fix" it automatically.
1215 People need to know that their tags might have been changed.
</p></div>
1218 <h3 id=
"_on_automatic_following">On Automatic following
</h3>
1219 <div class=
"paragraph"><p>If you are following somebody else
’s tree, you are most likely
1220 using remote-tracking branches (eg.
<code>refs/remotes/origin/master
</code>).
1221 You usually want the tags from the other end.
</p></div>
1222 <div class=
"paragraph"><p>On the other hand, if you are fetching because you would want a
1223 one-shot merge from somebody else, you typically do not want to
1224 get tags from there. This happens more often for people near
1225 the toplevel but not limited to them. Mere mortals when pulling
1226 from each other do not necessarily want to automatically get
1227 private anchor point tags from the other person.
</p></div>
1228 <div class=
"paragraph"><p>Often,
"please pull" messages on the mailing list just provide
1229 two pieces of information: a repo URL and a branch name; this
1230 is designed to be easily cut
&pasted at the end of a
<em>git fetch
</em>
1231 command line:
</p></div>
1232 <div class=
"listingblock">
1233 <div class=
"content">
1234 <pre><code>Linus, please pull from
1236 git://git..../proj.git master
1238 to get the following updates...
</code></pre>
1240 <div class=
"paragraph"><p>becomes:
</p></div>
1241 <div class=
"listingblock">
1242 <div class=
"content">
1243 <pre><code>$ git pull git://git..../proj.git master
</code></pre>
1245 <div class=
"paragraph"><p>In such a case, you do not want to automatically follow the other
1246 person
’s tags.
</p></div>
1247 <div class=
"paragraph"><p>One important aspect of Git is its distributed nature, which
1248 largely means there is no inherent
"upstream" or
1249 "downstream" in the system. On the face of it, the above
1250 example might seem to indicate that the tag namespace is owned
1251 by the upper echelon of people and that tags only flow downwards, but
1252 that is not the case. It only shows that the usage pattern
1253 determines who are interested in whose tags.
</p></div>
1254 <div class=
"paragraph"><p>A one-shot pull is a sign that a commit history is now crossing
1255 the boundary between one circle of people (e.g.
"people who are
1256 primarily interested in the networking part of the kernel") who may
1257 have their own set of tags (e.g.
"this is the third release
1258 candidate from the networking group to be proposed for general
1259 consumption with 2.6.21 release") to another circle of people
1260 (e.g.
"people who integrate various subsystem improvements").
1261 The latter are usually not interested in the detailed tags used
1262 internally in the former group (that is what
"internal" means).
1263 That is why it is desirable not to follow tags automatically in
1264 this case.
</p></div>
1265 <div class=
"paragraph"><p>It may well be that among networking people, they may want to
1266 exchange the tags internal to their group, but in that workflow
1267 they are most likely tracking each other
’s progress by
1268 having remote-tracking branches. Again, the heuristic to automatically
1269 follow such tags is a good thing.
</p></div>
1272 <h3 id=
"_on_backdating_tags">On Backdating Tags
</h3>
1273 <div class=
"paragraph"><p>If you have imported some changes from another VCS and would like
1274 to add tags for major releases of your work, it is useful to be able
1275 to specify the date to embed inside of the tag object; such data in
1276 the tag object affects, for example, the ordering of tags in the
1277 gitweb interface.
</p></div>
1278 <div class=
"paragraph"><p>To set the date used in future tag objects, set the environment
1279 variable GIT_COMMITTER_DATE (see the later discussion of possible
1280 values; the most common form is
"YYYY-MM-DD HH:MM").
</p></div>
1281 <div class=
"paragraph"><p>For example:
</p></div>
1282 <div class=
"listingblock">
1283 <div class=
"content">
1284 <pre><code>$
GIT_COMMITTER_DATE=
"2006-10-02 10:31" git tag -s v1.0
.1</code></pre>
1290 <h2 id=
"_date_formats">DATE FORMATS
</h2>
1291 <div class=
"sectionbody">
1292 <div class=
"paragraph"><p>The
<code>GIT_AUTHOR_DATE
</code> and
<code>GIT_COMMITTER_DATE
</code> environment variables
1293 support the following date formats:
</p></div>
1294 <div class=
"dlist"><dl>
1295 <dt class=
"hdlist1">
1300 It is
<code><unix-timestamp
> <time-zone-offset
></code>, where
1301 <code><unix-timestamp
></code> is the number of seconds since the UNIX epoch.
1302 <code><time-zone-offset
></code> is a positive or negative offset from UTC.
1303 For example CET (which is
1 hour ahead of UTC) is
<code>+
0100</code>.
1306 <dt class=
"hdlist1">
1311 The standard date format as described by RFC
2822, for example
1312 <code>Thu,
07 Apr
2005 22:
13:
13 +
0200</code>.
1315 <dt class=
"hdlist1">
1320 Time and date specified by the ISO
8601 standard, for example
1321 <code>2005-
04-
07T22:
13:
13</code>. The parser accepts a space instead of the
1322 <code>T
</code> character as well. Fractional parts of a second will be ignored,
1323 for example
<code>2005-
04-
07T22:
13:
13.019</code> will be treated as
1324 <code>2005-
04-
07T22:
13:
13</code>.
1326 <div class=
"admonitionblock">
1329 <div class=
"title">Note
</div>
1331 <td class=
"content">In addition, the date part is accepted in the following formats:
1332 <code>YYYY.MM.DD
</code>,
<code>MM/DD/YYYY
</code> and
<code>DD.MM.YYYY
</code>.
</td>
1340 <h2 id=
"_files">FILES
</h2>
1341 <div class=
"sectionbody">
1342 <div class=
"dlist"><dl>
1343 <dt class=
"hdlist1">
1344 <code>$GIT_DIR/TAG_EDITMSG
</code>
1348 This file contains the message of an in-progress annotated
1349 tag. If
<code>git tag
</code> exits due to an error before creating an
1350 annotated tag then the tag message that has been provided by the
1351 user in an editor session will be available in this file, but
1352 may be overwritten by the next invocation of
<code>git tag
</code>.
1359 <h2 id=
"_notes">NOTES
</h2>
1360 <div class=
"sectionbody">
1361 <div class=
"paragraph"><p>When combining multiple
<code>--contains
</code> and
<code>--no-contains
</code> filters, only
1362 references that contain at least one of the
<code>--contains
</code> commits and
1363 contain none of the
<code>--no-contains
</code> commits are shown.
</p></div>
1364 <div class=
"paragraph"><p>When combining multiple
<code>--merged
</code> and
<code>--no-merged
</code> filters, only
1365 references that are reachable from at least one of the
<code>--merged
</code>
1366 commits and from none of the
<code>--no-merged
</code> commits are shown.
</p></div>
1370 <h2 id=
"_see_also">SEE ALSO
</h2>
1371 <div class=
"sectionbody">
1372 <div class=
"paragraph"><p><a href=
"git-check-ref-format.html">git-check-ref-format(
1)
</a>.
1373 <a href=
"git-config.html">git-config(
1)
</a>.
</p></div>
1377 <h2 id=
"_git">GIT
</h2>
1378 <div class=
"sectionbody">
1379 <div class=
"paragraph"><p>Part of the
<a href=
"git.html">git(
1)
</a> suite
</p></div>
1383 <div id=
"footnotes"><hr /></div>
1385 <div id=
"footer-text">
1387 2024-
05-
16 11:
09:
25 PDT