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 --column[=&lt;options&gt;]
 947 </dt>
 948 <dt class="hdlist1">
 949 --no-column
 950 </dt>
 951 <dd>
 952 <p>
 953         Display tag listing in columns. See configuration variable
 954         <code>column.tag</code> for option syntax. <code>--column</code> and <code>--no-column</code>
 955         without options are equivalent to <em>always</em> and <em>never</em> respectively.
 956 </p>
 957 <div class="paragraph"><p>This option is only applicable when listing tags without annotation lines.</p></div>
 958 </dd>
 959 <dt class="hdlist1">
 960 --contains [&lt;commit&gt;]
 961 </dt>
 962 <dd>
 963 <p>
 964         Only list tags which contain the specified commit (HEAD if not
 965         specified). Implies <code>--list</code>.
 966 </p>
 967 </dd>
 968 <dt class="hdlist1">
 969 --no-contains [&lt;commit&gt;]
 970 </dt>
 971 <dd>
 972 <p>
 973         Only list tags which don&#8217;t contain the specified commit (HEAD if
 974         not specified). Implies <code>--list</code>.
 975 </p>
 976 </dd>
 977 <dt class="hdlist1">
 978 --merged [&lt;commit&gt;]
 979 </dt>
 980 <dd>
 981 <p>
 982         Only list tags whose commits are reachable from the specified
 983         commit (<code>HEAD</code> if not specified).
 984 </p>
 985 </dd>
 986 <dt class="hdlist1">
 987 --no-merged [&lt;commit&gt;]
 988 </dt>
 989 <dd>
 990 <p>
 991         Only list tags whose commits are not reachable from the specified
 992         commit (<code>HEAD</code> if not specified).
 993 </p>
 994 </dd>
 995 <dt class="hdlist1">
 996 --points-at &lt;object&gt;
 997 </dt>
 998 <dd>
 999 <p>
1000         Only list tags of the given object (HEAD if not
1001         specified). Implies <code>--list</code>.
1002 </p>
1003 </dd>
1004 <dt class="hdlist1">
1005 -m &lt;msg&gt;
1006 </dt>
1007 <dt class="hdlist1">
1008 --message=&lt;msg&gt;
1009 </dt>
1010 <dd>
1011 <p>
1012         Use the given tag message (instead of prompting).
1013         If multiple <code>-m</code> options are given, their values are
1014         concatenated as separate paragraphs.
1015         Implies <code>-a</code> if none of <code>-a</code>, <code>-s</code>, or <code>-u &lt;key-id&gt;</code>
1016         is given.
1017 </p>
1018 </dd>
1019 <dt class="hdlist1">
1020 -F &lt;file&gt;
1021 </dt>
1022 <dt class="hdlist1">
1023 --file=&lt;file&gt;
1024 </dt>
1025 <dd>
1026 <p>
1027         Take the tag message from the given file.  Use <em>-</em> to
1028         read the message from the standard input.
1029         Implies <code>-a</code> if none of <code>-a</code>, <code>-s</code>, or <code>-u &lt;key-id&gt;</code>
1030         is given.
1031 </p>
1032 </dd>
1033 <dt class="hdlist1">
1034 -e
1035 </dt>
1036 <dt class="hdlist1">
1037 --edit
1038 </dt>
1039 <dd>
1040 <p>
1041         The message taken from file with <code>-F</code> and command line with
1042         <code>-m</code> are usually used as the tag message unmodified.
1043         This option lets you further edit the message taken from these sources.
1044 </p>
1045 </dd>
1046 <dt class="hdlist1">
1047 --cleanup=&lt;mode&gt;
1048 </dt>
1049 <dd>
1050 <p>
1051         This option sets how the tag message is cleaned up.
1052         The  <em>&lt;mode&gt;</em> can be one of <em>verbatim</em>, <em>whitespace</em> and <em>strip</em>.  The
1053         <em>strip</em> mode is default. The <em>verbatim</em> mode does not change message at
1054         all, <em>whitespace</em> removes just leading/trailing whitespace lines and
1055         <em>strip</em> removes both whitespace and commentary.
1056 </p>
1057 </dd>
1058 <dt class="hdlist1">
1059 --create-reflog
1060 </dt>
1061 <dd>
1062 <p>
1063         Create a reflog for the tag. To globally enable reflogs for tags, see
1064         <code>core.logAllRefUpdates</code> in <a href="git-config.html">git-config(1)</a>.
1065         The negated form <code>--no-create-reflog</code> only overrides an earlier
1066         <code>--create-reflog</code>, but currently does not negate the setting of
1067         <code>core.logAllRefUpdates</code>.
1068 </p>
1069 </dd>
1070 <dt class="hdlist1">
1071 --format=&lt;format&gt;
1072 </dt>
1073 <dd>
1074 <p>
1075         A string that interpolates <code>%(fieldname)</code> from a tag ref being shown
1076         and the object it points at.  The format is the same as
1077         that of <a href="git-for-each-ref.html">git-for-each-ref(1)</a>.  When unspecified,
1078         defaults to <code>%(refname:strip=2)</code>.
1079 </p>
1080 </dd>
1081 <dt class="hdlist1">
1082 &lt;tagname&gt;
1083 </dt>
1084 <dd>
1085 <p>
1086         The name of the tag to create, delete, or describe.
1087         The new tag name must pass all checks defined by
1088         <a href="git-check-ref-format.html">git-check-ref-format(1)</a>.  Some of these checks
1089         may restrict the characters allowed in a tag name.
1090 </p>
1091 </dd>
1092 <dt class="hdlist1">
1093 &lt;commit&gt;
1094 </dt>
1095 <dt class="hdlist1">
1096 &lt;object&gt;
1097 </dt>
1098 <dd>
1099 <p>
1100         The object that the new tag will refer to, usually a commit.
1101         Defaults to HEAD.
1102 </p>
1103 </dd>
1104 </dl></div>
1105 </div>
1106 </div>
1107 <div class="sect1">
1108 <h2 id="_configuration">CONFIGURATION</h2>
1109 <div class="sectionbody">
1110 <div class="paragraph"><p>By default, <em>git tag</em> in sign-with-default mode (-s) will use your
1111 committer identity (of the form <code>Your Name &lt;your@email.address&gt;</code>) to
1112 find a key.  If you want to use a different default key, you can specify
1113 it in the repository configuration as follows:</p></div>
1114 <div class="listingblock">
1115 <div class="content">
1116 <pre><code>[user]
1117     signingKey = &lt;gpg-key_id&gt;</code></pre>
1118 </div></div>
1119 <div class="paragraph"><p><code>pager.tag</code> is only respected when listing tags, i.e., when <code>-l</code> is
1120 used or implied. The default is to use a pager.
1121 See <a href="git-config.html">git-config(1)</a>.</p></div>
1122 </div>
1123 </div>
1124 <div class="sect1">
1125 <h2 id="_discussion">DISCUSSION</h2>
1126 <div class="sectionbody">
1127 <div class="sect2">
1128 <h3 id="_on_re_tagging">On Re-tagging</h3>
1129 <div class="paragraph"><p>What should you do when you tag a wrong commit and you would
1130 want to re-tag?</p></div>
1131 <div class="paragraph"><p>If you never pushed anything out, just re-tag it. Use "-f" to
1132 replace the old one. And you&#8217;re done.</p></div>
1133 <div class="paragraph"><p>But if you have pushed things out (or others could just read
1134 your repository directly), then others will have already seen
1135 the old tag. In that case you can do one of two things:</p></div>
1136 <div class="olist arabic"><ol class="arabic">
1137 <li>
1138 <p>
1139 The sane thing.
1140   Just admit you screwed up, and use a different name. Others have
1141   already seen one tag-name, and if you keep the same name, you
1142   may be in the situation that two people both have "version X",
1143   but they actually have <em>different</em> "X"'s.  So just call it "X.1"
1144   and be done with it.
1145 </p>
1146 </li>
1147 <li>
1148 <p>
1149 The insane thing.
1150   You really want to call the new version "X" too, <em>even though</em>
1151   others have already seen the old one. So just use <em>git tag -f</em>
1152   again, as if you hadn&#8217;t already published the old one.
1153 </p>
1154 </li>
1155 </ol></div>
1156 <div class="paragraph"><p>However, Git does <strong>not</strong> (and it should not) change tags behind
1157 users back. So if somebody already got the old tag, doing a
1158 <em>git pull</em> on your tree shouldn&#8217;t just make them overwrite the old
1159 one.</p></div>
1160 <div class="paragraph"><p>If somebody got a release tag from you, you cannot just change
1161 the tag for them by updating your own one. This is a big
1162 security issue, in that people MUST be able to trust their
1163 tag-names.  If you really want to do the insane thing, you need
1164 to just fess up to it, and tell people that you messed up. You
1165 can do that by making a very public announcement saying:</p></div>
1166 <div class="listingblock">
1167 <div class="content">
1168 <pre><code>Ok, I messed up, and I pushed out an earlier version tagged as X. I
1169 then fixed something, and retagged the *fixed* tree as X again.
1170
1171 If you got the wrong tag, and want the new one, please delete
1172 the old one and fetch the new one by doing:
1173
1174         git tag -d X
1175         git fetch origin tag X
1176
1177 to get my updated tag.
1178
1179 You can test which tag you have by doing
1180
1181         git rev-parse X
1182
1183 which should return 0123456789abcdef.. if you have the new version.
1184
1185 Sorry for the inconvenience.</code></pre>
1186 </div></div>
1187 <div class="paragraph"><p>Does this seem a bit complicated?  It <strong>should</strong> be. There is no
1188 way that it would be correct to just "fix" it automatically.
1189 People need to know that their tags might have been changed.</p></div>
1190 </div>
1191 <div class="sect2">
1192 <h3 id="_on_automatic_following">On Automatic following</h3>
1193 <div class="paragraph"><p>If you are following somebody else&#8217;s tree, you are most likely
1194 using remote-tracking branches (eg. <code>refs/remotes/origin/master</code>).
1195 You usually want the tags from the other end.</p></div>
1196 <div class="paragraph"><p>On the other hand, if you are fetching because you would want a
1197 one-shot merge from somebody else, you typically do not want to
1198 get tags from there.  This happens more often for people near
1199 the toplevel but not limited to them.  Mere mortals when pulling
1200 from each other do not necessarily want to automatically get
1201 private anchor point tags from the other person.</p></div>
1202 <div class="paragraph"><p>Often, "please pull" messages on the mailing list just provide
1203 two pieces of information: a repo URL and a branch name; this
1204 is designed to be easily cut&amp;pasted at the end of a <em>git fetch</em>
1205 command line:</p></div>
1206 <div class="listingblock">
1207 <div class="content">
1208 <pre><code>Linus, please pull from
1209
1210         git://git..../proj.git master
1211
1212 to get the following updates...</code></pre>
1213 </div></div>
1214 <div class="paragraph"><p>becomes:</p></div>
1215 <div class="listingblock">
1216 <div class="content">
1217 <pre><code>$ git pull git://git..../proj.git master</code></pre>
1218 </div></div>
1219 <div class="paragraph"><p>In such a case, you do not want to automatically follow the other
1220 person&#8217;s tags.</p></div>
1221 <div class="paragraph"><p>One important aspect of Git is its distributed nature, which
1222 largely means there is no inherent "upstream" or
1223 "downstream" in the system.  On the face of it, the above
1224 example might seem to indicate that the tag namespace is owned
1225 by the upper echelon of people and that tags only flow downwards, but
1226 that is not the case.  It only shows that the usage pattern
1227 determines who are interested in whose tags.</p></div>
1228 <div class="paragraph"><p>A one-shot pull is a sign that a commit history is now crossing
1229 the boundary between one circle of people (e.g. "people who are
1230 primarily interested in the networking part of the kernel") who may
1231 have their own set of tags (e.g. "this is the third release
1232 candidate from the networking group to be proposed for general
1233 consumption with 2.6.21 release") to another circle of people
1234 (e.g. "people who integrate various subsystem improvements").
1235 The latter are usually not interested in the detailed tags used
1236 internally in the former group (that is what "internal" means).
1237 That is why it is desirable not to follow tags automatically in
1238 this case.</p></div>
1239 <div class="paragraph"><p>It may well be that among networking people, they may want to
1240 exchange the tags internal to their group, but in that workflow
1241 they are most likely tracking each other&#8217;s progress by
1242 having remote-tracking branches.  Again, the heuristic to automatically
1243 follow such tags is a good thing.</p></div>
1244 </div>
1245 <div class="sect2">
1246 <h3 id="_on_backdating_tags">On Backdating Tags</h3>
1247 <div class="paragraph"><p>If you have imported some changes from another VCS and would like
1248 to add tags for major releases of your work, it is useful to be able
1249 to specify the date to embed inside of the tag object; such data in
1250 the tag object affects, for example, the ordering of tags in the
1251 gitweb interface.</p></div>
1252 <div class="paragraph"><p>To set the date used in future tag objects, set the environment
1253 variable GIT_COMMITTER_DATE (see the later discussion of possible
1254 values; the most common form is "YYYY-MM-DD HH:MM").</p></div>
1255 <div class="paragraph"><p>For example:</p></div>
1256 <div class="listingblock">
1257 <div class="content">
1258 <pre><code>$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1</code></pre>
1259 </div></div>
1260 </div>
1261 </div>
1262 </div>
1263 <div class="sect1">
1264 <h2 id="_date_formats">DATE FORMATS</h2>
1265 <div class="sectionbody">
1266 <div class="paragraph"><p>The <code>GIT_AUTHOR_DATE</code> and <code>GIT_COMMITTER_DATE</code> environment variables
1267 support the following date formats:</p></div>
1268 <div class="dlist"><dl>
1269 <dt class="hdlist1">
1270 Git internal format
1271 </dt>
1272 <dd>
1273 <p>
1274         It is <code>&lt;unix-timestamp&gt; &lt;time-zone-offset&gt;</code>, where
1275         <code>&lt;unix-timestamp&gt;</code> is the number of seconds since the UNIX epoch.
1276         <code>&lt;time-zone-offset&gt;</code> is a positive or negative offset from UTC.
1277         For example CET (which is 1 hour ahead of UTC) is <code>+0100</code>.
1278 </p>
1279 </dd>
1280 <dt class="hdlist1">
1281 RFC 2822
1282 </dt>
1283 <dd>
1284 <p>
1285         The standard email format as described by RFC 2822, for example
1286         <code>Thu, 07 Apr 2005 22:13:13 +0200</code>.
1287 </p>
1288 </dd>
1289 <dt class="hdlist1">
1290 ISO 8601
1291 </dt>
1292 <dd>
1293 <p>
1294         Time and date specified by the ISO 8601 standard, for example
1295         <code>2005-04-07T22:13:13</code>. The parser accepts a space instead of the
1296         <code>T</code> character as well. Fractional parts of a second will be ignored,
1297         for example <code>2005-04-07T22:13:13.019</code> will be treated as
1298         <code>2005-04-07T22:13:13</code>.
1299 </p>
1300 <div class="admonitionblock">
1301 <table><tr>
1302 <td class="icon">
1303 <div class="title">Note</div>
1304 </td>
1305 <td class="content">In addition, the date part is accepted in the following formats:
1306 <code>YYYY.MM.DD</code>, <code>MM/DD/YYYY</code> and <code>DD.MM.YYYY</code>.</td>
1307 </tr></table>
1308 </div>
1309 </dd>
1310 </dl></div>
1311 </div>
1312 </div>
1313 <div class="sect1">
1314 <h2 id="_notes">NOTES</h2>
1315 <div class="sectionbody">
1316 <div class="paragraph"><p>When combining multiple <code>--contains</code> and <code>--no-contains</code> filters, only
1317 references that contain at least one of the <code>--contains</code> commits and
1318 contain none of the <code>--no-contains</code> commits are shown.</p></div>
1319 <div class="paragraph"><p>When combining multiple <code>--merged</code> and <code>--no-merged</code> filters, only
1320 references that are reachable from at least one of the <code>--merged</code>
1321 commits and from none of the <code>--no-merged</code> commits are shown.</p></div>
1322 </div>
1323 </div>
1324 <div class="sect1">
1325 <h2 id="_see_also">SEE ALSO</h2>
1326 <div class="sectionbody">
1327 <div class="paragraph"><p><a href="git-check-ref-format.html">git-check-ref-format(1)</a>.
1328 <a href="git-config.html">git-config(1)</a>.</p></div>
1329 </div>
1330 </div>
1331 <div class="sect1">
1332 <h2 id="_git">GIT</h2>
1333 <div class="sectionbody">
1334 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1335 </div>
1336 </div>
1337 </div>
1338 <div id="footnotes"><hr /></div>
1339 <div id="footer">
1340 <div id="footer-text">
1341 Last updated
1342  2022-10-29 03:53:56 JST
1343 </div>
1344 </div>
1345 </body>
1346 </html>