git-tag.html

   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">
   5 <head>
   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 */
  11
  12 /* Default font. */
  13 body {
  14   font-family: Georgia,serif;
  15 }
  16
  17 /* Title font. */
  18 h1, h2, h3, h4, h5, h6,
  19 div.title, caption.title,
  20 thead, p.table.header,
  21 #toctitle,
  22 #author, #revnumber, #revdate, #revremark,
  23 #footer {
  24   font-family: Arial,Helvetica,sans-serif;
  25 }
  26
  27 body {
  28   margin: 1em 5% 1em 5%;
  29 }
  30
  31 a {
  32   color: blue;
  33   text-decoration: underline;
  34 }
  35 a:visited {
  36   color: fuchsia;
  37 }
  38
  39 em {
  40   font-style: italic;
  41   color: navy;
  42 }
  43
  44 strong {
  45   font-weight: bold;
  46   color: #083194;
  47 }
  48
  49 h1, h2, h3, h4, h5, h6 {
  50   color: #527bbd;
  51   margin-top: 1.2em;
  52   margin-bottom: 0.5em;
  53   line-height: 1.3;
  54 }
  55
  56 h1, h2, h3 {
  57   border-bottom: 2px solid silver;
  58 }
  59 h2 {
  60   padding-top: 0.5em;
  61 }
  62 h3 {
  63   float: left;
  64 }
  65 h3 + * {
  66   clear: left;
  67 }
  68 h5 {
  69   font-size: 1.0em;
  70 }
  71
  72 div.sectionbody {
  73   margin-left: 0;
  74 }
  75
  76 hr {
  77   border: 1px solid silver;
  78 }
  79
  80 p {
  81   margin-top: 0.5em;
  82   margin-bottom: 0.5em;
  83 }
  84
  85 ul, ol, li > p {
  86   margin-top: 0;
  87 }
  88 ul > li     { color: #aaa; }
  89 ul > li > * { color: black; }
  90
  91 .monospaced, code, pre {
  92   font-family: "Courier New", Courier, monospace;
  93   font-size: inherit;
  94   color: navy;
  95   padding: 0;
  96   margin: 0;
  97 }
  98 pre {
  99   white-space: pre-wrap;
 100 }
 101
 102 #author {
 103   color: #527bbd;
 104   font-weight: bold;
 105   font-size: 1.1em;
 106 }
 107 #email {
 108 }
 109 #revnumber, #revdate, #revremark {
 110 }
 111
 112 #footer {
 113   font-size: small;
 114   border-top: 2px solid silver;
 115   padding-top: 0.5em;
 116   margin-top: 4.0em;
 117 }
 118 #footer-text {
 119   float: left;
 120   padding-bottom: 0.5em;
 121 }
 122 #footer-badges {
 123   float: right;
 124   padding-bottom: 0.5em;
 125 }
 126
 127 #preamble {
 128   margin-top: 1.5em;
 129   margin-bottom: 1.5em;
 130 }
 131 div.imageblock, div.exampleblock, div.verseblock,
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 133 div.admonitionblock {
 134   margin-top: 1.0em;
 135   margin-bottom: 1.5em;
 136 }
 137 div.admonitionblock {
 138   margin-top: 2.0em;
 139   margin-bottom: 2.0em;
 140   margin-right: 10%;
 141   color: #606060;
 142 }
 143
 144 div.content { /* Block element content. */
 145   padding: 0;
 146 }
 147
 148 /* Block element titles. */
 149 div.title, caption.title {
 150   color: #527bbd;
 151   font-weight: bold;
 152   text-align: left;
 153   margin-top: 1.0em;
 154   margin-bottom: 0.5em;
 155 }
 156 div.title + * {
 157   margin-top: 0;
 158 }
 159
 160 td div.title:first-child {
 161   margin-top: 0.0em;
 162 }
 163 div.content div.title:first-child {
 164   margin-top: 0.0em;
 165 }
 166 div.content + div.title {
 167   margin-top: 0.0em;
 168 }
 169
 170 div.sidebarblock > div.content {
 171   background: #ffffee;
 172   border: 1px solid #dddddd;
 173   border-left: 4px solid #f0f0f0;
 174   padding: 0.5em;
 175 }
 176
 177 div.listingblock > div.content {
 178   border: 1px solid #dddddd;
 179   border-left: 5px solid #f0f0f0;
 180   background: #f8f8f8;
 181   padding: 0.5em;
 182 }
 183
 184 div.quoteblock, div.verseblock {
 185   padding-left: 1.0em;
 186   margin-left: 1.0em;
 187   margin-right: 10%;
 188   border-left: 5px solid #f0f0f0;
 189   color: #888;
 190 }
 191
 192 div.quoteblock > div.attribution {
 193   padding-top: 0.5em;
 194   text-align: right;
 195 }
 196
 197 div.verseblock > pre.content {
 198   font-family: inherit;
 199   font-size: inherit;
 200 }
 201 div.verseblock > div.attribution {
 202   padding-top: 0.75em;
 203   text-align: left;
 204 }
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 206 div.verseblock + div.attribution {
 207   text-align: left;
 208 }
 209
 210 div.admonitionblock .icon {
 211   vertical-align: top;
 212   font-size: 1.1em;
 213   font-weight: bold;
 214   text-decoration: underline;
 215   color: #527bbd;
 216   padding-right: 0.5em;
 217 }
 218 div.admonitionblock td.content {
 219   padding-left: 0.5em;
 220   border-left: 3px solid #dddddd;
 221 }
 222
 223 div.exampleblock > div.content {
 224   border-left: 3px solid #dddddd;
 225   padding-left: 0.5em;
 226 }
 227
 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; }
 231
 232 dl {
 233   margin-top: 0.8em;
 234   margin-bottom: 0.8em;
 235 }
 236 dt {
 237   margin-top: 0.5em;
 238   margin-bottom: 0;
 239   font-style: normal;
 240   color: navy;
 241 }
 242 dd > *:first-child {
 243   margin-top: 0.1em;
 244 }
 245
 246 ul, ol {
 247     list-style-position: outside;
 248 }
 249 ol.arabic {
 250   list-style-type: decimal;
 251 }
 252 ol.loweralpha {
 253   list-style-type: lower-alpha;
 254 }
 255 ol.upperalpha {
 256   list-style-type: upper-alpha;
 257 }
 258 ol.lowerroman {
 259   list-style-type: lower-roman;
 260 }
 261 ol.upperroman {
 262   list-style-type: upper-roman;
 263 }
 264
 265 div.compact ul, div.compact ol,
 266 div.compact p, div.compact p,
 267 div.compact div, div.compact div {
 268   margin-top: 0.1em;
 269   margin-bottom: 0.1em;
 270 }
 271
 272 tfoot {
 273   font-weight: bold;
 274 }
 275 td > div.verse {
 276   white-space: pre;
 277 }
 278
 279 div.hdlist {
 280   margin-top: 0.8em;
 281   margin-bottom: 0.8em;
 282 }
 283 div.hdlist tr {
 284   padding-bottom: 15px;
 285 }
 286 dt.hdlist1.strong, td.hdlist1.strong {
 287   font-weight: bold;
 288 }
 289 td.hdlist1 {
 290   vertical-align: top;
 291   font-style: normal;
 292   padding-right: 0.8em;
 293   color: navy;
 294 }
 295 td.hdlist2 {
 296   vertical-align: top;
 297 }
 298 div.hdlist.compact tr {
 299   margin: 0;
 300   padding-bottom: 0;
 301 }
 302
 303 .comment {
 304   background: yellow;
 305 }
 306
 307 .footnote, .footnoteref {
 308   font-size: 0.8em;
 309 }
 310
 311 span.footnote, span.footnoteref {
 312   vertical-align: super;
 313 }
 314
 315 #footnotes {
 316   margin: 20px 0 20px 0;
 317   padding: 7px 0 0 0;
 318 }
 319
 320 #footnotes div.footnote {
 321   margin: 0 0 5px 0;
 322 }
 323
 324 #footnotes hr {
 325   border: none;
 326   border-top: 1px solid silver;
 327   height: 1px;
 328   text-align: left;
 329   margin-left: 0;
 330   width: 20%;
 331   min-width: 100px;
 332 }
 333
 334 div.colist td {
 335   padding-right: 0.5em;
 336   padding-bottom: 0.3em;
 337   vertical-align: top;
 338 }
 339 div.colist td img {
 340   margin-top: 0.3em;
 341 }
 342
 343 @media print {
 344   #footer-badges { display: none; }
 345 }
 346
 347 #toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 #toctitle {
 352   color: #527bbd;
 353   font-size: 1.1em;
 354   font-weight: bold;
 355   margin-top: 1.0em;
 356   margin-bottom: 0.1em;
 357 }
 358
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 360   margin-top: 0;
 361   margin-bottom: 0;
 362 }
 363 div.toclevel2 {
 364   margin-left: 2em;
 365   font-size: 0.9em;
 366 }
 367 div.toclevel3 {
 368   margin-left: 4em;
 369   font-size: 0.9em;
 370 }
 371 div.toclevel4 {
 372   margin-left: 6em;
 373   font-size: 0.9em;
 374 }
 375
 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; }
 392
 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; }
 409
 410 span.big { font-size: 2em; }
 411 span.small { font-size: 0.6em; }
 412
 413 span.underline { text-decoration: underline; }
 414 span.overline { text-decoration: overline; }
 415 span.line-through { text-decoration: line-through; }
 416
 417 div.unbreakable { page-break-inside: avoid; }
 418
 419
 420 /*
 421  * xhtml11 specific
 422  *
 423  * */
 424
 425 div.tableblock {
 426   margin-top: 1.0em;
 427   margin-bottom: 1.5em;
 428 }
 429 div.tableblock > table {
 430   border: 3px solid #527bbd;
 431 }
 432 thead, p.table.header {
 433   font-weight: bold;
 434   color: #527bbd;
 435 }
 436 p.table {
 437   margin-top: 0;
 438 }
 439 /* Because the table frame attribute is overridden by CSS in most browsers. */
 440 div.tableblock > table[frame="void"] {
 441   border-style: none;
 442 }
 443 div.tableblock > table[frame="hsides"] {
 444   border-left-style: none;
 445   border-right-style: none;
 446 }
 447 div.tableblock > table[frame="vsides"] {
 448   border-top-style: none;
 449   border-bottom-style: none;
 450 }
 451
 452
 453 /*
 454  * html5 specific
 455  *
 456  * */
 457
 458 table.tableblock {
 459   margin-top: 1.0em;
 460   margin-bottom: 1.5em;
 461 }
 462 thead, p.tableblock.header {
 463   font-weight: bold;
 464   color: #527bbd;
 465 }
 466 p.tableblock {
 467   margin-top: 0;
 468 }
 469 table.tableblock {
 470   border-width: 3px;
 471   border-spacing: 0px;
 472   border-style: solid;
 473   border-color: #527bbd;
 474   border-collapse: collapse;
 475 }
 476 th.tableblock, td.tableblock {
 477   border-width: 1px;
 478   padding: 4px;
 479   border-style: solid;
 480   border-color: #527bbd;
 481 }
 482
 483 table.tableblock.frame-topbot {
 484   border-left-style: hidden;
 485   border-right-style: hidden;
 486 }
 487 table.tableblock.frame-sides {
 488   border-top-style: hidden;
 489   border-bottom-style: hidden;
 490 }
 491 table.tableblock.frame-none {
 492   border-style: hidden;
 493 }
 494
 495 th.tableblock.halign-left, td.tableblock.halign-left {
 496   text-align: left;
 497 }
 498 th.tableblock.halign-center, td.tableblock.halign-center {
 499   text-align: center;
 500 }
 501 th.tableblock.halign-right, td.tableblock.halign-right {
 502   text-align: right;
 503 }
 504
 505 th.tableblock.valign-top, td.tableblock.valign-top {
 506   vertical-align: top;
 507 }
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {
 509   vertical-align: middle;
 510 }
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 512   vertical-align: bottom;
 513 }
 514
 515
 516 /*
 517  * manpage specific
 518  *
 519  * */
 520
 521 body.manpage h1 {
 522   padding-top: 0.5em;
 523   padding-bottom: 0.5em;
 524   border-top: 2px solid silver;
 525   border-bottom: 2px solid silver;
 526 }
 527 body.manpage h2 {
 528   border-style: none;
 529 }
 530 body.manpage div.sectionbody {
 531   margin-left: 3em;
 532 }
 533
 534 @media print {
 535   body.manpage div#toc { display: none; }
 536 }
 537
 538
 539 </style>
 540 <script type="text/javascript">
 541 /*<![CDATA[*/
 542 var asciidoc = {  // Namespace.
 543
 544 /////////////////////////////////////////////////////////////////////
 545 // Table Of Contents generator
 546 /////////////////////////////////////////////////////////////////////
 547
 548 /* Author: Mihai Bazon, September 2002
 549  * http://students.infoiasi.ro/~mishoo
 550  *
 551  * Table Of Content generator
 552  * Version: 0.4
 553  *
 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.
 556  */
 557
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 560
 561 // toclevels = 1..4.
 562 toc: function (toclevels) {
 563
 564   function getText(el) {
 565     var text = "";
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 568         text += i.data;
 569       else if (i.firstChild != null)
 570         text += getText(i);
 571     }
 572     return text;
 573   }
 574
 575   function TocEntry(el, text, toclevel) {
 576     this.element = el;
 577     this.text = text;
 578     this.toclevel = toclevel;
 579   }
 580
 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
 586     // browsers).
 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);
 593           }
 594           iterate(i);
 595         }
 596       }
 597     }
 598     iterate(el);
 599     return result;
 600   }
 601
 602   var toc = document.getElementById("toc");
 603   if (!toc) {
 604     return;
 605   }
 606
 607   // Delete existing TOC entries in case we're reloading the TOC.
 608   var tocEntriesToRemove = [];
 609   var i;
 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);
 616   }
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {
 618     toc.removeChild(tocEntriesToRemove[i]);
 619   }
 620
 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");
 631     div.appendChild(a);
 632     div.className = "toclevel" + entry.toclevel;
 633     toc.appendChild(div);
 634   }
 635   if (entries.length == 0)
 636     toc.parentNode.removeChild(toc);
 637 },
 638
 639
 640 /////////////////////////////////////////////////////////////////////
 641 // Footnotes generator
 642 /////////////////////////////////////////////////////////////////////
 643
 644 /* Based on footnote generation code from:
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 646  */
 647
 648 footnotes: function () {
 649   // Delete existing footnote entries in case we're reloading the footnodes.
 650   var i;
 651   var noteholder = document.getElementById("footnotes");
 652   if (!noteholder) {
 653     return;
 654   }
 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);
 660   }
 661   for (i = 0; i < entriesToRemove.length; i++) {
 662     noteholder.removeChild(entriesToRemove[i]);
 663   }
 664
 665   // Rebuild footnote entries.
 666   var cont = document.getElementById("content");
 667   var spans = cont.getElementsByTagName("span");
 668   var refs = {};
 669   var n = 0;
 670   for (i=0; i<spans.length; i++) {
 671     if (spans[i].className == "footnote") {
 672       n++;
 673       var note = spans[i].getAttribute("data-note");
 674       if (!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];
 678         spans[i].innerHTML =
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";
 681         spans[i].setAttribute("data-note", note);
 682       }
 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;
 689     }
 690   }
 691   if (n == 0)
 692     noteholder.parentNode.removeChild(noteholder);
 693   else {
 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.
 699         n = refs[href];
 700         spans[i].innerHTML =
 701           "[<a href='#_footnote_" + n +
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";
 703       }
 704     }
 705   }
 706 },
 707
 708 install: function(toclevels) {
 709   var timerId;
 710
 711   function reinstall() {
 712     asciidoc.footnotes();
 713     if (toclevels) {
 714       asciidoc.toc(toclevels);
 715     }
 716   }
 717
 718   function reinstallAndRemoveTimer() {
 719     clearInterval(timerId);
 720     reinstall();
 721   }
 722
 723   timerId = setInterval(reinstall, 500);
 724   if (document.addEventListener)
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
 726   else
 727     window.onload = reinstallAndRemoveTimer;
 728 }
 729
 730 }
 731 asciidoc.install();
 732 /*]]>*/
 733 </script>
 734 </head>
 735 <body class="manpage">
 736 <div id="header">
 737 <h1>
 738 git-tag(1) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>git-tag -
 743    Create, list, delete or verify a tag object signed with GPG
 744 </p>
 745 </div>
 746 </div>
 747 <div id="content">
 748 <div class="sect1">
 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 &lt;key-id&gt;] [-f] [-m &lt;msg&gt; | -F &lt;file&gt;] [-e]
 753         &lt;tagname&gt; [&lt;commit&gt; | &lt;object&gt;]
 754 <em>git tag</em> -d &lt;tagname&gt;&#8230;
 755 <em>git tag</em> [-n[&lt;num&gt;]] -l [--contains &lt;commit&gt;] [--no-contains &lt;commit&gt;]
 756         [--points-at &lt;object&gt;] [--column[=&lt;options&gt;] | --no-column]
 757         [--create-reflog] [--sort=&lt;key&gt;] [--format=&lt;format&gt;]
 758         [--merged &lt;commit&gt;] [--no-merged &lt;commit&gt;] [&lt;pattern&gt;&#8230;]
 759 <em>git tag</em> -v [--format=&lt;format&gt;] &lt;tagname&gt;&#8230;</pre>
 760 <div class="attribution">
 761 </div></div>
 762 </div>
 763 </div>
 764 <div class="sect1">
 765 <h2 id="_description">DESCRIPTION</h2>
 766 <div class="sectionbody">
 767 <div class="paragraph"><p>Add a tag reference in <code>refs/tags/</code>, unless <code>-d/-l/-v</code> is given
 768 to delete, list or verify tags.</p></div>
 769 <div class="paragraph"><p>Unless <code>-f</code> is given, the named tag must not yet exist.</p></div>
 770 <div class="paragraph"><p>If one of <code>-a</code>, <code>-s</code>, or <code>-u &lt;key-id&gt;</code> is passed, the command
 771 creates a <em>tag</em> object, and requires a tag message.  Unless
 772 <code>-m &lt;msg&gt;</code> or <code>-F &lt;file&gt;</code> is given, an editor is started for the user to type
 773 in the tag message.</p></div>
 774 <div class="paragraph"><p>If <code>-m &lt;msg&gt;</code> or <code>-F &lt;file&gt;</code> is given and <code>-a</code>, <code>-s</code>, and <code>-u &lt;key-id&gt;</code>
 775 are absent, <code>-a</code> is implied.</p></div>
 776 <div class="paragraph"><p>Otherwise, a tag reference that points directly at the given object
 777 (i.e., a lightweight tag) is created.</p></div>
 778 <div class="paragraph"><p>A GnuPG signed tag object will be created when <code>-s</code> or <code>-u
 779 &lt;key-id&gt;</code> is used.  When <code>-u &lt;key-id&gt;</code> is not used, the
 780 committer identity for the current user is used to find the
 781 GnuPG key for signing.  The configuration variable <code>gpg.program</code>
 782 is used to specify custom GnuPG binary.</p></div>
 783 <div class="paragraph"><p>Tag objects (created with <code>-a</code>, <code>-s</code>, or <code>-u</code>) are called "annotated"
 784 tags; they contain a creation date, the tagger name and e-mail, a
 785 tagging message, and an optional GnuPG signature. Whereas a
 786 "lightweight" tag is simply a name for an object (usually a commit
 787 object).</p></div>
 788 <div class="paragraph"><p>Annotated tags are meant for release while lightweight tags are meant
 789 for private or temporary object labels. For this reason, some git
 790 commands for naming objects (like <code>git describe</code>) will ignore
 791 lightweight tags by default.</p></div>
 792 </div>
 793 </div>
 794 <div class="sect1">
 795 <h2 id="_options">OPTIONS</h2>
 796 <div class="sectionbody">
 797 <div class="dlist"><dl>
 798 <dt class="hdlist1">
 799 -a
 800 </dt>
 801 <dt class="hdlist1">
 802 --annotate
 803 </dt>
 804 <dd>
 805 <p>
 806         Make an unsigned, annotated tag object
 807 </p>
 808 </dd>
 809 <dt class="hdlist1">
 810 -s
 811 </dt>
 812 <dt class="hdlist1">
 813 --sign
 814 </dt>
 815 <dd>
 816 <p>
 817         Make a GPG-signed tag, using the default e-mail address&#8217;s key.
 818         The default behavior of tag GPG-signing is controlled by <code>tag.gpgSign</code>
 819         configuration variable if it exists, or disabled otherwise.
 820         See <a href="git-config.html">git-config(1)</a>.
 821 </p>
 822 </dd>
 823 <dt class="hdlist1">
 824 --no-sign
 825 </dt>
 826 <dd>
 827 <p>
 828         Override <code>tag.gpgSign</code> configuration variable that is
 829         set to force each and every tag to be signed.
 830 </p>
 831 </dd>
 832 <dt class="hdlist1">
 833 -u &lt;key-id&gt;
 834 </dt>
 835 <dt class="hdlist1">
 836 --local-user=&lt;key-id&gt;
 837 </dt>
 838 <dd>
 839 <p>
 840         Make a GPG-signed tag, using the given key.
 841 </p>
 842 </dd>
 843 <dt class="hdlist1">
 844 -f
 845 </dt>
 846 <dt class="hdlist1">
 847 --force
 848 </dt>
 849 <dd>
 850 <p>
 851         Replace an existing tag with the given name (instead of failing)
 852 </p>
 853 </dd>
 854 <dt class="hdlist1">
 855 -d
 856 </dt>
 857 <dt class="hdlist1">
 858 --delete
 859 </dt>
 860 <dd>
 861 <p>
 862         Delete existing tags with the given names.
 863 </p>
 864 </dd>
 865 <dt class="hdlist1">
 866 -v
 867 </dt>
 868 <dt class="hdlist1">
 869 --verify
 870 </dt>
 871 <dd>
 872 <p>
 873         Verify the GPG signature of the given tag names.
 874 </p>
 875 </dd>
 876 <dt class="hdlist1">
 877 -n&lt;num&gt;
 878 </dt>
 879 <dd>
 880 <p>
 881         &lt;num&gt; specifies how many lines from the annotation, if any,
 882         are printed when using -l. Implies <code>--list</code>.
 883 </p>
 884 <div class="paragraph"><p>The default is not to print any annotation lines.
 885 If no number is given to <code>-n</code>, only the first line is printed.
 886 If the tag is not annotated, the commit message is displayed instead.</p></div>
 887 </dd>
 888 <dt class="hdlist1">
 889 -l
 890 </dt>
 891 <dt class="hdlist1">
 892 --list
 893 </dt>
 894 <dd>
 895 <p>
 896         List tags. With optional <code>&lt;pattern&gt;...</code>, e.g. <code>git tag --list
 897         'v-*'</code>, list only the tags that match the pattern(s).
 898 </p>
 899 <div class="paragraph"><p>Running "git tag" without arguments also lists all tags. The pattern
 900 is a shell wildcard (i.e., matched using fnmatch(3)). Multiple
 901 patterns may be given; if any of them matches, the tag is shown.</p></div>
 902 <div class="paragraph"><p>This option is implicitly supplied if any other list-like option such
 903 as <code>--contains</code> is provided. See the documentation for each of those
 904 options for details.</p></div>
 905 </dd>
 906 <dt class="hdlist1">
 907 --sort=&lt;key&gt;
 908 </dt>
 909 <dd>
 910 <p>
 911         Sort based on the key given.  Prefix <code>-</code> to sort in
 912         descending order of the value. You may use the --sort=&lt;key&gt; option
 913         multiple times, in which case the last key becomes the primary
 914         key. Also supports "version:refname" or "v:refname" (tag
 915         names are treated as versions). The "version:refname" sort
 916         order can also be affected by the "versionsort.suffix"
 917         configuration variable.
 918         The keys supported are the same as those in <code>git for-each-ref</code>.
 919         Sort order defaults to the value configured for the <code>tag.sort</code>
 920         variable if it exists, or lexicographic order otherwise. See
 921         <a href="git-config.html">git-config(1)</a>.
 922 </p>
 923 </dd>
 924 <dt class="hdlist1">
 925 --color[=&lt;when&gt;]
 926 </dt>
 927 <dd>
 928 <p>
 929         Respect any colors specified in the <code>--format</code> option. The
 930         <code>&lt;when&gt;</code> field must be one of <code>always</code>, <code>never</code>, or <code>auto</code> (if
 931         <code>&lt;when&gt;</code> is absent, behave as if <code>always</code> was given).
 932 </p>
 933 </dd>
 934 <dt class="hdlist1">
 935 -i
 936 </dt>
 937 <dt class="hdlist1">
 938 --ignore-case
 939 </dt>
 940 <dd>
 941 <p>
 942         Sorting and filtering tags are case insensitive.
 943 </p>
 944 </dd>
 945 <dt class="hdlist1">
 946 --omit-empty
 947 </dt>
 948 <dd>
 949 <p>
 950         Do not print a newline after formatted refs where the format expands
 951         to the empty string.
 952 </p>
 953 </dd>
 954 <dt class="hdlist1">
 955 --column[=&lt;options&gt;]
 956 </dt>
 957 <dt class="hdlist1">
 958 --no-column
 959 </dt>
 960 <dd>
 961 <p>
 962         Display tag listing in columns. See configuration variable
 963         <code>column.tag</code> for option syntax. <code>--column</code> and <code>--no-column</code>
 964         without options are equivalent to <em>always</em> and <em>never</em> respectively.
 965 </p>
 966 <div class="paragraph"><p>This option is only applicable when listing tags without annotation lines.</p></div>
 967 </dd>
 968 <dt class="hdlist1">
 969 --contains [&lt;commit&gt;]
 970 </dt>
 971 <dd>
 972 <p>
 973         Only list tags which contain the specified commit (HEAD if not
 974         specified). Implies <code>--list</code>.
 975 </p>
 976 </dd>
 977 <dt class="hdlist1">
 978 --no-contains [&lt;commit&gt;]
 979 </dt>
 980 <dd>
 981 <p>
 982         Only list tags which don&#8217;t contain the specified commit (HEAD if
 983         not specified). Implies <code>--list</code>.
 984 </p>
 985 </dd>
 986 <dt class="hdlist1">
 987 --merged [&lt;commit&gt;]
 988 </dt>
 989 <dd>
 990 <p>
 991         Only list tags whose commits are reachable from the specified
 992         commit (<code>HEAD</code> if not specified).
 993 </p>
 994 </dd>
 995 <dt class="hdlist1">
 996 --no-merged [&lt;commit&gt;]
 997 </dt>
 998 <dd>
 999 <p>
1000         Only list tags whose commits are not reachable from the specified
1001         commit (<code>HEAD</code> if not specified).
1002 </p>
1003 </dd>
1004 <dt class="hdlist1">
1005 --points-at &lt;object&gt;
1006 </dt>
1007 <dd>
1008 <p>
1009         Only list tags of the given object (HEAD if not
1010         specified). Implies <code>--list</code>.
1011 </p>
1012 </dd>
1013 <dt class="hdlist1">
1014 -m &lt;msg&gt;
1015 </dt>
1016 <dt class="hdlist1">
1017 --message=&lt;msg&gt;
1018 </dt>
1019 <dd>
1020 <p>
1021         Use the given tag message (instead of prompting).
1022         If multiple <code>-m</code> options are given, their values are
1023         concatenated as separate paragraphs.
1024         Implies <code>-a</code> if none of <code>-a</code>, <code>-s</code>, or <code>-u &lt;key-id&gt;</code>
1025         is given.
1026 </p>
1027 </dd>
1028 <dt class="hdlist1">
1029 -F &lt;file&gt;
1030 </dt>
1031 <dt class="hdlist1">
1032 --file=&lt;file&gt;
1033 </dt>
1034 <dd>
1035 <p>
1036         Take the tag message from the given file.  Use <em>-</em> to
1037         read the message from the standard input.
1038         Implies <code>-a</code> if none of <code>-a</code>, <code>-s</code>, or <code>-u &lt;key-id&gt;</code>
1039         is given.
1040 </p>
1041 </dd>
1042 <dt class="hdlist1">
1043 -e
1044 </dt>
1045 <dt class="hdlist1">
1046 --edit
1047 </dt>
1048 <dd>
1049 <p>
1050         The message taken from file with <code>-F</code> and command line with
1051         <code>-m</code> are usually used as the tag message unmodified.
1052         This option lets you further edit the message taken from these sources.
1053 </p>
1054 </dd>
1055 <dt class="hdlist1">
1056 --cleanup=&lt;mode&gt;
1057 </dt>
1058 <dd>
1059 <p>
1060         This option sets how the tag message is cleaned up.
1061         The  <em>&lt;mode&gt;</em> can be one of <em>verbatim</em>, <em>whitespace</em> and <em>strip</em>.  The
1062         <em>strip</em> mode is default. The <em>verbatim</em> mode does not change message at
1063         all, <em>whitespace</em> removes just leading/trailing whitespace lines and
1064         <em>strip</em> removes both whitespace and commentary.
1065 </p>
1066 </dd>
1067 <dt class="hdlist1">
1068 --create-reflog
1069 </dt>
1070 <dd>
1071 <p>
1072         Create a reflog for the tag. To globally enable reflogs for tags, see
1073         <code>core.logAllRefUpdates</code> in <a href="git-config.html">git-config(1)</a>.
1074         The negated form <code>--no-create-reflog</code> only overrides an earlier
1075         <code>--create-reflog</code>, but currently does not negate the setting of
1076         <code>core.logAllRefUpdates</code>.
1077 </p>
1078 </dd>
1079 <dt class="hdlist1">
1080 --format=&lt;format&gt;
1081 </dt>
1082 <dd>
1083 <p>
1084         A string that interpolates <code>%(fieldname)</code> from a tag ref being shown
1085         and the object it points at.  The format is the same as
1086         that of <a href="git-for-each-ref.html">git-for-each-ref(1)</a>.  When unspecified,
1087         defaults to <code>%(refname:strip=2)</code>.
1088 </p>
1089 </dd>
1090 <dt class="hdlist1">
1091 &lt;tagname&gt;
1092 </dt>
1093 <dd>
1094 <p>
1095         The name of the tag to create, delete, or describe.
1096         The new tag name must pass all checks defined by
1097         <a href="git-check-ref-format.html">git-check-ref-format(1)</a>.  Some of these checks
1098         may restrict the characters allowed in a tag name.
1099 </p>
1100 </dd>
1101 <dt class="hdlist1">
1102 &lt;commit&gt;
1103 </dt>
1104 <dt class="hdlist1">
1105 &lt;object&gt;
1106 </dt>
1107 <dd>
1108 <p>
1109         The object that the new tag will refer to, usually a commit.
1110         Defaults to HEAD.
1111 </p>
1112 </dd>
1113 </dl></div>
1114 </div>
1115 </div>
1116 <div class="sect1">
1117 <h2 id="_configuration">CONFIGURATION</h2>
1118 <div class="sectionbody">
1119 <div class="paragraph"><p>By default, <em>git tag</em> in sign-with-default mode (-s) will use your
1120 committer identity (of the form <code>Your Name &lt;your@email.address&gt;</code>) to
1121 find a key.  If you want to use a different default key, you can specify
1122 it in the repository configuration as follows:</p></div>
1123 <div class="listingblock">
1124 <div class="content">
1125 <pre><code>[user]
1126     signingKey = &lt;gpg-key_id&gt;</code></pre>
1127 </div></div>
1128 <div class="paragraph"><p><code>pager.tag</code> is only respected when listing tags, i.e., when <code>-l</code> is
1129 used or implied. The default is to use a pager.
1130 See <a href="git-config.html">git-config(1)</a>.</p></div>
1131 </div>
1132 </div>
1133 <div class="sect1">
1134 <h2 id="_discussion">DISCUSSION</h2>
1135 <div class="sectionbody">
1136 <div class="sect2">
1137 <h3 id="_on_re_tagging">On Re-tagging</h3>
1138 <div class="paragraph"><p>What should you do when you tag a wrong commit and you would
1139 want to re-tag?</p></div>
1140 <div class="paragraph"><p>If you never pushed anything out, just re-tag it. Use "-f" to
1141 replace the old one. And you&#8217;re done.</p></div>
1142 <div class="paragraph"><p>But if you have pushed things out (or others could just read
1143 your repository directly), then others will have already seen
1144 the old tag. In that case you can do one of two things:</p></div>
1145 <div class="olist arabic"><ol class="arabic">
1146 <li>
1147 <p>
1148 The sane thing.
1149   Just admit you screwed up, and use a different name. Others have
1150   already seen one tag-name, and if you keep the same name, you
1151   may be in the situation that two people both have "version X",
1152   but they actually have <em>different</em> "X"'s.  So just call it "X.1"
1153   and be done with it.
1154 </p>
1155 </li>
1156 <li>
1157 <p>
1158 The insane thing.
1159   You really want to call the new version "X" too, <em>even though</em>
1160   others have already seen the old one. So just use <em>git tag -f</em>
1161   again, as if you hadn&#8217;t already published the old one.
1162 </p>
1163 </li>
1164 </ol></div>
1165 <div class="paragraph"><p>However, Git does <strong>not</strong> (and it should not) change tags behind
1166 users back. So if somebody already got the old tag, doing a
1167 <em>git pull</em> on your tree shouldn&#8217;t just make them overwrite the old
1168 one.</p></div>
1169 <div class="paragraph"><p>If somebody got a release tag from you, you cannot just change
1170 the tag for them by updating your own one. This is a big
1171 security issue, in that people MUST be able to trust their
1172 tag-names.  If you really want to do the insane thing, you need
1173 to just fess up to it, and tell people that you messed up. You
1174 can do that by making a very public announcement saying:</p></div>
1175 <div class="listingblock">
1176 <div class="content">
1177 <pre><code>Ok, I messed up, and I pushed out an earlier version tagged as X. I
1178 then fixed something, and retagged the *fixed* tree as X again.
1179
1180 If you got the wrong tag, and want the new one, please delete
1181 the old one and fetch the new one by doing:
1182
1183         git tag -d X
1184         git fetch origin tag X
1185
1186 to get my updated tag.
1187
1188 You can test which tag you have by doing
1189
1190         git rev-parse X
1191
1192 which should return 0123456789abcdef.. if you have the new version.
1193
1194 Sorry for the inconvenience.</code></pre>
1195 </div></div>
1196 <div class="paragraph"><p>Does this seem a bit complicated?  It <strong>should</strong> be. There is no
1197 way that it would be correct to just "fix" it automatically.
1198 People need to know that their tags might have been changed.</p></div>
1199 </div>
1200 <div class="sect2">
1201 <h3 id="_on_automatic_following">On Automatic following</h3>
1202 <div class="paragraph"><p>If you are following somebody else&#8217;s tree, you are most likely
1203 using remote-tracking branches (eg. <code>refs/remotes/origin/master</code>).
1204 You usually want the tags from the other end.</p></div>
1205 <div class="paragraph"><p>On the other hand, if you are fetching because you would want a
1206 one-shot merge from somebody else, you typically do not want to
1207 get tags from there.  This happens more often for people near
1208 the toplevel but not limited to them.  Mere mortals when pulling
1209 from each other do not necessarily want to automatically get
1210 private anchor point tags from the other person.</p></div>
1211 <div class="paragraph"><p>Often, "please pull" messages on the mailing list just provide
1212 two pieces of information: a repo URL and a branch name; this
1213 is designed to be easily cut&amp;pasted at the end of a <em>git fetch</em>
1214 command line:</p></div>
1215 <div class="listingblock">
1216 <div class="content">
1217 <pre><code>Linus, please pull from
1218
1219         git://git..../proj.git master
1220
1221 to get the following updates...</code></pre>
1222 </div></div>
1223 <div class="paragraph"><p>becomes:</p></div>
1224 <div class="listingblock">
1225 <div class="content">
1226 <pre><code>$ git pull git://git..../proj.git master</code></pre>
1227 </div></div>
1228 <div class="paragraph"><p>In such a case, you do not want to automatically follow the other
1229 person&#8217;s tags.</p></div>
1230 <div class="paragraph"><p>One important aspect of Git is its distributed nature, which
1231 largely means there is no inherent "upstream" or
1232 "downstream" in the system.  On the face of it, the above
1233 example might seem to indicate that the tag namespace is owned
1234 by the upper echelon of people and that tags only flow downwards, but
1235 that is not the case.  It only shows that the usage pattern
1236 determines who are interested in whose tags.</p></div>
1237 <div class="paragraph"><p>A one-shot pull is a sign that a commit history is now crossing
1238 the boundary between one circle of people (e.g. "people who are
1239 primarily interested in the networking part of the kernel") who may
1240 have their own set of tags (e.g. "this is the third release
1241 candidate from the networking group to be proposed for general
1242 consumption with 2.6.21 release") to another circle of people
1243 (e.g. "people who integrate various subsystem improvements").
1244 The latter are usually not interested in the detailed tags used
1245 internally in the former group (that is what "internal" means).
1246 That is why it is desirable not to follow tags automatically in
1247 this case.</p></div>
1248 <div class="paragraph"><p>It may well be that among networking people, they may want to
1249 exchange the tags internal to their group, but in that workflow
1250 they are most likely tracking each other&#8217;s progress by
1251 having remote-tracking branches.  Again, the heuristic to automatically
1252 follow such tags is a good thing.</p></div>
1253 </div>
1254 <div class="sect2">
1255 <h3 id="_on_backdating_tags">On Backdating Tags</h3>
1256 <div class="paragraph"><p>If you have imported some changes from another VCS and would like
1257 to add tags for major releases of your work, it is useful to be able
1258 to specify the date to embed inside of the tag object; such data in
1259 the tag object affects, for example, the ordering of tags in the
1260 gitweb interface.</p></div>
1261 <div class="paragraph"><p>To set the date used in future tag objects, set the environment
1262 variable GIT_COMMITTER_DATE (see the later discussion of possible
1263 values; the most common form is "YYYY-MM-DD HH:MM").</p></div>
1264 <div class="paragraph"><p>For example:</p></div>
1265 <div class="listingblock">
1266 <div class="content">
1267 <pre><code>$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1</code></pre>
1268 </div></div>
1269 </div>
1270 </div>
1271 </div>
1272 <div class="sect1">
1273 <h2 id="_date_formats">DATE FORMATS</h2>
1274 <div class="sectionbody">
1275 <div class="paragraph"><p>The <code>GIT_AUTHOR_DATE</code> and <code>GIT_COMMITTER_DATE</code> environment variables
1276 support the following date formats:</p></div>
1277 <div class="dlist"><dl>
1278 <dt class="hdlist1">
1279 Git internal format
1280 </dt>
1281 <dd>
1282 <p>
1283         It is <code>&lt;unix-timestamp&gt; &lt;time-zone-offset&gt;</code>, where
1284         <code>&lt;unix-timestamp&gt;</code> is the number of seconds since the UNIX epoch.
1285         <code>&lt;time-zone-offset&gt;</code> is a positive or negative offset from UTC.
1286         For example CET (which is 1 hour ahead of UTC) is <code>+0100</code>.
1287 </p>
1288 </dd>
1289 <dt class="hdlist1">
1290 RFC 2822
1291 </dt>
1292 <dd>
1293 <p>
1294         The standard email format as described by RFC 2822, for example
1295         <code>Thu, 07 Apr 2005 22:13:13 +0200</code>.
1296 </p>
1297 </dd>
1298 <dt class="hdlist1">
1299 ISO 8601
1300 </dt>
1301 <dd>
1302 <p>
1303         Time and date specified by the ISO 8601 standard, for example
1304         <code>2005-04-07T22:13:13</code>. The parser accepts a space instead of the
1305         <code>T</code> character as well. Fractional parts of a second will be ignored,
1306         for example <code>2005-04-07T22:13:13.019</code> will be treated as
1307         <code>2005-04-07T22:13:13</code>.
1308 </p>
1309 <div class="admonitionblock">
1310 <table><tr>
1311 <td class="icon">
1312 <div class="title">Note</div>
1313 </td>
1314 <td class="content">In addition, the date part is accepted in the following formats:
1315 <code>YYYY.MM.DD</code>, <code>MM/DD/YYYY</code> and <code>DD.MM.YYYY</code>.</td>
1316 </tr></table>
1317 </div>
1318 </dd>
1319 </dl></div>
1320 </div>
1321 </div>
1322 <div class="sect1">
1323 <h2 id="_files">FILES</h2>
1324 <div class="sectionbody">
1325 <div class="dlist"><dl>
1326 <dt class="hdlist1">
1327 <code>$GIT_DIR/TAG_EDITMSG</code>
1328 </dt>
1329 <dd>
1330 <p>
1331         This file contains the message of an in-progress annotated
1332         tag. If <code>git tag</code> exits due to an error before creating an
1333         annotated tag then the tag message that has been provided by the
1334         user in an editor session will be available in this file, but
1335         may be overwritten by the next invocation of <code>git tag</code>.
1336 </p>
1337 </dd>
1338 </dl></div>
1339 </div>
1340 </div>
1341 <div class="sect1">
1342 <h2 id="_notes">NOTES</h2>
1343 <div class="sectionbody">
1344 <div class="paragraph"><p>When combining multiple <code>--contains</code> and <code>--no-contains</code> filters, only
1345 references that contain at least one of the <code>--contains</code> commits and
1346 contain none of the <code>--no-contains</code> commits are shown.</p></div>
1347 <div class="paragraph"><p>When combining multiple <code>--merged</code> and <code>--no-merged</code> filters, only
1348 references that are reachable from at least one of the <code>--merged</code>
1349 commits and from none of the <code>--no-merged</code> commits are shown.</p></div>
1350 </div>
1351 </div>
1352 <div class="sect1">
1353 <h2 id="_see_also">SEE ALSO</h2>
1354 <div class="sectionbody">
1355 <div class="paragraph"><p><a href="git-check-ref-format.html">git-check-ref-format(1)</a>.
1356 <a href="git-config.html">git-config(1)</a>.</p></div>
1357 </div>
1358 </div>
1359 <div class="sect1">
1360 <h2 id="_git">GIT</h2>
1361 <div class="sectionbody">
1362 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1363 </div>
1364 </div>
1365 </div>
1366 <div id="footnotes"><hr /></div>
1367 <div id="footer">
1368 <div id="footer-text">
1369 Last updated
1370  2023-06-13 13:57:42 PDT
1371 </div>
1372 </div>
1373 </body>
1374 </html>