Autogenerated HTML docs for v2.45.1-204-gd8ab1
[git-htmldocs.git] / git-tag.html
blob0b229bbebe458b9507b8a1787612e99a85ce5574
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 */
12 /* Default font. */
13 body {
14 font-family: Georgia,serif;
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;
27 body {
28 margin: 1em 5% 1em 5%;
31 a {
32 color: blue;
33 text-decoration: underline;
35 a:visited {
36 color: fuchsia;
39 em {
40 font-style: italic;
41 color: navy;
44 strong {
45 font-weight: bold;
46 color: #083194;
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;
56 h1, h2, h3 {
57 border-bottom: 2px solid silver;
59 h2 {
60 padding-top: 0.5em;
62 h3 {
63 float: left;
65 h3 + * {
66 clear: left;
68 h5 {
69 font-size: 1.0em;
72 div.sectionbody {
73 margin-left: 0;
76 hr {
77 border: 1px solid silver;
80 p {
81 margin-top: 0.5em;
82 margin-bottom: 0.5em;
85 ul, ol, li > p {
86 margin-top: 0;
88 ul > li { color: #aaa; }
89 ul > li > * { color: black; }
91 .monospaced, code, pre {
92 font-family: "Courier New", Courier, monospace;
93 font-size: inherit;
94 color: navy;
95 padding: 0;
96 margin: 0;
98 pre {
99 white-space: pre-wrap;
102 #author {
103 color: #527bbd;
104 font-weight: bold;
105 font-size: 1.1em;
107 #email {
109 #revnumber, #revdate, #revremark {
112 #footer {
113 font-size: small;
114 border-top: 2px solid silver;
115 padding-top: 0.5em;
116 margin-top: 4.0em;
118 #footer-text {
119 float: left;
120 padding-bottom: 0.5em;
122 #footer-badges {
123 float: right;
124 padding-bottom: 0.5em;
127 #preamble {
128 margin-top: 1.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 {
134 margin-top: 1.0em;
135 margin-bottom: 1.5em;
137 div.admonitionblock {
138 margin-top: 2.0em;
139 margin-bottom: 2.0em;
140 margin-right: 10%;
141 color: #606060;
144 div.content { /* Block element content. */
145 padding: 0;
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;
156 div.title + * {
157 margin-top: 0;
160 td div.title:first-child {
161 margin-top: 0.0em;
163 div.content div.title:first-child {
164 margin-top: 0.0em;
166 div.content + div.title {
167 margin-top: 0.0em;
170 div.sidebarblock > div.content {
171 background: #ffffee;
172 border: 1px solid #dddddd;
173 border-left: 4px solid #f0f0f0;
174 padding: 0.5em;
177 div.listingblock > div.content {
178 border: 1px solid #dddddd;
179 border-left: 5px solid #f0f0f0;
180 background: #f8f8f8;
181 padding: 0.5em;
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;
192 div.quoteblock > div.attribution {
193 padding-top: 0.5em;
194 text-align: right;
197 div.verseblock > pre.content {
198 font-family: inherit;
199 font-size: inherit;
201 div.verseblock > div.attribution {
202 padding-top: 0.75em;
203 text-align: left;
205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
206 div.verseblock + div.attribution {
207 text-align: left;
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;
218 div.admonitionblock td.content {
219 padding-left: 0.5em;
220 border-left: 3px solid #dddddd;
223 div.exampleblock > div.content {
224 border-left: 3px solid #dddddd;
225 padding-left: 0.5em;
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; }
232 dl {
233 margin-top: 0.8em;
234 margin-bottom: 0.8em;
236 dt {
237 margin-top: 0.5em;
238 margin-bottom: 0;
239 font-style: normal;
240 color: navy;
242 dd > *:first-child {
243 margin-top: 0.1em;
246 ul, ol {
247 list-style-position: outside;
249 ol.arabic {
250 list-style-type: decimal;
252 ol.loweralpha {
253 list-style-type: lower-alpha;
255 ol.upperalpha {
256 list-style-type: upper-alpha;
258 ol.lowerroman {
259 list-style-type: lower-roman;
261 ol.upperroman {
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 {
268 margin-top: 0.1em;
269 margin-bottom: 0.1em;
272 tfoot {
273 font-weight: bold;
275 td > div.verse {
276 white-space: pre;
279 div.hdlist {
280 margin-top: 0.8em;
281 margin-bottom: 0.8em;
283 div.hdlist tr {
284 padding-bottom: 15px;
286 dt.hdlist1.strong, td.hdlist1.strong {
287 font-weight: bold;
289 td.hdlist1 {
290 vertical-align: top;
291 font-style: normal;
292 padding-right: 0.8em;
293 color: navy;
295 td.hdlist2 {
296 vertical-align: top;
298 div.hdlist.compact tr {
299 margin: 0;
300 padding-bottom: 0;
303 .comment {
304 background: yellow;
307 .footnote, .footnoteref {
308 font-size: 0.8em;
311 span.footnote, span.footnoteref {
312 vertical-align: super;
315 #footnotes {
316 margin: 20px 0 20px 0;
317 padding: 7px 0 0 0;
320 #footnotes div.footnote {
321 margin: 0 0 5px 0;
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;
334 div.colist td {
335 padding-right: 0.5em;
336 padding-bottom: 0.3em;
337 vertical-align: top;
339 div.colist td img {
340 margin-top: 0.3em;
343 @media print {
344 #footer-badges { display: none; }
347 #toc {
348 margin-bottom: 2.5em;
351 #toctitle {
352 color: #527bbd;
353 font-size: 1.1em;
354 font-weight: bold;
355 margin-top: 1.0em;
356 margin-bottom: 0.1em;
359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
360 margin-top: 0;
361 margin-bottom: 0;
363 div.toclevel2 {
364 margin-left: 2em;
365 font-size: 0.9em;
367 div.toclevel3 {
368 margin-left: 4em;
369 font-size: 0.9em;
371 div.toclevel4 {
372 margin-left: 6em;
373 font-size: 0.9em;
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; }
421 * xhtml11 specific
423 * */
425 div.tableblock {
426 margin-top: 1.0em;
427 margin-bottom: 1.5em;
429 div.tableblock > table {
430 border: 3px solid #527bbd;
432 thead, p.table.header {
433 font-weight: bold;
434 color: #527bbd;
436 p.table {
437 margin-top: 0;
439 /* Because the table frame attribute is overridden by CSS in most browsers. */
440 div.tableblock > table[frame="void"] {
441 border-style: none;
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;
454 * html5 specific
456 * */
458 table.tableblock {
459 margin-top: 1.0em;
460 margin-bottom: 1.5em;
462 thead, p.tableblock.header {
463 font-weight: bold;
464 color: #527bbd;
466 p.tableblock {
467 margin-top: 0;
469 table.tableblock {
470 border-width: 3px;
471 border-spacing: 0px;
472 border-style: solid;
473 border-color: #527bbd;
474 border-collapse: collapse;
476 th.tableblock, td.tableblock {
477 border-width: 1px;
478 padding: 4px;
479 border-style: solid;
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 {
496 text-align: left;
498 th.tableblock.halign-center, td.tableblock.halign-center {
499 text-align: center;
501 th.tableblock.halign-right, td.tableblock.halign-right {
502 text-align: right;
505 th.tableblock.valign-top, td.tableblock.valign-top {
506 vertical-align: 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;
517 * manpage specific
519 * */
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;
527 body.manpage h2 {
528 border-style: none;
530 body.manpage div.sectionbody {
531 margin-left: 3em;
534 @media print {
535 body.manpage div#toc { display: none; }
539 </style>
540 <script type="text/javascript">
541 /*<![CDATA[*/
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
552 * Version: 0.4
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 */
561 // toclevels = 1..4.
562 toc: function (toclevels) {
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);
572 return text;
575 function TocEntry(el, text, toclevel) {
576 this.element = el;
577 this.text = text;
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
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);
594 iterate(i);
598 iterate(el);
599 return result;
602 var toc = document.getElementById("toc");
603 if (!toc) {
604 return;
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);
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");
631 div.appendChild(a);
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.
650 var i;
651 var noteholder = document.getElementById("footnotes");
652 if (!noteholder) {
653 return;
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");
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);
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;
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>]";
708 install: function(toclevels) {
709 var timerId;
711 function reinstall() {
712 asciidoc.footnotes();
713 if (toclevels) {
714 asciidoc.toc(toclevels);
718 function reinstallAndRemoveTimer() {
719 clearInterval(timerId);
720 reinstall();
723 timerId = setInterval(reinstall, 500);
724 if (document.addEventListener)
725 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
726 else
727 window.onload = reinstallAndRemoveTimer;
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 [(--trailer &lt;token&gt;[(=|:)&lt;value&gt;])&#8230;]
754 &lt;tagname&gt; [&lt;commit&gt; | &lt;object&gt;]
755 <em>git tag</em> -d &lt;tagname&gt;&#8230;
756 <em>git tag</em> [-n[&lt;num&gt;]] -l [--contains &lt;commit&gt;] [--no-contains &lt;commit&gt;]
757 [--points-at &lt;object&gt;] [--column[=&lt;options&gt;] | --no-column]
758 [--create-reflog] [--sort=&lt;key&gt;] [--format=&lt;format&gt;]
759 [--merged &lt;commit&gt;] [--no-merged &lt;commit&gt;] [&lt;pattern&gt;&#8230;]
760 <em>git tag</em> -v [--format=&lt;format&gt;] &lt;tagname&gt;&#8230;</pre>
761 <div class="attribution">
762 </div></div>
763 </div>
764 </div>
765 <div class="sect1">
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 &lt;key-id&gt;</code> is passed, the command
772 creates a <em>tag</em> object, and requires a tag message. Unless
773 <code>-m &lt;msg&gt;</code> or <code>-F &lt;file&gt;</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 &lt;msg&gt;</code> or <code>-F &lt;file&gt;</code> or <code>--trailer &lt;token&gt;[=&lt;value&gt;]</code> is given
776 and <code>-a</code>, <code>-s</code>, and <code>-u &lt;key-id&gt;</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 &lt;key-id&gt;</code> is used. When <code>-u &lt;key-id&gt;</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
788 object).</p></div>
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>
793 </div>
794 </div>
795 <div class="sect1">
796 <h2 id="_options">OPTIONS</h2>
797 <div class="sectionbody">
798 <div class="dlist"><dl>
799 <dt class="hdlist1">
801 </dt>
802 <dt class="hdlist1">
803 --annotate
804 </dt>
805 <dd>
807 Make an unsigned, annotated tag object
808 </p>
809 </dd>
810 <dt class="hdlist1">
812 </dt>
813 <dt class="hdlist1">
814 --sign
815 </dt>
816 <dd>
818 Make a GPG-signed tag, using the default e-mail address&#8217;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>.
822 </p>
823 </dd>
824 <dt class="hdlist1">
825 --no-sign
826 </dt>
827 <dd>
829 Override <code>tag.gpgSign</code> configuration variable that is
830 set to force each and every tag to be signed.
831 </p>
832 </dd>
833 <dt class="hdlist1">
834 -u &lt;key-id&gt;
835 </dt>
836 <dt class="hdlist1">
837 --local-user=&lt;key-id&gt;
838 </dt>
839 <dd>
841 Make a GPG-signed tag, using the given key.
842 </p>
843 </dd>
844 <dt class="hdlist1">
846 </dt>
847 <dt class="hdlist1">
848 --force
849 </dt>
850 <dd>
852 Replace an existing tag with the given name (instead of failing)
853 </p>
854 </dd>
855 <dt class="hdlist1">
857 </dt>
858 <dt class="hdlist1">
859 --delete
860 </dt>
861 <dd>
863 Delete existing tags with the given names.
864 </p>
865 </dd>
866 <dt class="hdlist1">
868 </dt>
869 <dt class="hdlist1">
870 --verify
871 </dt>
872 <dd>
874 Verify the GPG signature of the given tag names.
875 </p>
876 </dd>
877 <dt class="hdlist1">
878 -n&lt;num&gt;
879 </dt>
880 <dd>
882 &lt;num&gt; specifies how many lines from the annotation, if any,
883 are printed when using -l. Implies <code>--list</code>.
884 </p>
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>
888 </dd>
889 <dt class="hdlist1">
891 </dt>
892 <dt class="hdlist1">
893 --list
894 </dt>
895 <dd>
897 List tags. With optional <code>&lt;pattern&gt;...</code>, e.g. <code>git tag --list
898 'v-*'</code>, list only the tags that match the pattern(s).
899 </p>
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>
906 </dd>
907 <dt class="hdlist1">
908 --sort=&lt;key&gt;
909 </dt>
910 <dd>
912 Sort based on the key given. Prefix <code>-</code> to sort in
913 descending order of the value. You may use the --sort=&lt;key&gt; 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>.
923 </p>
924 </dd>
925 <dt class="hdlist1">
926 --color[=&lt;when&gt;]
927 </dt>
928 <dd>
930 Respect any colors specified in the <code>--format</code> option. The
931 <code>&lt;when&gt;</code> field must be one of <code>always</code>, <code>never</code>, or <code>auto</code> (if
932 <code>&lt;when&gt;</code> is absent, behave as if <code>always</code> was given).
933 </p>
934 </dd>
935 <dt class="hdlist1">
937 </dt>
938 <dt class="hdlist1">
939 --ignore-case
940 </dt>
941 <dd>
943 Sorting and filtering tags are case insensitive.
944 </p>
945 </dd>
946 <dt class="hdlist1">
947 --omit-empty
948 </dt>
949 <dd>
951 Do not print a newline after formatted refs where the format expands
952 to the empty string.
953 </p>
954 </dd>
955 <dt class="hdlist1">
956 --column[=&lt;options&gt;]
957 </dt>
958 <dt class="hdlist1">
959 --no-column
960 </dt>
961 <dd>
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.
966 </p>
967 <div class="paragraph"><p>This option is only applicable when listing tags without annotation lines.</p></div>
968 </dd>
969 <dt class="hdlist1">
970 --contains [&lt;commit&gt;]
971 </dt>
972 <dd>
974 Only list tags which contain the specified commit (HEAD if not
975 specified). Implies <code>--list</code>.
976 </p>
977 </dd>
978 <dt class="hdlist1">
979 --no-contains [&lt;commit&gt;]
980 </dt>
981 <dd>
983 Only list tags which don&#8217;t contain the specified commit (HEAD if
984 not specified). Implies <code>--list</code>.
985 </p>
986 </dd>
987 <dt class="hdlist1">
988 --merged [&lt;commit&gt;]
989 </dt>
990 <dd>
992 Only list tags whose commits are reachable from the specified
993 commit (<code>HEAD</code> if not specified).
994 </p>
995 </dd>
996 <dt class="hdlist1">
997 --no-merged [&lt;commit&gt;]
998 </dt>
999 <dd>
1001 Only list tags whose commits are not reachable from the specified
1002 commit (<code>HEAD</code> if not specified).
1003 </p>
1004 </dd>
1005 <dt class="hdlist1">
1006 --points-at &lt;object&gt;
1007 </dt>
1008 <dd>
1010 Only list tags of the given object (HEAD if not
1011 specified). Implies <code>--list</code>.
1012 </p>
1013 </dd>
1014 <dt class="hdlist1">
1015 -m &lt;msg&gt;
1016 </dt>
1017 <dt class="hdlist1">
1018 --message=&lt;msg&gt;
1019 </dt>
1020 <dd>
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 &lt;key-id&gt;</code>
1026 is given.
1027 </p>
1028 </dd>
1029 <dt class="hdlist1">
1030 -F &lt;file&gt;
1031 </dt>
1032 <dt class="hdlist1">
1033 --file=&lt;file&gt;
1034 </dt>
1035 <dd>
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 &lt;key-id&gt;</code>
1040 is given.
1041 </p>
1042 </dd>
1043 <dt class="hdlist1">
1044 --trailer &lt;token&gt;[(=|:)&lt;value&gt;]
1045 </dt>
1046 <dd>
1048 Specify a (&lt;token&gt;, &lt;value&gt;) 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.
1057 </p>
1058 </dd>
1059 <dt class="hdlist1">
1061 </dt>
1062 <dt class="hdlist1">
1063 --edit
1064 </dt>
1065 <dd>
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.
1070 </p>
1071 </dd>
1072 <dt class="hdlist1">
1073 --cleanup=&lt;mode&gt;
1074 </dt>
1075 <dd>
1077 This option sets how the tag message is cleaned up.
1078 The <em>&lt;mode&gt;</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.
1082 </p>
1083 </dd>
1084 <dt class="hdlist1">
1085 --create-reflog
1086 </dt>
1087 <dd>
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>.
1094 </p>
1095 </dd>
1096 <dt class="hdlist1">
1097 --format=&lt;format&gt;
1098 </dt>
1099 <dd>
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>.
1105 </p>
1106 </dd>
1107 <dt class="hdlist1">
1108 &lt;tagname&gt;
1109 </dt>
1110 <dd>
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.
1116 </p>
1117 </dd>
1118 <dt class="hdlist1">
1119 &lt;commit&gt;
1120 </dt>
1121 <dt class="hdlist1">
1122 &lt;object&gt;
1123 </dt>
1124 <dd>
1126 The object that the new tag will refer to, usually a commit.
1127 Defaults to HEAD.
1128 </p>
1129 </dd>
1130 </dl></div>
1131 </div>
1132 </div>
1133 <div class="sect1">
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 &lt;your@email.address&gt;</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">
1142 <pre><code>[user]
1143 signingKey = &lt;gpg-key-id&gt;</code></pre>
1144 </div></div>
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>
1148 </div>
1149 </div>
1150 <div class="sect1">
1151 <h2 id="_discussion">DISCUSSION</h2>
1152 <div class="sectionbody">
1153 <div class="sect2">
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&#8217;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">
1163 <li>
1165 The sane thing.
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.
1171 </p>
1172 </li>
1173 <li>
1175 The insane thing.
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&#8217;t already published the old one.
1179 </p>
1180 </li>
1181 </ol></div>
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&#8217;t just make them overwrite the old
1185 one.</p></div>
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:
1200 git tag -d X
1201 git fetch origin tag X
1203 to get my updated tag.
1205 You can test which tag you have by doing
1207 git rev-parse X
1209 which should return 0123456789abcdef.. if you have the new version.
1211 Sorry for the inconvenience.</code></pre>
1212 </div></div>
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>
1216 </div>
1217 <div class="sect2">
1218 <h3 id="_on_automatic_following">On Automatic following</h3>
1219 <div class="paragraph"><p>If you are following somebody else&#8217;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&amp;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>
1239 </div></div>
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>
1244 </div></div>
1245 <div class="paragraph"><p>In such a case, you do not want to automatically follow the other
1246 person&#8217;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&#8217;s progress by
1268 having remote-tracking branches. Again, the heuristic to automatically
1269 follow such tags is a good thing.</p></div>
1270 </div>
1271 <div class="sect2">
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>
1285 </div></div>
1286 </div>
1287 </div>
1288 </div>
1289 <div class="sect1">
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">
1296 Git internal format
1297 </dt>
1298 <dd>
1300 It is <code>&lt;unix-timestamp&gt; &lt;time-zone-offset&gt;</code>, where
1301 <code>&lt;unix-timestamp&gt;</code> is the number of seconds since the UNIX epoch.
1302 <code>&lt;time-zone-offset&gt;</code> is a positive or negative offset from UTC.
1303 For example CET (which is 1 hour ahead of UTC) is <code>+0100</code>.
1304 </p>
1305 </dd>
1306 <dt class="hdlist1">
1307 RFC 2822
1308 </dt>
1309 <dd>
1311 The standard date format as described by RFC 2822, for example
1312 <code>Thu, 07 Apr 2005 22:13:13 +0200</code>.
1313 </p>
1314 </dd>
1315 <dt class="hdlist1">
1316 ISO 8601
1317 </dt>
1318 <dd>
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>.
1325 </p>
1326 <div class="admonitionblock">
1327 <table><tr>
1328 <td class="icon">
1329 <div class="title">Note</div>
1330 </td>
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>
1333 </tr></table>
1334 </div>
1335 </dd>
1336 </dl></div>
1337 </div>
1338 </div>
1339 <div class="sect1">
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>
1345 </dt>
1346 <dd>
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>.
1353 </p>
1354 </dd>
1355 </dl></div>
1356 </div>
1357 </div>
1358 <div class="sect1">
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>
1367 </div>
1368 </div>
1369 <div class="sect1">
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>
1374 </div>
1375 </div>
1376 <div class="sect1">
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>
1380 </div>
1381 </div>
1382 </div>
1383 <div id="footnotes"><hr /></div>
1384 <div id="footer">
1385 <div id="footer-text">
1386 Last updated
1387 2024-05-16 11:09:25 PDT
1388 </div>
1389 </div>
1390 </body>
1391 </html>