git-ls-files.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
   6 <meta name="generator" content="AsciiDoc 7.0.2" />\r
   7 <style type="text/css">\r
   8 /* Debug borders */\r
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
  10 /*\r
  11   border: 1px solid red;\r
  12 */\r
  13 }\r
  14 \r
  15 body {\r
  16   margin: 1em 5% 1em 5%;\r
  17 }\r
  18 \r
  19 a { color: blue; }\r
  20 a:visited { color: fuchsia; }\r
  21 \r
  22 em {\r
  23   font-style: italic;\r
  24 }\r
  25 \r
  26 strong {\r
  27   font-weight: bold;\r
  28 }\r
  29 \r
  30 tt {\r
  31   color: navy;\r
  32 }\r
  33 \r
  34 h1, h2, h3, h4, h5, h6 {\r
  35   color: #527bbd;\r
  36   font-family: sans-serif;\r
  37   margin-top: 1.2em;\r
  38   margin-bottom: 0.5em;\r
  39   line-height: 1.3;\r
  40 }\r
  41 \r
  42 h1 {\r
  43   border-bottom: 2px solid silver;\r
  44 }\r
  45 h2 {\r
  46   border-bottom: 2px solid silver;\r
  47   padding-top: 0.5em;\r
  48 }\r
  49 \r
  50 div.sectionbody {\r
  51   font-family: serif;\r
  52   margin-left: 0;\r
  53 }\r
  54 \r
  55 hr {\r
  56   border: 1px solid silver;\r
  57 }\r
  58 \r
  59 p {\r
  60   margin-top: 0.5em;\r
  61   margin-bottom: 0.5em;\r
  62 }\r
  63 \r
  64 pre {\r
  65   padding: 0;\r
  66   margin: 0;\r
  67 }\r
  68 \r
  69 span#author {\r
  70   color: #527bbd;\r
  71   font-family: sans-serif;\r
  72   font-weight: bold;\r
  73   font-size: 1.2em;\r
  74 }\r
  75 span#email {\r
  76 }\r
  77 span#revision {\r
  78   font-family: sans-serif;\r
  79 }\r
  80 \r
  81 div#footer {\r
  82   font-family: sans-serif;\r
  83   font-size: small;\r
  84   border-top: 2px solid silver;\r
  85   padding-top: 0.5em;\r
  86   margin-top: 4.0em;\r
  87 }\r
  88 div#footer-text {\r
  89   float: left;\r
  90   padding-bottom: 0.5em;\r
  91 }\r
  92 div#footer-badges {\r
  93   float: right;\r
  94   padding-bottom: 0.5em;\r
  95 }\r
  96 \r
  97 div#preamble,\r
  98 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
  99 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
 100 div.admonitionblock {\r
 101   margin-right: 10%;\r
 102   margin-top: 1.5em;\r
 103   margin-bottom: 1.5em;\r
 104 }\r
 105 div.admonitionblock {\r
 106   margin-top: 2.5em;\r
 107   margin-bottom: 2.5em;\r
 108 }\r
 109 \r
 110 div.content { /* Block element content. */\r
 111   padding: 0;\r
 112 }\r
 113 \r
 114 /* Block element titles. */\r
 115 div.title, caption.title {\r
 116   font-family: sans-serif;\r
 117   font-weight: bold;\r
 118   text-align: left;\r
 119   margin-top: 1.0em;\r
 120   margin-bottom: 0.5em;\r
 121 }\r
 122 div.title + * {\r
 123   margin-top: 0;\r
 124 }\r
 125 \r
 126 td div.title:first-child {\r
 127   margin-top: 0.0em;\r
 128 }\r
 129 div.content div.title:first-child {\r
 130   margin-top: 0.0em;\r
 131 }\r
 132 div.content + div.title {\r
 133   margin-top: 0.0em;\r
 134 }\r
 135 \r
 136 div.sidebarblock > div.content {\r
 137   background: #ffffee;\r
 138   border: 1px solid silver;\r
 139   padding: 0.5em;\r
 140 }\r
 141 \r
 142 div.listingblock > div.content {\r
 143   border: 1px solid silver;\r
 144   background: #f4f4f4;\r
 145   padding: 0.5em;\r
 146 }\r
 147 \r
 148 div.quoteblock > div.content {\r
 149   padding-left: 2.0em;\r
 150 }\r
 151 div.quoteblock .attribution {\r
 152   text-align: right;\r
 153 }\r
 154 \r
 155 div.admonitionblock .icon {\r
 156   vertical-align: top;\r
 157   font-size: 1.1em;\r
 158   font-weight: bold;\r
 159   text-decoration: underline;\r
 160   color: #527bbd;\r
 161   padding-right: 0.5em;\r
 162 }\r
 163 div.admonitionblock td.content {\r
 164   padding-left: 0.5em;\r
 165   border-left: 2px solid silver;\r
 166 }\r
 167 \r
 168 div.exampleblock > div.content {\r
 169   border-left: 2px solid silver;\r
 170   padding: 0.5em;\r
 171 }\r
 172 \r
 173 div.verseblock div.content {\r
 174   white-space: pre;\r
 175 }\r
 176 \r
 177 div.imageblock div.content { padding-left: 0; }\r
 178 div.imageblock img { border: 1px solid silver; }\r
 179 span.image img { border-style: none; }\r
 180 \r
 181 dl {\r
 182   margin-top: 0.8em;\r
 183   margin-bottom: 0.8em;\r
 184 }\r
 185 dt {\r
 186   margin-top: 0.5em;\r
 187   margin-bottom: 0;\r
 188   font-style: italic;\r
 189 }\r
 190 dd > *:first-child {\r
 191   margin-top: 0;\r
 192 }\r
 193 \r
 194 ul, ol {\r
 195     list-style-position: outside;\r
 196 }\r
 197 ol.olist2 {\r
 198   list-style-type: lower-alpha;\r
 199 }\r
 200 \r
 201 div.tableblock > table {\r
 202   border-color: #527bbd;\r
 203   border-width: 3px;\r
 204 }\r
 205 thead {\r
 206   font-family: sans-serif;\r
 207   font-weight: bold;\r
 208 }\r
 209 tfoot {\r
 210   font-weight: bold;\r
 211 }\r
 212 \r
 213 div.hlist {\r
 214   margin-top: 0.8em;\r
 215   margin-bottom: 0.8em;\r
 216 }\r
 217 td.hlist1 {\r
 218   vertical-align: top;\r
 219   font-style: italic;\r
 220   padding-right: 0.8em;\r
 221 }\r
 222 td.hlist2 {\r
 223   vertical-align: top;\r
 224 }\r
 225 \r
 226 @media print {\r
 227   div#footer-badges { display: none; }\r
 228 }\r
 229 include::./stylesheets/xhtml11-manpage.css[]\r
 230 /* Workarounds for IE6's broken and incomplete CSS2. */\r
 231 \r
 232 div.sidebar-content {\r
 233   background: #ffffee;\r
 234   border: 1px solid silver;\r
 235   padding: 0.5em;\r
 236 }\r
 237 div.sidebar-title, div.image-title {\r
 238   font-family: sans-serif;\r
 239   font-weight: bold;\r
 240   margin-top: 0.0em;\r
 241   margin-bottom: 0.5em;\r
 242 }\r
 243 \r
 244 div.listingblock div.content {\r
 245   border: 1px solid silver;\r
 246   background: #f4f4f4;\r
 247   padding: 0.5em;\r
 248 }\r
 249 \r
 250 div.quoteblock-content {\r
 251   padding-left: 2.0em;\r
 252 }\r
 253 \r
 254 div.exampleblock-content {\r
 255   border-left: 2px solid silver;\r
 256   padding-left: 0.5em;\r
 257 }\r
 258 </style>\r
 259 <title>git-ls-files(1)</title>\r
 260 </head>\r
 261 <body>\r
 262 <div id="header">\r
 263 <h1>\r
 264 git-ls-files(1) Manual Page\r
 265 </h1>\r
 266 <h2>NAME</h2>\r
 267 <div class="sectionbody">\r
 268 <p>git-ls-files -\r
 269    Information about files in the index/working directory\r
 270 </p>\r
 271 </div>\r
 272 </div>\r
 273 <h2>SYNOPSIS</h2>\r
 274 <div class="sectionbody">\r
 275 <div class="verseblock">\r
 276 <div class="content"><em>git-ls-files</em> [-z] [-t] [-v]\r
 277                 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\r
 278                 (-[c|d|o|i|s|u|k|m])*\r
 279                 [-x &lt;pattern&gt;|--exclude=&lt;pattern&gt;]\r
 280                 [-X &lt;file&gt;|--exclude-from=&lt;file&gt;]\r
 281                 [--exclude-per-directory=&lt;file&gt;]\r
 282                 [--error-unmatch]\r
 283                 [--full-name] [--abbrev] [--] [&lt;file&gt;]*</div></div>\r
 284 </div>\r
 285 <h2>DESCRIPTION</h2>\r
 286 <div class="sectionbody">\r
 287 <p>This merges the file listing in the directory cache index with the\r
 288 actual working directory list, and shows different combinations of the\r
 289 two.</p>\r
 290 <p>One or more of the options below may be used to determine the files\r
 291 shown:</p>\r
 292 </div>\r
 293 <h2>OPTIONS</h2>\r
 294 <div class="sectionbody">\r
 295 <dl>\r
 296 <dt>\r
 297 -c|--cached\r
 298 </dt>\r
 299 <dd>\r
 300 <p>\r
 301         Show cached files in the output (default)\r
 302 </p>\r
 303 </dd>\r
 304 <dt>\r
 305 -d|--deleted\r
 306 </dt>\r
 307 <dd>\r
 308 <p>\r
 309         Show deleted files in the output\r
 310 </p>\r
 311 </dd>\r
 312 <dt>\r
 313 -m|--modified\r
 314 </dt>\r
 315 <dd>\r
 316 <p>\r
 317         Show modified files in the output\r
 318 </p>\r
 319 </dd>\r
 320 <dt>\r
 321 -o|--others\r
 322 </dt>\r
 323 <dd>\r
 324 <p>\r
 325         Show other files in the output\r
 326 </p>\r
 327 </dd>\r
 328 <dt>\r
 329 -i|--ignored\r
 330 </dt>\r
 331 <dd>\r
 332 <p>\r
 333         Show ignored files in the output\r
 334         Note the this also reverses any exclude list present.\r
 335 </p>\r
 336 </dd>\r
 337 <dt>\r
 338 -s|--stage\r
 339 </dt>\r
 340 <dd>\r
 341 <p>\r
 342         Show stage files in the output\r
 343 </p>\r
 344 </dd>\r
 345 <dt>\r
 346 --directory\r
 347 </dt>\r
 348 <dd>\r
 349 <p>\r
 350         If a whole directory is classified as "other", show just its\r
 351         name (with a trailing slash) and not its whole contents.\r
 352 </p>\r
 353 </dd>\r
 354 <dt>\r
 355 --no-empty-directory\r
 356 </dt>\r
 357 <dd>\r
 358 <p>\r
 359         Do not list empty directories. Has no effect without --directory.\r
 360 </p>\r
 361 </dd>\r
 362 <dt>\r
 363 -u|--unmerged\r
 364 </dt>\r
 365 <dd>\r
 366 <p>\r
 367         Show unmerged files in the output (forces --stage)\r
 368 </p>\r
 369 </dd>\r
 370 <dt>\r
 371 -k|--killed\r
 372 </dt>\r
 373 <dd>\r
 374 <p>\r
 375         Show files on the filesystem that need to be removed due\r
 376         to file/directory conflicts for checkout-index to\r
 377         succeed.\r
 378 </p>\r
 379 </dd>\r
 380 <dt>\r
 381 -z\r
 382 </dt>\r
 383 <dd>\r
 384 <p>\r
 385         \0 line termination on output.\r
 386 </p>\r
 387 </dd>\r
 388 <dt>\r
 389 -x|--exclude=&lt;pattern&gt;\r
 390 </dt>\r
 391 <dd>\r
 392 <p>\r
 393         Skips files matching pattern.\r
 394         Note that pattern is a shell wildcard pattern.\r
 395 </p>\r
 396 </dd>\r
 397 <dt>\r
 398 -X|--exclude-from=&lt;file&gt;\r
 399 </dt>\r
 400 <dd>\r
 401 <p>\r
 402         exclude patterns are read from &lt;file&gt;; 1 per line.\r
 403 </p>\r
 404 </dd>\r
 405 <dt>\r
 406 --exclude-per-directory=&lt;file&gt;\r
 407 </dt>\r
 408 <dd>\r
 409 <p>\r
 410         read additional exclude patterns that apply only to the\r
 411         directory and its subdirectories in &lt;file&gt;.\r
 412 </p>\r
 413 </dd>\r
 414 <dt>\r
 415 --error-unmatch\r
 416 </dt>\r
 417 <dd>\r
 418 <p>\r
 419         If any &lt;file&gt; does not appear in the index, treat this as an\r
 420         error (return 1).\r
 421 </p>\r
 422 </dd>\r
 423 <dt>\r
 424 -t\r
 425 </dt>\r
 426 <dd>\r
 427 <p>\r
 428         Identify the file status with the following tags (followed by\r
 429         a space) at the start of each line:\r
 430 </p>\r
 431 <div class="hlist"><table>\r
 432 <tr>\r
 433 <td class="hlist1">\r
 434 H\r
 435 </td>\r
 436 <td class="hlist2">\r
 437 cached\r
 438 </td>\r
 439 </tr>\r
 440 <tr>\r
 441 <td class="hlist1">\r
 442 M\r
 443 </td>\r
 444 <td class="hlist2">\r
 445 unmerged\r
 446 </td>\r
 447 </tr>\r
 448 <tr>\r
 449 <td class="hlist1">\r
 450 R\r
 451 </td>\r
 452 <td class="hlist2">\r
 453 removed/deleted\r
 454 </td>\r
 455 </tr>\r
 456 <tr>\r
 457 <td class="hlist1">\r
 458 C\r
 459 </td>\r
 460 <td class="hlist2">\r
 461 modified/changed\r
 462 </td>\r
 463 </tr>\r
 464 <tr>\r
 465 <td class="hlist1">\r
 466 K\r
 467 </td>\r
 468 <td class="hlist2">\r
 469 to be killed\r
 470 </td>\r
 471 </tr>\r
 472 <tr>\r
 473 <td class="hlist1">\r
 474 ?\r
 475 </td>\r
 476 <td class="hlist2">\r
 477 other\r
 478 </td>\r
 479 </tr>\r
 480 </table></div>\r
 481 </dd>\r
 482 <dt>\r
 483 -v\r
 484 </dt>\r
 485 <dd>\r
 486 <p>\r
 487         Similar to <tt>-t</tt>, but use lowercase letters for files\r
 488         that are marked as <em>always matching index</em>.\r
 489 </p>\r
 490 </dd>\r
 491 <dt>\r
 492 --full-name\r
 493 </dt>\r
 494 <dd>\r
 495 <p>\r
 496         When run from a subdirectory, the command usually\r
 497         outputs paths relative to the current directory.  This\r
 498         option forces paths to be output relative to the project\r
 499         top directory.\r
 500 </p>\r
 501 </dd>\r
 502 <dt>\r
 503 --abbrev[=&lt;n&gt;]\r
 504 </dt>\r
 505 <dd>\r
 506 <p>\r
 507         Instead of showing the full 40-byte hexadecimal object\r
 508         lines, show only handful hexdigits prefix.\r
 509         Non default number of digits can be specified with --abbrev=&lt;n&gt;.\r
 510 </p>\r
 511 </dd>\r
 512 <dt>\r
 513 --\r
 514 </dt>\r
 515 <dd>\r
 516 <p>\r
 517         Do not interpret any more arguments as options.\r
 518 </p>\r
 519 </dd>\r
 520 <dt>\r
 521 &lt;file&gt;\r
 522 </dt>\r
 523 <dd>\r
 524 <p>\r
 525         Files to show. If no files are given all files which match the other\r
 526         specified criteria are shown.\r
 527 </p>\r
 528 </dd>\r
 529 </dl>\r
 530 </div>\r
 531 <h2>Output</h2>\r
 532 <div class="sectionbody">\r
 533 <p>show files just outputs the filename unless <em>--stage</em> is specified in\r
 534 which case it outputs:</p>\r
 535 <div class="literalblock">\r
 536 <div class="content">\r
 537 <pre><tt>[&lt;tag&gt; ]&lt;mode&gt; &lt;object&gt; &lt;stage&gt; &lt;file&gt;</tt></pre>\r
 538 </div></div>\r
 539 <p>"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine\r
 540 detailed information on unmerged paths.</p>\r
 541 <p>For an unmerged path, instead of recording a single mode/SHA1 pair,\r
 542 the dircache records up to three such pairs; one from tree O in stage\r
 543 1, A in stage 2, and B in stage 3.  This information can be used by\r
 544 the user (or the porcelain) to see what should eventually be recorded at the\r
 545 path. (see git-read-tree for more information on state)</p>\r
 546 <p>When <tt>-z</tt> option is not used, TAB, LF, and backslash characters\r
 547 in pathnames are represented as <tt>\t</tt>, <tt>\n</tt>, and <tt>\\</tt>,\r
 548 respectively.</p>\r
 549 </div>\r
 550 <h2>Exclude Patterns</h2>\r
 551 <div class="sectionbody">\r
 552 <p><em>git-ls-files</em> can use a list of "exclude patterns" when\r
 553 traversing the directory tree and finding files to show when the\r
 554 flags --others or --ignored are specified.</p>\r
 555 <p>These exclude patterns come from these places:</p>\r
 556 <ol>\r
 557 <li>\r
 558 <p>\r
 559 command line flag --exclude=&lt;pattern&gt; specifies a single\r
 560      pattern.\r
 561 </p>\r
 562 </li>\r
 563 <li>\r
 564 <p>\r
 565 command line flag --exclude-from=&lt;file&gt; specifies a list of\r
 566      patterns stored in a file.\r
 567 </p>\r
 568 </li>\r
 569 <li>\r
 570 <p>\r
 571 command line flag --exclude-per-directory=&lt;name&gt; specifies\r
 572      a name of the file in each directory <em>git-ls-files</em>\r
 573      examines, and if exists, its contents are used as an\r
 574      additional list of patterns.\r
 575 </p>\r
 576 </li>\r
 577 </ol>\r
 578 <p>An exclude pattern file used by (2) and (3) contains one pattern\r
 579 per line.  A line that starts with a <em>#</em> can be used as comment\r
 580 for readability.</p>\r
 581 <p>There are three lists of patterns that are in effect at a given\r
 582 time.  They are built and ordered in the following way:</p>\r
 583 <ul>\r
 584 <li>\r
 585 <p>\r
 586 --exclude=&lt;pattern&gt; from the command line; patterns are\r
 587    ordered in the same order as they appear on the command line.\r
 588 </p>\r
 589 </li>\r
 590 <li>\r
 591 <p>\r
 592 lines read from --exclude-from=&lt;file&gt;; patterns are ordered\r
 593    in the same order as they appear in the file.\r
 594 </p>\r
 595 </li>\r
 596 <li>\r
 597 <p>\r
 598 When --exclude-per-directory=&lt;name&gt; is specified, upon\r
 599    entering a directory that has such a file, its contents are\r
 600    appended at the end of the current "list of patterns".  They\r
 601    are popped off when leaving the directory.\r
 602 </p>\r
 603 </li>\r
 604 </ul>\r
 605 <p>Each pattern in the pattern list specifies "a match pattern" and\r
 606 optionally the fate; either a file that matches the pattern is\r
 607 considered excluded or included.  A filename is matched against\r
 608 the patterns in the three lists; the --exclude-from list is\r
 609 checked first, then the --exclude-per-directory list, and then\r
 610 finally the --exclude list. The last match determines its fate.\r
 611 If there is no match in the three lists, the fate is "included".</p>\r
 612 <p>A pattern specified on the command line with --exclude or read\r
 613 from the file specified with --exclude-from is relative to the\r
 614 top of the directory tree.  A pattern read from a file specified\r
 615 by --exclude-per-directory is relative to the directory that the\r
 616 pattern file appears in.</p>\r
 617 <p>An exclude pattern is of the following format:</p>\r
 618 <ul>\r
 619 <li>\r
 620 <p>\r
 621 an optional prefix <em>!</em> which means that the fate this pattern\r
 622    specifies is "include", not the usual "exclude"; the\r
 623    remainder of the pattern string is interpreted according to\r
 624    the following rules.\r
 625 </p>\r
 626 </li>\r
 627 <li>\r
 628 <p>\r
 629 if it does not contain a slash <em>/</em>, it is a shell glob\r
 630    pattern and used to match against the filename without\r
 631    leading directories (i.e. the same way as the current\r
 632    implementation).\r
 633 </p>\r
 634 </li>\r
 635 <li>\r
 636 <p>\r
 637 otherwise, it is a shell glob pattern, suitable for\r
 638    consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a\r
 639    slash in the pattern must match a slash in the pathname.\r
 640    "Documentation/*.html" matches "Documentation/git.html" but\r
 641    not "ppc/ppc.html".  As a natural exception, "/*.c" matches\r
 642    "cat-file.c" but not "mozilla-sha1/sha1.c".\r
 643 </p>\r
 644 </li>\r
 645 </ul>\r
 646 <p>An example:</p>\r
 647 <div class="listingblock">\r
 648 <div class="content">\r
 649 <pre><tt>    $ cat .git/ignore\r
 650     # ignore objects and archives, anywhere in the tree.\r
 651     *.[oa]\r
 652     $ cat Documentation/.gitignore\r
 653     # ignore generated html files,\r
 654     *.html\r
 655     # except foo.html which is maintained by hand\r
 656     !foo.html\r
 657     $ git-ls-files --ignored \\r
 658         --exclude='Documentation/*.[0-9]' \\r
 659         --exclude-from=.git/ignore \\r
 660         --exclude-per-directory=.gitignore</tt></pre>\r
 661 </div></div>\r
 662 </div>\r
 663 <h2>See Also</h2>\r
 664 <div class="sectionbody">\r
 665 <p><a href="git-read-tree.html">git-read-tree(1)</a></p>\r
 666 </div>\r
 667 <h2>Author</h2>\r
 668 <div class="sectionbody">\r
 669 <p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;</p>\r
 670 </div>\r
 671 <h2>Documentation</h2>\r
 672 <div class="sectionbody">\r
 673 <p>Documentation by David Greaves, Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p>\r
 674 </div>\r
 675 <h2>GIT</h2>\r
 676 <div class="sectionbody">\r
 677 <p>Part of the <a href="git.html">git(7)</a> suite</p>\r
 678 </div>\r
 679 <div id="footer">\r
 680 <div id="footer-text">\r
 681 Last updated 05-May-2006 23:14:13 UTC\r
 682 </div>\r
 683 </div>\r
 684 </body>\r
 685 </html>\r