doc/source/en/TortoiseGit/git_doc/git-show.html.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-show(1)">\r
   5 <articleinfo>\r
   6     <title>git-show(1)</title>\r
   7         <indexterm>\r
   8                 <primary>git-show(1)</primary>\r
   9         </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-show - Show various types of objects</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <simpara><emphasis>git show</emphasis> [options] &lt;object&gt;&#8230;</simpara>\r
  18 </simplesect>\r
  19 <simplesect id="_description">\r
  20 <title>DESCRIPTION</title>\r
  21 <simpara>Shows one or more objects (blobs, trees, tags and commits).</simpara>\r
  22 <simpara>For commits it shows the log message and textual diff. It also\r
  23 presents the merge commit in a special format as produced by\r
  24 <emphasis>git-diff-tree --cc</emphasis>.</simpara>\r
  25 <simpara>For tags, it shows the tag message and the referenced objects.</simpara>\r
  26 <simpara>For trees, it shows the names (equivalent to <emphasis>git-ls-tree</emphasis>\r
  27 with --name-only).</simpara>\r
  28 <simpara>For plain blobs, it shows the plain contents.</simpara>\r
  29 <simpara>The command takes options applicable to the <emphasis>git-diff-tree</emphasis> command to\r
  30 control how the changes the commit introduces are shown.</simpara>\r
  31 <simpara>This manual page describes only the most frequently used options.</simpara>\r
  32 </simplesect>\r
  33 <simplesect id="_options">\r
  34 <title>OPTIONS</title>\r
  35 <variablelist>\r
  36 <varlistentry>\r
  37 <term>\r
  38 &lt;object&gt;&#8230;\r
  39 </term>\r
  40 <listitem>\r
  41 <simpara>\r
  42         The names of objects to show.\r
  43         For a more complete list of ways to spell object names, see\r
  44         "SPECIFYING REVISIONS" section in <xref linkend="git-rev-parse(1)"/>.\r
  45 </simpara>\r
  46 </listitem>\r
  47 </varlistentry>\r
  48 <varlistentry>\r
  49 <term>\r
  50 --pretty[=<emphasis>&lt;format&gt;</emphasis>]\r
  51 </term>\r
  52 <listitem>\r
  53 <simpara>\r
  54         Pretty-print the contents of the commit logs in a given format,\r
  55         where <emphasis>&lt;format&gt;</emphasis> can be one of <emphasis>oneline</emphasis>, <emphasis>short</emphasis>, <emphasis>medium</emphasis>,\r
  56         <emphasis>full</emphasis>, <emphasis>fuller</emphasis>, <emphasis>email</emphasis>, <emphasis>raw</emphasis> and <emphasis>format:&lt;string&gt;</emphasis>.\r
  57         When omitted, the format defaults to <emphasis>medium</emphasis>.\r
  58 </simpara>\r
  59 <simpara>Note: you can specify the default pretty format in the repository\r
  60 configuration (see <xref linkend="git-config(1)"/>).</simpara>\r
  61 </listitem>\r
  62 </varlistentry>\r
  63 <varlistentry>\r
  64 <term>\r
  65 --abbrev-commit\r
  66 </term>\r
  67 <listitem>\r
  68 <simpara>\r
  69         Instead of showing the full 40-byte hexadecimal commit object\r
  70         name, show only a partial prefix.  Non default number of\r
  71         digits can be specified with "--abbrev=&lt;n&gt;" (which also modifies\r
  72         diff output, if it is displayed).\r
  73 </simpara>\r
  74 <simpara>This should make "--pretty=oneline" a whole lot more readable for\r
  75 people using 80-column terminals.</simpara>\r
  76 </listitem>\r
  77 </varlistentry>\r
  78 <varlistentry>\r
  79 <term>\r
  80 --encoding[=&lt;encoding&gt;]\r
  81 </term>\r
  82 <listitem>\r
  83 <simpara>\r
  84         The commit objects record the encoding used for the log message\r
  85         in their encoding header; this option can be used to tell the\r
  86         command to re-code the commit log message in the encoding\r
  87         preferred by the user.  For non plumbing commands this\r
  88         defaults to UTF-8.\r
  89 </simpara>\r
  90 </listitem>\r
  91 </varlistentry>\r
  92 </variablelist>\r
  93 </simplesect>\r
  94 <simplesect id="_pretty_formats">\r
  95 <title>PRETTY FORMATS</title>\r
  96 <simpara>If the commit is a merge, and if the pretty-format\r
  97 is not <emphasis>oneline</emphasis>, <emphasis>email</emphasis> or <emphasis>raw</emphasis>, an additional line is\r
  98 inserted before the <emphasis>Author:</emphasis> line.  This line begins with\r
  99 "Merge: " and the sha1s of ancestral commits are printed,\r
 100 separated by spaces.  Note that the listed commits may not\r
 101 necessarily be the list of the <emphasis role="strong">direct</emphasis> parent commits if you\r
 102 have limited your view of history: for example, if you are\r
 103 only interested in changes related to a certain directory or\r
 104 file.</simpara>\r
 105 <simpara>Here are some additional details for each format:</simpara>\r
 106 <itemizedlist>\r
 107 <listitem>\r
 108 <simpara>\r
 109 <emphasis>oneline</emphasis>\r
 110 </simpara>\r
 111 <literallayout class="monospaced">&lt;sha1&gt; &lt;title line&gt;</literallayout>\r
 112 <simpara>This is designed to be as compact as possible.</simpara>\r
 113 </listitem>\r
 114 <listitem>\r
 115 <simpara>\r
 116 <emphasis>short</emphasis>\r
 117 </simpara>\r
 118 <literallayout class="monospaced">commit &lt;sha1&gt;\r
 119 Author: &lt;author&gt;</literallayout>\r
 120 <literallayout class="monospaced">&lt;title line&gt;</literallayout>\r
 121 </listitem>\r
 122 <listitem>\r
 123 <simpara>\r
 124 <emphasis>medium</emphasis>\r
 125 </simpara>\r
 126 <literallayout class="monospaced">commit &lt;sha1&gt;\r
 127 Author: &lt;author&gt;\r
 128 Date:   &lt;author date&gt;</literallayout>\r
 129 <literallayout class="monospaced">&lt;title line&gt;</literallayout>\r
 130 <literallayout class="monospaced">&lt;full commit message&gt;</literallayout>\r
 131 </listitem>\r
 132 <listitem>\r
 133 <simpara>\r
 134 <emphasis>full</emphasis>\r
 135 </simpara>\r
 136 <literallayout class="monospaced">commit &lt;sha1&gt;\r
 137 Author: &lt;author&gt;\r
 138 Commit: &lt;committer&gt;</literallayout>\r
 139 <literallayout class="monospaced">&lt;title line&gt;</literallayout>\r
 140 <literallayout class="monospaced">&lt;full commit message&gt;</literallayout>\r
 141 </listitem>\r
 142 <listitem>\r
 143 <simpara>\r
 144 <emphasis>fuller</emphasis>\r
 145 </simpara>\r
 146 <literallayout class="monospaced">commit &lt;sha1&gt;\r
 147 Author:     &lt;author&gt;\r
 148 AuthorDate: &lt;author date&gt;\r
 149 Commit:     &lt;committer&gt;\r
 150 CommitDate: &lt;committer date&gt;</literallayout>\r
 151 <literallayout class="monospaced">&lt;title line&gt;</literallayout>\r
 152 <literallayout class="monospaced">&lt;full commit message&gt;</literallayout>\r
 153 </listitem>\r
 154 <listitem>\r
 155 <simpara>\r
 156 <emphasis>email</emphasis>\r
 157 </simpara>\r
 158 <literallayout class="monospaced">From &lt;sha1&gt; &lt;date&gt;\r
 159 From: &lt;author&gt;\r
 160 Date: &lt;author date&gt;\r
 161 Subject: [PATCH] &lt;title line&gt;</literallayout>\r
 162 <literallayout class="monospaced">&lt;full commit message&gt;</literallayout>\r
 163 </listitem>\r
 164 <listitem>\r
 165 <simpara>\r
 166 <emphasis>raw</emphasis>\r
 167 </simpara>\r
 168 <simpara>The <emphasis>raw</emphasis> format shows the entire commit exactly as\r
 169 stored in the commit object.  Notably, the SHA1s are\r
 170 displayed in full, regardless of whether --abbrev or\r
 171 --no-abbrev are used, and <emphasis>parents</emphasis> information show the\r
 172 true parent commits, without taking grafts nor history\r
 173 simplification into account.</simpara>\r
 174 </listitem>\r
 175 <listitem>\r
 176 <simpara>\r
 177 <emphasis>format:</emphasis>\r
 178 </simpara>\r
 179 <simpara>The <emphasis>format:</emphasis> format allows you to specify which information\r
 180 you want to show. It works a little bit like printf format,\r
 181 with the notable exception that you get a newline with <emphasis>%n</emphasis>\r
 182 instead of <emphasis>\n</emphasis>.</simpara>\r
 183 <simpara>E.g, <emphasis>format:"The author of %h was %an, %ar%nThe title was &gt;&gt;%s&lt;&lt;%n"</emphasis>\r
 184 would show something like this:</simpara>\r
 185 <literallayout>The author of fe6e0ee was Junio C Hamano, 23 hours ago\r
 186 The title was &gt;&gt;t4119: test autocomputing -p&lt;n&gt; for traditional diff input.&lt;&lt;</literallayout>\r
 187 <simpara>The placeholders are:</simpara>\r
 188 <itemizedlist>\r
 189 <listitem>\r
 190 <simpara>\r
 191 <emphasis>%H</emphasis>: commit hash\r
 192 </simpara>\r
 193 </listitem>\r
 194 <listitem>\r
 195 <simpara>\r
 196 <emphasis>%h</emphasis>: abbreviated commit hash\r
 197 </simpara>\r
 198 </listitem>\r
 199 <listitem>\r
 200 <simpara>\r
 201 <emphasis>%T</emphasis>: tree hash\r
 202 </simpara>\r
 203 </listitem>\r
 204 <listitem>\r
 205 <simpara>\r
 206 <emphasis>%t</emphasis>: abbreviated tree hash\r
 207 </simpara>\r
 208 </listitem>\r
 209 <listitem>\r
 210 <simpara>\r
 211 <emphasis>%P</emphasis>: parent hashes\r
 212 </simpara>\r
 213 </listitem>\r
 214 <listitem>\r
 215 <simpara>\r
 216 <emphasis>%p</emphasis>: abbreviated parent hashes\r
 217 </simpara>\r
 218 </listitem>\r
 219 <listitem>\r
 220 <simpara>\r
 221 <emphasis>%an</emphasis>: author name\r
 222 </simpara>\r
 223 </listitem>\r
 224 <listitem>\r
 225 <simpara>\r
 226 <emphasis>%aN</emphasis>: author name (respecting .mailmap)\r
 227 </simpara>\r
 228 </listitem>\r
 229 <listitem>\r
 230 <simpara>\r
 231 <emphasis>%ae</emphasis>: author email\r
 232 </simpara>\r
 233 </listitem>\r
 234 <listitem>\r
 235 <simpara>\r
 236 <emphasis>%aE</emphasis>: author email (respecting .mailmap)\r
 237 </simpara>\r
 238 </listitem>\r
 239 <listitem>\r
 240 <simpara>\r
 241 <emphasis>%ad</emphasis>: author date (format respects --date= option)\r
 242 </simpara>\r
 243 </listitem>\r
 244 <listitem>\r
 245 <simpara>\r
 246 <emphasis>%aD</emphasis>: author date, RFC2822 style\r
 247 </simpara>\r
 248 </listitem>\r
 249 <listitem>\r
 250 <simpara>\r
 251 <emphasis>%ar</emphasis>: author date, relative\r
 252 </simpara>\r
 253 </listitem>\r
 254 <listitem>\r
 255 <simpara>\r
 256 <emphasis>%at</emphasis>: author date, UNIX timestamp\r
 257 </simpara>\r
 258 </listitem>\r
 259 <listitem>\r
 260 <simpara>\r
 261 <emphasis>%ai</emphasis>: author date, ISO 8601 format\r
 262 </simpara>\r
 263 </listitem>\r
 264 <listitem>\r
 265 <simpara>\r
 266 <emphasis>%cn</emphasis>: committer name\r
 267 </simpara>\r
 268 </listitem>\r
 269 <listitem>\r
 270 <simpara>\r
 271 <emphasis>%cN</emphasis>: committer name (respecting .mailmap)\r
 272 </simpara>\r
 273 </listitem>\r
 274 <listitem>\r
 275 <simpara>\r
 276 <emphasis>%ce</emphasis>: committer email\r
 277 </simpara>\r
 278 </listitem>\r
 279 <listitem>\r
 280 <simpara>\r
 281 <emphasis>%cE</emphasis>: committer email (respecting .mailmap)\r
 282 </simpara>\r
 283 </listitem>\r
 284 <listitem>\r
 285 <simpara>\r
 286 <emphasis>%cd</emphasis>: committer date\r
 287 </simpara>\r
 288 </listitem>\r
 289 <listitem>\r
 290 <simpara>\r
 291 <emphasis>%cD</emphasis>: committer date, RFC2822 style\r
 292 </simpara>\r
 293 </listitem>\r
 294 <listitem>\r
 295 <simpara>\r
 296 <emphasis>%cr</emphasis>: committer date, relative\r
 297 </simpara>\r
 298 </listitem>\r
 299 <listitem>\r
 300 <simpara>\r
 301 <emphasis>%ct</emphasis>: committer date, UNIX timestamp\r
 302 </simpara>\r
 303 </listitem>\r
 304 <listitem>\r
 305 <simpara>\r
 306 <emphasis>%ci</emphasis>: committer date, ISO 8601 format\r
 307 </simpara>\r
 308 </listitem>\r
 309 <listitem>\r
 310 <simpara>\r
 311 <emphasis>%d</emphasis>: ref names, like the --decorate option of <xref linkend="git-log(1)"/>\r
 312 </simpara>\r
 313 </listitem>\r
 314 <listitem>\r
 315 <simpara>\r
 316 <emphasis>%e</emphasis>: encoding\r
 317 </simpara>\r
 318 </listitem>\r
 319 <listitem>\r
 320 <simpara>\r
 321 <emphasis>%s</emphasis>: subject\r
 322 </simpara>\r
 323 </listitem>\r
 324 <listitem>\r
 325 <simpara>\r
 326 <emphasis>%b</emphasis>: body\r
 327 </simpara>\r
 328 </listitem>\r
 329 <listitem>\r
 330 <simpara>\r
 331 <emphasis>%Cred</emphasis>: switch color to red\r
 332 </simpara>\r
 333 </listitem>\r
 334 <listitem>\r
 335 <simpara>\r
 336 <emphasis>%Cgreen</emphasis>: switch color to green\r
 337 </simpara>\r
 338 </listitem>\r
 339 <listitem>\r
 340 <simpara>\r
 341 <emphasis>%Cblue</emphasis>: switch color to blue\r
 342 </simpara>\r
 343 </listitem>\r
 344 <listitem>\r
 345 <simpara>\r
 346 <emphasis>%Creset</emphasis>: reset color\r
 347 </simpara>\r
 348 </listitem>\r
 349 <listitem>\r
 350 <simpara>\r
 351 <emphasis>%C(&#8230;)</emphasis>: color specification, as described in color.branch.* config option\r
 352 </simpara>\r
 353 </listitem>\r
 354 <listitem>\r
 355 <simpara>\r
 356 <emphasis>%m</emphasis>: left, right or boundary mark\r
 357 </simpara>\r
 358 </listitem>\r
 359 <listitem>\r
 360 <simpara>\r
 361 <emphasis>%n</emphasis>: newline\r
 362 </simpara>\r
 363 </listitem>\r
 364 <listitem>\r
 365 <simpara>\r
 366 <emphasis>%x00</emphasis>: print a byte from a hex code\r
 367 </simpara>\r
 368 </listitem>\r
 369 </itemizedlist>\r
 370 </listitem>\r
 371 <listitem>\r
 372 <simpara>\r
 373 <emphasis>tformat:</emphasis>\r
 374 </simpara>\r
 375 <simpara>The <emphasis>tformat:</emphasis> format works exactly like <emphasis>format:</emphasis>, except that it\r
 376 provides "terminator" semantics instead of "separator" semantics. In\r
 377 other words, each commit has the message terminator character (usually a\r
 378 newline) appended, rather than a separator placed between entries.\r
 379 This means that the final entry of a single-line format will be properly\r
 380 terminated with a new line, just as the "oneline" format does.\r
 381 For example:</simpara>\r
 382 <literallayout>$ git log -2 --pretty=format:%h 4da45bef \\r
 383   | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'\r
 384 4da45be\r
 385 7134973 -- NO NEWLINE\r
 386 \r
 387 $ git log -2 --pretty=tformat:%h 4da45bef \\r
 388   | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'\r
 389 4da45be\r
 390 7134973</literallayout>\r
 391 </listitem>\r
 392 </itemizedlist>\r
 393 </simplesect>\r
 394 <simplesect id="_examples">\r
 395 <title>EXAMPLES</title>\r
 396 <variablelist>\r
 397 <varlistentry>\r
 398 <term>\r
 399 git show v1.0.0\r
 400 </term>\r
 401 <listitem>\r
 402 <simpara>\r
 403         Shows the tag <literal>v1.0.0</literal>, along with the object the tags\r
 404         points at.\r
 405 </simpara>\r
 406 </listitem>\r
 407 </varlistentry>\r
 408 <varlistentry>\r
 409 <term>\r
 410 git show v1.0.0^{tree}\r
 411 </term>\r
 412 <listitem>\r
 413 <simpara>\r
 414         Shows the tree pointed to by the tag <literal>v1.0.0</literal>.\r
 415 </simpara>\r
 416 </listitem>\r
 417 </varlistentry>\r
 418 <varlistentry>\r
 419 <term>\r
 420 git show next~10:Documentation/README\r
 421 </term>\r
 422 <listitem>\r
 423 <simpara>\r
 424         Shows the contents of the file <literal>Documentation/README</literal> as\r
 425         they were current in the 10th last commit of the branch\r
 426         <literal>next</literal>.\r
 427 </simpara>\r
 428 </listitem>\r
 429 </varlistentry>\r
 430 <varlistentry>\r
 431 <term>\r
 432 git show master:Makefile master:t/Makefile\r
 433 </term>\r
 434 <listitem>\r
 435 <simpara>\r
 436         Concatenates the contents of said Makefiles in the head\r
 437         of the branch <literal>master</literal>.\r
 438 </simpara>\r
 439 </listitem>\r
 440 </varlistentry>\r
 441 </variablelist>\r
 442 </simplesect>\r
 443 <simplesect id="_discussion">\r
 444 <title>Discussion</title>\r
 445 <simpara>At the core level, git is character encoding agnostic.</simpara>\r
 446 <itemizedlist>\r
 447 <listitem>\r
 448 <simpara>\r
 449 The pathnames recorded in the index and in the tree objects\r
 450    are treated as uninterpreted sequences of non-NUL bytes.\r
 451    What readdir(2) returns are what are recorded and compared\r
 452    with the data git keeps track of, which in turn are expected\r
 453    to be what lstat(2) and creat(2) accepts.  There is no such\r
 454    thing as pathname encoding translation.\r
 455 </simpara>\r
 456 </listitem>\r
 457 <listitem>\r
 458 <simpara>\r
 459 The contents of the blob objects are uninterpreted sequences\r
 460    of bytes.  There is no encoding translation at the core\r
 461    level.\r
 462 </simpara>\r
 463 </listitem>\r
 464 <listitem>\r
 465 <simpara>\r
 466 The commit log messages are uninterpreted sequences of non-NUL\r
 467    bytes.\r
 468 </simpara>\r
 469 </listitem>\r
 470 </itemizedlist>\r
 471 <simpara>Although we encourage that the commit log messages are encoded\r
 472 in UTF-8, both the core and git Porcelain are designed not to\r
 473 force UTF-8 on projects.  If all participants of a particular\r
 474 project find it more convenient to use legacy encodings, git\r
 475 does not forbid it.  However, there are a few things to keep in\r
 476 mind.</simpara>\r
 477 <orderedlist numeration="arabic">\r
 478 <listitem>\r
 479 <simpara>\r
 480 <emphasis>git-commit</emphasis> and <emphasis>git-commit-tree</emphasis> issues\r
 481   a warning if the commit log message given to it does not look\r
 482   like a valid UTF-8 string, unless you explicitly say your\r
 483   project uses a legacy encoding.  The way to say this is to\r
 484   have i18n.commitencoding in <literal>.git/config</literal> file, like this:\r
 485 </simpara>\r
 486 <literallayout>[i18n]\r
 487         commitencoding = ISO-8859-1</literallayout>\r
 488 <simpara>Commit objects created with the above setting record the value\r
 489 of <literal>i18n.commitencoding</literal> in its <literal>encoding</literal> header.  This is to\r
 490 help other people who look at them later.  Lack of this header\r
 491 implies that the commit log message is encoded in UTF-8.</simpara>\r
 492 </listitem>\r
 493 <listitem>\r
 494 <simpara>\r
 495 <emphasis>git-log</emphasis>, <emphasis>git-show</emphasis>, <emphasis>git-blame</emphasis> and friends look at the\r
 496   <literal>encoding</literal> header of a commit object, and try to re-code the\r
 497   log message into UTF-8 unless otherwise specified.  You can\r
 498   specify the desired output encoding with\r
 499   <literal>i18n.logoutputencoding</literal> in <literal>.git/config</literal> file, like this:\r
 500 </simpara>\r
 501 <literallayout>[i18n]\r
 502         logoutputencoding = ISO-8859-1</literallayout>\r
 503 <simpara>If you do not have this configuration variable, the value of\r
 504 <literal>i18n.commitencoding</literal> is used instead.</simpara>\r
 505 </listitem>\r
 506 </orderedlist>\r
 507 <simpara>Note that we deliberately chose not to re-code the commit log\r
 508 message when a commit is made to force UTF-8 at the commit\r
 509 object level, because re-coding to UTF-8 is not necessarily a\r
 510 reversible operation.</simpara>\r
 511 </simplesect>\r
 512 <simplesect id="_author">\r
 513 <title>Author</title>\r
 514 <simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt; and\r
 515 Junio C Hamano &lt;<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>&gt;.  Significantly enhanced by\r
 516 Johannes Schindelin &lt;<ulink url="mailto:Johannes.Schindelin@gmx.de">Johannes.Schindelin@gmx.de</ulink>&gt;.</simpara>\r
 517 </simplesect>\r
 518 <simplesect id="_documentation">\r
 519 <title>Documentation</title>\r
 520 <simpara>Documentation by David Greaves, Petr Baudis and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>\r
 521 </simplesect>\r
 522 <simplesect id="_git">\r
 523 <title>GIT</title>\r
 524 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
 525 </simplesect>\r
 526 </article>\r