git-interpret-trailers.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-interpret-trailers(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-interpret-trailers(1) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>git-interpret-trailers -
 743    Add or parse structured information in commit messages
 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 interpret-trailers</em> [--in-place] [--trim-empty]
 753                         [(--trailer &lt;token&gt;[(=|:)&lt;value&gt;])&#8230;]
 754                         [--parse] [&lt;file&gt;&#8230;]</pre>
 755 <div class="attribution">
 756 </div></div>
 757 </div>
 758 </div>
 759 <div class="sect1">
 760 <h2 id="_description">DESCRIPTION</h2>
 761 <div class="sectionbody">
 762 <div class="paragraph"><p>Add or parse <em>trailer</em> lines that look similar to RFC 822 e-mail
 763 headers, at the end of the otherwise free-form part of a commit
 764 message. For example, in the following commit message</p></div>
 765 <div class="listingblock">
 766 <div class="content">
 767 <pre><code>subject
 768
 769 Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 770
 771 Signed-off-by: Alice &lt;alice@example.com&gt;
 772 Signed-off-by: Bob &lt;bob@example.com&gt;</code></pre>
 773 </div></div>
 774 <div class="paragraph"><p>the last two lines starting with "Signed-off-by" are trailers.</p></div>
 775 <div class="paragraph"><p>This command reads commit messages from either the
 776 &lt;file&gt; arguments or the standard input if no &lt;file&gt; is specified.
 777 If <code>--parse</code> is specified, the output consists of the parsed trailers.
 778 Otherwise, this command applies the arguments passed using the
 779 <code>--trailer</code> option, if any, to each input file. The result is emitted on the
 780 standard output.</p></div>
 781 <div class="paragraph"><p>This command can also operate on the output of <a href="git-format-patch.html">git-format-patch(1)</a>,
 782 which is more elaborate than a plain commit message. Namely, such output
 783 includes a commit message (as above), a "---" divider line, and a patch part.
 784 For these inputs, the divider and patch parts are not modified by
 785 this command and are emitted as is on the output, unless
 786 <code>--no-divider</code> is specified.</p></div>
 787 <div class="paragraph"><p>Some configuration variables control the way the <code>--trailer</code> arguments
 788 are applied to each input and the way any existing trailer in
 789 the input is changed. They also make it possible to
 790 automatically add some trailers.</p></div>
 791 <div class="paragraph"><p>By default, a <em>&lt;token&gt;=&lt;value&gt;</em> or <em>&lt;token&gt;:&lt;value&gt;</em> argument given
 792 using <code>--trailer</code> will be appended after the existing trailers only if
 793 the last trailer has a different (&lt;token&gt;, &lt;value&gt;) pair (or if there
 794 is no existing trailer). The &lt;token&gt; and &lt;value&gt; parts will be trimmed
 795 to remove starting and trailing whitespace, and the resulting trimmed
 796 &lt;token&gt; and &lt;value&gt; will appear in the output like this:</p></div>
 797 <div class="listingblock">
 798 <div class="content">
 799 <pre><code>token: value</code></pre>
 800 </div></div>
 801 <div class="paragraph"><p>This means that the trimmed &lt;token&gt; and &lt;value&gt; will be separated by
 802 <code>': '</code> (one colon followed by one space). For convenience, the &lt;token&gt; can be a
 803 shortened string key (e.g., "sign") instead of the full string which should
 804 appear before the separator on the output (e.g., "Signed-off-by"). This can be
 805 configured using the <em>trailer.&lt;token&gt;.key</em> configuration variable.</p></div>
 806 <div class="paragraph"><p>By default the new trailer will appear at the end of all the existing
 807 trailers. If there is no existing trailer, the new trailer will appear
 808 at the end of the input. A blank line will be added before the new
 809 trailer if there isn&#8217;t one already.</p></div>
 810 <div class="paragraph"><p>Existing trailers are extracted from the input by looking for
 811 a group of one or more lines that (i) is all trailers, or (ii) contains at
 812 least one Git-generated or user-configured trailer and consists of at
 813 least 25% trailers.
 814 The group must be preceded by one or more empty (or whitespace-only) lines.
 815 The group must either be at the end of the input or be the last
 816 non-whitespace lines before a line that starts with <em>---</em> (followed by a
 817 space or the end of the line).</p></div>
 818 <div class="paragraph"><p>When reading trailers, there can be no whitespace before or inside the
 819 &lt;token&gt;, but any number of regular space and tab characters are allowed
 820 between the &lt;token&gt; and the separator. There can be whitespaces before,
 821 inside or after the &lt;value&gt;. The &lt;value&gt; may be split over multiple lines
 822 with each subsequent line starting with at least one whitespace, like
 823 the "folding" in RFC 822. Example:</p></div>
 824 <div class="listingblock">
 825 <div class="content">
 826 <pre><code>token: This is a very long value, with spaces and
 827   newlines in it.</code></pre>
 828 </div></div>
 829 <div class="paragraph"><p>Note that trailers do not follow (nor are they intended to follow) many of the
 830 rules for RFC 822 headers. For example they do not follow the encoding rule.</p></div>
 831 </div>
 832 </div>
 833 <div class="sect1">
 834 <h2 id="_options">OPTIONS</h2>
 835 <div class="sectionbody">
 836 <div class="dlist"><dl>
 837 <dt class="hdlist1">
 838 --in-place
 839 </dt>
 840 <dd>
 841 <p>
 842         Edit the files in place.
 843 </p>
 844 </dd>
 845 <dt class="hdlist1">
 846 --trim-empty
 847 </dt>
 848 <dd>
 849 <p>
 850         If the &lt;value&gt; part of any trailer contains only whitespace,
 851         the whole trailer will be removed from the output.
 852         This applies to existing trailers as well as new trailers.
 853 </p>
 854 </dd>
 855 <dt class="hdlist1">
 856 --trailer &lt;token&gt;[(=|:)&lt;value&gt;]
 857 </dt>
 858 <dd>
 859 <p>
 860         Specify a (&lt;token&gt;, &lt;value&gt;) pair that should be applied as a
 861         trailer to the inputs. See the description of this
 862         command.
 863 </p>
 864 </dd>
 865 <dt class="hdlist1">
 866 --where &lt;placement&gt;
 867 </dt>
 868 <dt class="hdlist1">
 869 --no-where
 870 </dt>
 871 <dd>
 872 <p>
 873         Specify where all new trailers will be added.  A setting
 874         provided with <em>--where</em> overrides all configuration variables
 875         and applies to all <em>--trailer</em> options until the next occurrence of
 876         <em>--where</em> or <em>--no-where</em>. Possible values are <code>after</code>, <code>before</code>,
 877         <code>end</code> or <code>start</code>.
 878 </p>
 879 </dd>
 880 <dt class="hdlist1">
 881 --if-exists &lt;action&gt;
 882 </dt>
 883 <dt class="hdlist1">
 884 --no-if-exists
 885 </dt>
 886 <dd>
 887 <p>
 888         Specify what action will be performed when there is already at
 889         least one trailer with the same &lt;token&gt; in the input.  A setting
 890         provided with <em>--if-exists</em> overrides all configuration variables
 891         and applies to all <em>--trailer</em> options until the next occurrence of
 892         <em>--if-exists</em> or <em>--no-if-exists</em>. Possible actions are <code>addIfDifferent</code>,
 893         <code>addIfDifferentNeighbor</code>, <code>add</code>, <code>replace</code> and <code>doNothing</code>.
 894 </p>
 895 </dd>
 896 <dt class="hdlist1">
 897 --if-missing &lt;action&gt;
 898 </dt>
 899 <dt class="hdlist1">
 900 --no-if-missing
 901 </dt>
 902 <dd>
 903 <p>
 904         Specify what action will be performed when there is no other
 905         trailer with the same &lt;token&gt; in the input.  A setting
 906         provided with <em>--if-missing</em> overrides all configuration variables
 907         and applies to all <em>--trailer</em> options until the next occurrence of
 908         <em>--if-missing</em> or <em>--no-if-missing</em>. Possible actions are <code>doNothing</code>
 909         or <code>add</code>.
 910 </p>
 911 </dd>
 912 <dt class="hdlist1">
 913 --only-trailers
 914 </dt>
 915 <dd>
 916 <p>
 917         Output only the trailers, not any other parts of the input.
 918 </p>
 919 </dd>
 920 <dt class="hdlist1">
 921 --only-input
 922 </dt>
 923 <dd>
 924 <p>
 925         Output only trailers that exist in the input; do not add any
 926         from the command-line or by following configured <code>trailer.*</code>
 927         rules.
 928 </p>
 929 </dd>
 930 <dt class="hdlist1">
 931 --unfold
 932 </dt>
 933 <dd>
 934 <p>
 935         Remove any whitespace-continuation in trailers, so that each
 936         trailer appears on a line by itself with its full content.
 937 </p>
 938 </dd>
 939 <dt class="hdlist1">
 940 --parse
 941 </dt>
 942 <dd>
 943 <p>
 944         A convenience alias for <code>--only-trailers --only-input
 945         --unfold</code>.
 946 </p>
 947 </dd>
 948 <dt class="hdlist1">
 949 --no-divider
 950 </dt>
 951 <dd>
 952 <p>
 953         Do not treat <code>---</code> as the end of the commit message. Use this
 954         when you know your input contains just the commit message itself
 955         (and not an email or the output of <code>git format-patch</code>).
 956 </p>
 957 </dd>
 958 </dl></div>
 959 </div>
 960 </div>
 961 <div class="sect1">
 962 <h2 id="_configuration_variables">CONFIGURATION VARIABLES</h2>
 963 <div class="sectionbody">
 964 <div class="dlist"><dl>
 965 <dt class="hdlist1">
 966 trailer.separators
 967 </dt>
 968 <dd>
 969 <p>
 970         This option tells which characters are recognized as trailer
 971         separators. By default only <em>:</em> is recognized as a trailer
 972         separator, except that <em>=</em> is always accepted on the command
 973         line for compatibility with other git commands.
 974 </p>
 975 <div class="paragraph"><p>The first character given by this option will be the default character
 976 used when another separator is not specified in the config for this
 977 trailer.</p></div>
 978 <div class="paragraph"><p>For example, if the value for this option is "%=$", then only lines
 979 using the format <em>&lt;token&gt;&lt;sep&gt;&lt;value&gt;</em> with &lt;sep&gt; containing <em>%</em>, <em>=</em>
 980 or <em>$</em> and then spaces will be considered trailers. And <em>%</em> will be
 981 the default separator used, so by default trailers will appear like:
 982 <em>&lt;token&gt;% &lt;value&gt;</em> (one percent sign and one space will appear between
 983 the token and the value).</p></div>
 984 </dd>
 985 <dt class="hdlist1">
 986 trailer.where
 987 </dt>
 988 <dd>
 989 <p>
 990         This option tells where a new trailer will be added.
 991 </p>
 992 <div class="paragraph"><p>This can be <code>end</code>, which is the default, <code>start</code>, <code>after</code> or <code>before</code>.</p></div>
 993 <div class="paragraph"><p>If it is <code>end</code>, then each new trailer will appear at the end of the
 994 existing trailers.</p></div>
 995 <div class="paragraph"><p>If it is <code>start</code>, then each new trailer will appear at the start,
 996 instead of the end, of the existing trailers.</p></div>
 997 <div class="paragraph"><p>If it is <code>after</code>, then each new trailer will appear just after the
 998 last trailer with the same &lt;token&gt;.</p></div>
 999 <div class="paragraph"><p>If it is <code>before</code>, then each new trailer will appear just before the
1000 first trailer with the same &lt;token&gt;.</p></div>
1001 </dd>
1002 <dt class="hdlist1">
1003 trailer.ifexists
1004 </dt>
1005 <dd>
1006 <p>
1007         This option makes it possible to choose what action will be
1008         performed when there is already at least one trailer with the
1009         same &lt;token&gt; in the input.
1010 </p>
1011 <div class="paragraph"><p>The valid values for this option are: <code>addIfDifferentNeighbor</code> (this
1012 is the default), <code>addIfDifferent</code>, <code>add</code>, <code>replace</code> or <code>doNothing</code>.</p></div>
1013 <div class="paragraph"><p>With <code>addIfDifferentNeighbor</code>, a new trailer will be added only if no
1014 trailer with the same (&lt;token&gt;, &lt;value&gt;) pair is above or below the line
1015 where the new trailer will be added.</p></div>
1016 <div class="paragraph"><p>With <code>addIfDifferent</code>, a new trailer will be added only if no trailer
1017 with the same (&lt;token&gt;, &lt;value&gt;) pair is already in the input.</p></div>
1018 <div class="paragraph"><p>With <code>add</code>, a new trailer will be added, even if some trailers with
1019 the same (&lt;token&gt;, &lt;value&gt;) pair are already in the input.</p></div>
1020 <div class="paragraph"><p>With <code>replace</code>, an existing trailer with the same &lt;token&gt; will be
1021 deleted and the new trailer will be added. The deleted trailer will be
1022 the closest one (with the same &lt;token&gt;) to the place where the new one
1023 will be added.</p></div>
1024 <div class="paragraph"><p>With <code>doNothing</code>, nothing will be done; that is no new trailer will be
1025 added if there is already one with the same &lt;token&gt; in the input.</p></div>
1026 </dd>
1027 <dt class="hdlist1">
1028 trailer.ifmissing
1029 </dt>
1030 <dd>
1031 <p>
1032         This option makes it possible to choose what action will be
1033         performed when there is not yet any trailer with the same
1034         &lt;token&gt; in the input.
1035 </p>
1036 <div class="paragraph"><p>The valid values for this option are: <code>add</code> (this is the default) and
1037 <code>doNothing</code>.</p></div>
1038 <div class="paragraph"><p>With <code>add</code>, a new trailer will be added.</p></div>
1039 <div class="paragraph"><p>With <code>doNothing</code>, nothing will be done.</p></div>
1040 </dd>
1041 <dt class="hdlist1">
1042 trailer.&lt;token&gt;.key
1043 </dt>
1044 <dd>
1045 <p>
1046         This <code>key</code> will be used instead of &lt;token&gt; in the trailer. At
1047         the end of this key, a separator can appear and then some
1048         space characters. By default the only valid separator is <em>:</em>,
1049         but this can be changed using the <code>trailer.separators</code> config
1050         variable.
1051 </p>
1052 <div class="paragraph"><p>If there is a separator, then the key will be used instead of both the
1053 &lt;token&gt; and the default separator when adding the trailer.</p></div>
1054 </dd>
1055 <dt class="hdlist1">
1056 trailer.&lt;token&gt;.where
1057 </dt>
1058 <dd>
1059 <p>
1060         This option takes the same values as the <em>trailer.where</em>
1061         configuration variable and it overrides what is specified by
1062         that option for trailers with the specified &lt;token&gt;.
1063 </p>
1064 </dd>
1065 <dt class="hdlist1">
1066 trailer.&lt;token&gt;.ifexists
1067 </dt>
1068 <dd>
1069 <p>
1070         This option takes the same values as the <em>trailer.ifexists</em>
1071         configuration variable and it overrides what is specified by
1072         that option for trailers with the specified &lt;token&gt;.
1073 </p>
1074 </dd>
1075 <dt class="hdlist1">
1076 trailer.&lt;token&gt;.ifmissing
1077 </dt>
1078 <dd>
1079 <p>
1080         This option takes the same values as the <em>trailer.ifmissing</em>
1081         configuration variable and it overrides what is specified by
1082         that option for trailers with the specified &lt;token&gt;.
1083 </p>
1084 </dd>
1085 <dt class="hdlist1">
1086 trailer.&lt;token&gt;.command
1087 </dt>
1088 <dd>
1089 <p>
1090         Deprecated in favor of <em>trailer.&lt;token&gt;.cmd</em>.
1091         This option behaves in the same way as <em>trailer.&lt;token&gt;.cmd</em>, except
1092         that it doesn&#8217;t pass anything as argument to the specified command.
1093         Instead the first occurrence of substring $ARG is replaced by the
1094         &lt;value&gt; that would be passed as argument.
1095 </p>
1096 <div class="paragraph"><p>Note that $ARG in the user&#8217;s command is
1097 only replaced once and that the original way of replacing $ARG is not safe.</p></div>
1098 <div class="paragraph"><p>When both <em>trailer.&lt;token&gt;.cmd</em> and <em>trailer.&lt;token&gt;.command</em> are given
1099 for the same &lt;token&gt;, <em>trailer.&lt;token&gt;.cmd</em> is used and
1100 <em>trailer.&lt;token&gt;.command</em> is ignored.</p></div>
1101 </dd>
1102 <dt class="hdlist1">
1103 trailer.&lt;token&gt;.cmd
1104 </dt>
1105 <dd>
1106 <p>
1107         This option can be used to specify a shell command that will be called
1108         once to automatically add a trailer with the specified &lt;token&gt;, and then
1109         called each time a <em>--trailer &lt;token&gt;=&lt;value&gt;</em> argument is specified to
1110         modify the &lt;value&gt; of the trailer that this option would produce.
1111 </p>
1112 <div class="paragraph"><p>When the specified command is first called to add a trailer
1113 with the specified &lt;token&gt;, the behavior is as if a special
1114 <em>--trailer &lt;token&gt;=&lt;value&gt;</em> argument was added at the beginning
1115 of the "git interpret-trailers" command, where &lt;value&gt;
1116 is taken to be the standard output of the command with any
1117 leading and trailing whitespace trimmed off.</p></div>
1118 <div class="paragraph"><p>If some <em>--trailer &lt;token&gt;=&lt;value&gt;</em> arguments are also passed
1119 on the command line, the command is called again once for each
1120 of these arguments with the same &lt;token&gt;. And the &lt;value&gt; part
1121 of these arguments, if any, will be passed to the command as its
1122 first argument. This way the command can produce a &lt;value&gt; computed
1123 from the &lt;value&gt; passed in the <em>--trailer &lt;token&gt;=&lt;value&gt;</em> argument.</p></div>
1124 </dd>
1125 </dl></div>
1126 </div>
1127 </div>
1128 <div class="sect1">
1129 <h2 id="_examples">EXAMPLES</h2>
1130 <div class="sectionbody">
1131 <div class="ulist"><ul>
1132 <li>
1133 <p>
1134 Configure a <em>sign</em> trailer with a <em>Signed-off-by</em> key, and then
1135   add two of these trailers to a commit message file:
1136 </p>
1137 <div class="listingblock">
1138 <div class="content">
1139 <pre><code>$ git config trailer.sign.key "Signed-off-by"
1140 $ cat msg.txt
1141 subject
1142
1143 body text
1144 $ git interpret-trailers --trailer 'sign: Alice &lt;alice@example.com&gt;' --trailer 'sign: Bob &lt;bob@example.com&gt;' &lt;msg.txt
1145 subject
1146
1147 body text
1148
1149 Signed-off-by: Alice &lt;alice@example.com&gt;
1150 Signed-off-by: Bob &lt;bob@example.com&gt;</code></pre>
1151 </div></div>
1152 </li>
1153 <li>
1154 <p>
1155 Use the <code>--in-place</code> option to edit a commit message file in place:
1156 </p>
1157 <div class="listingblock">
1158 <div class="content">
1159 <pre><code>$ cat msg.txt
1160 subject
1161
1162 body text
1163
1164 Signed-off-by: Bob &lt;bob@example.com&gt;
1165 $ git interpret-trailers --trailer 'Acked-by: Alice &lt;alice@example.com&gt;' --in-place msg.txt
1166 $ cat msg.txt
1167 subject
1168
1169 body text
1170
1171 Signed-off-by: Bob &lt;bob@example.com&gt;
1172 Acked-by: Alice &lt;alice@example.com&gt;</code></pre>
1173 </div></div>
1174 </li>
1175 <li>
1176 <p>
1177 Extract the last commit as a patch, and add a <em>Cc</em> and a
1178   <em>Reviewed-by</em> trailer to it:
1179 </p>
1180 <div class="listingblock">
1181 <div class="content">
1182 <pre><code>$ git format-patch -1
1183 0001-foo.patch
1184 $ git interpret-trailers --trailer 'Cc: Alice &lt;alice@example.com&gt;' --trailer 'Reviewed-by: Bob &lt;bob@example.com&gt;' 0001-foo.patch &gt;0001-bar.patch</code></pre>
1185 </div></div>
1186 </li>
1187 <li>
1188 <p>
1189 Configure a <em>sign</em> trailer with a command to automatically add a
1190   'Signed-off-by: ' with the author information only if there is no
1191   'Signed-off-by: ' already, and show how it works:
1192 </p>
1193 <div class="listingblock">
1194 <div class="content">
1195 <pre><code>$ cat msg1.txt
1196 subject
1197
1198 body text
1199 $ git config trailer.sign.key "Signed-off-by: "
1200 $ git config trailer.sign.ifmissing add
1201 $ git config trailer.sign.ifexists doNothing
1202 $ git config trailer.sign.cmd 'echo "$(git config user.name) &lt;$(git config user.email)&gt;"'
1203 $ git interpret-trailers --trailer sign &lt;msg1.txt
1204 subject
1205
1206 body text
1207
1208 Signed-off-by: Bob &lt;bob@example.com&gt;
1209 $ cat msg2.txt
1210 subject
1211
1212 body text
1213
1214 Signed-off-by: Alice &lt;alice@example.com&gt;
1215 $ git interpret-trailers --trailer sign &lt;msg2.txt
1216 subject
1217
1218 body text
1219
1220 Signed-off-by: Alice &lt;alice@example.com&gt;</code></pre>
1221 </div></div>
1222 </li>
1223 <li>
1224 <p>
1225 Configure a <em>fix</em> trailer with a key that contains a <em>#</em> and no
1226   space after this character, and show how it works:
1227 </p>
1228 <div class="listingblock">
1229 <div class="content">
1230 <pre><code>$ git config trailer.separators ":#"
1231 $ git config trailer.fix.key "Fix #"
1232 $ echo "subject" | git interpret-trailers --trailer fix=42
1233 subject
1234
1235 Fix #42</code></pre>
1236 </div></div>
1237 </li>
1238 <li>
1239 <p>
1240 Configure a <em>help</em> trailer with a cmd use a script <code>glog-find-author</code>
1241   which search specified author identity from git log in git repository
1242   and show how it works:
1243 </p>
1244 <div class="listingblock">
1245 <div class="content">
1246 <pre><code>$ cat ~/bin/glog-find-author
1247 #!/bin/sh
1248 test -n "$1" &amp;&amp; git log --author="$1" --pretty="%an &lt;%ae&gt;" -1 || true
1249 $ cat msg.txt
1250 subject
1251
1252 body text
1253 $ git config trailer.help.key "Helped-by: "
1254 $ git config trailer.help.ifExists "addIfDifferentNeighbor"
1255 $ git config trailer.help.cmd "~/bin/glog-find-author"
1256 $ git interpret-trailers --trailer="help:Junio" --trailer="help:Couder" &lt;msg.txt
1257 subject
1258
1259 body text
1260
1261 Helped-by: Junio C Hamano &lt;gitster@pobox.com&gt;
1262 Helped-by: Christian Couder &lt;christian.couder@gmail.com&gt;</code></pre>
1263 </div></div>
1264 </li>
1265 <li>
1266 <p>
1267 Configure a <em>ref</em> trailer with a cmd use a script <code>glog-grep</code>
1268   to grep last relevant commit from git log in the git repository
1269   and show how it works:
1270 </p>
1271 <div class="listingblock">
1272 <div class="content">
1273 <pre><code>$ cat ~/bin/glog-grep
1274 #!/bin/sh
1275 test -n "$1" &amp;&amp; git log --grep "$1" --pretty=reference -1 || true
1276 $ cat msg.txt
1277 subject
1278
1279 body text
1280 $ git config trailer.ref.key "Reference-to: "
1281 $ git config trailer.ref.ifExists "replace"
1282 $ git config trailer.ref.cmd "~/bin/glog-grep"
1283 $ git interpret-trailers --trailer="ref:Add copyright notices." &lt;msg.txt
1284 subject
1285
1286 body text
1287
1288 Reference-to: 8bc9a0c769 (Add copyright notices., 2005-04-07)</code></pre>
1289 </div></div>
1290 </li>
1291 <li>
1292 <p>
1293 Configure a <em>see</em> trailer with a command to show the subject of a
1294   commit that is related, and show how it works:
1295 </p>
1296 <div class="listingblock">
1297 <div class="content">
1298 <pre><code>$ cat msg.txt
1299 subject
1300
1301 body text
1302
1303 see: HEAD~2
1304 $ cat ~/bin/glog-ref
1305 #!/bin/sh
1306 git log -1 --oneline --format="%h (%s)" --abbrev-commit --abbrev=14
1307 $ git config trailer.see.key "See-also: "
1308 $ git config trailer.see.ifExists "replace"
1309 $ git config trailer.see.ifMissing "doNothing"
1310 $ git config trailer.see.cmd "glog-ref"
1311 $ git interpret-trailers --trailer=see &lt;msg.txt
1312 subject
1313
1314 body text
1315
1316 See-also: fe3187489d69c4 (subject of related commit)</code></pre>
1317 </div></div>
1318 </li>
1319 <li>
1320 <p>
1321 Configure a commit template with some trailers with empty values
1322   (using sed to show and keep the trailing spaces at the end of the
1323   trailers), then configure a commit-msg hook that uses
1324   <em>git interpret-trailers</em> to remove trailers with empty values and
1325   to add a <em>git-version</em> trailer:
1326 </p>
1327 <div class="listingblock">
1328 <div class="content">
1329 <pre><code>$ cat temp.txt
1330 ***subject***
1331
1332 ***message***
1333
1334 Fixes: Z
1335 Cc: Z
1336 Reviewed-by: Z
1337 Signed-off-by: Z
1338 $ sed -e 's/ Z$/ /' temp.txt &gt; commit_template.txt
1339 $ git config commit.template commit_template.txt
1340 $ cat .git/hooks/commit-msg
1341 #!/bin/sh
1342 git interpret-trailers --trim-empty --trailer "git-version: \$(git describe)" "\$1" &gt; "\$1.new"
1343 mv "\$1.new" "\$1"
1344 $ chmod +x .git/hooks/commit-msg</code></pre>
1345 </div></div>
1346 </li>
1347 </ul></div>
1348 </div>
1349 </div>
1350 <div class="sect1">
1351 <h2 id="_see_also">SEE ALSO</h2>
1352 <div class="sectionbody">
1353 <div class="paragraph"><p><a href="git-commit.html">git-commit(1)</a>, <a href="git-format-patch.html">git-format-patch(1)</a>, <a href="git-config.html">git-config(1)</a></p></div>
1354 </div>
1355 </div>
1356 <div class="sect1">
1357 <h2 id="_git">GIT</h2>
1358 <div class="sectionbody">
1359 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1360 </div>
1361 </div>
1362 </div>
1363 <div id="footnotes"><hr /></div>
1364 <div id="footer">
1365 <div id="footer-text">
1366 Last updated
1367  2023-06-23 13:24:09 PDT
1368 </div>
1369 </div>
1370 </body>
1371 </html>