doc/source/en/TortoiseGit/git_doc/git-ls-files.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-ls-files(1)">\r
   5 <articleinfo>\r
   6     <title>git-ls-files(1)</title>\r
   7 <indexterm>\r
   8 <primary>git-ls-files(1)</primary>\r
   9 </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-ls-files - Show information about files in the index and the working tree</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git ls-files</emphasis> [-z] [-t] [-v]\r
  19                 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*\r
  20                 (-[c|d|o|i|s|u|k|m])*\r
  21                 [-x &lt;pattern&gt;|--exclude=&lt;pattern&gt;]\r
  22                 [-X &lt;file&gt;|--exclude-from=&lt;file&gt;]\r
  23                 [--exclude-per-directory=&lt;file&gt;]\r
  24                 [--exclude-standard]\r
  25                 [--error-unmatch] [--with-tree=&lt;tree-ish&gt;]\r
  26                 [--full-name] [--abbrev] [--] [&lt;file&gt;&#8230;]</literallayout>\r
  27 </blockquote>\r
  28 </simplesect>\r
  29 <simplesect id="_description">\r
  30 <title>DESCRIPTION</title>\r
  31 <simpara>This merges the file listing in the directory cache index with the\r
  32 actual working directory list, and shows different combinations of the\r
  33 two.</simpara>\r
  34 <simpara>One or more of the options below may be used to determine the files\r
  35 shown:</simpara>\r
  36 </simplesect>\r
  37 <simplesect id="_options">\r
  38 <title>OPTIONS</title>\r
  39 <variablelist>\r
  40 <varlistentry>\r
  41 <term>\r
  42 -c\r
  43 </term>\r
  44 <term>\r
  45 --cached\r
  46 </term>\r
  47 <listitem>\r
  48 <simpara>\r
  49         Show cached files in the output (default)\r
  50 </simpara>\r
  51 </listitem>\r
  52 </varlistentry>\r
  53 <varlistentry>\r
  54 <term>\r
  55 -d\r
  56 </term>\r
  57 <term>\r
  58 --deleted\r
  59 </term>\r
  60 <listitem>\r
  61 <simpara>\r
  62         Show deleted files in the output\r
  63 </simpara>\r
  64 </listitem>\r
  65 </varlistentry>\r
  66 <varlistentry>\r
  67 <term>\r
  68 -m\r
  69 </term>\r
  70 <term>\r
  71 --modified\r
  72 </term>\r
  73 <listitem>\r
  74 <simpara>\r
  75         Show modified files in the output\r
  76 </simpara>\r
  77 </listitem>\r
  78 </varlistentry>\r
  79 <varlistentry>\r
  80 <term>\r
  81 -o\r
  82 </term>\r
  83 <term>\r
  84 --others\r
  85 </term>\r
  86 <listitem>\r
  87 <simpara>\r
  88         Show other (i.e. untracked) files in the output\r
  89 </simpara>\r
  90 </listitem>\r
  91 </varlistentry>\r
  92 <varlistentry>\r
  93 <term>\r
  94 -i\r
  95 </term>\r
  96 <term>\r
  97 --ignored\r
  98 </term>\r
  99 <listitem>\r
 100 <simpara>\r
 101         Show only ignored files in the output. When showing files in the\r
 102         index, print only those matched by an exclude pattern. When\r
 103         showing "other" files, show only those matched by an exclude\r
 104         pattern.\r
 105 </simpara>\r
 106 </listitem>\r
 107 </varlistentry>\r
 108 <varlistentry>\r
 109 <term>\r
 110 -s\r
 111 </term>\r
 112 <term>\r
 113 --stage\r
 114 </term>\r
 115 <listitem>\r
 116 <simpara>\r
 117         Show staged contents' object name, mode bits and stage number in the output.\r
 118 </simpara>\r
 119 </listitem>\r
 120 </varlistentry>\r
 121 <varlistentry>\r
 122 <term>\r
 123 --directory\r
 124 </term>\r
 125 <listitem>\r
 126 <simpara>\r
 127         If a whole directory is classified as "other", show just its\r
 128         name (with a trailing slash) and not its whole contents.\r
 129 </simpara>\r
 130 </listitem>\r
 131 </varlistentry>\r
 132 <varlistentry>\r
 133 <term>\r
 134 --no-empty-directory\r
 135 </term>\r
 136 <listitem>\r
 137 <simpara>\r
 138         Do not list empty directories. Has no effect without --directory.\r
 139 </simpara>\r
 140 </listitem>\r
 141 </varlistentry>\r
 142 <varlistentry>\r
 143 <term>\r
 144 -u\r
 145 </term>\r
 146 <term>\r
 147 --unmerged\r
 148 </term>\r
 149 <listitem>\r
 150 <simpara>\r
 151         Show unmerged files in the output (forces --stage)\r
 152 </simpara>\r
 153 </listitem>\r
 154 </varlistentry>\r
 155 <varlistentry>\r
 156 <term>\r
 157 -k\r
 158 </term>\r
 159 <term>\r
 160 --killed\r
 161 </term>\r
 162 <listitem>\r
 163 <simpara>\r
 164         Show files on the filesystem that need to be removed due\r
 165         to file/directory conflicts for checkout-index to\r
 166         succeed.\r
 167 </simpara>\r
 168 </listitem>\r
 169 </varlistentry>\r
 170 <varlistentry>\r
 171 <term>\r
 172 -z\r
 173 </term>\r
 174 <listitem>\r
 175 <simpara>\r
 176         \0 line termination on output.\r
 177 </simpara>\r
 178 </listitem>\r
 179 </varlistentry>\r
 180 <varlistentry>\r
 181 <term>\r
 182 -x &lt;pattern&gt;\r
 183 </term>\r
 184 <term>\r
 185 --exclude=&lt;pattern&gt;\r
 186 </term>\r
 187 <listitem>\r
 188 <simpara>\r
 189         Skip untracked files matching pattern.\r
 190         Note that pattern is a shell wildcard pattern. See EXCLUDE PATTERNS\r
 191         below for more information.\r
 192 </simpara>\r
 193 </listitem>\r
 194 </varlistentry>\r
 195 <varlistentry>\r
 196 <term>\r
 197 -X &lt;file&gt;\r
 198 </term>\r
 199 <term>\r
 200 --exclude-from=&lt;file&gt;\r
 201 </term>\r
 202 <listitem>\r
 203 <simpara>\r
 204         Read exclude patterns from &lt;file&gt;; 1 per line.\r
 205 </simpara>\r
 206 </listitem>\r
 207 </varlistentry>\r
 208 <varlistentry>\r
 209 <term>\r
 210 --exclude-per-directory=&lt;file&gt;\r
 211 </term>\r
 212 <listitem>\r
 213 <simpara>\r
 214         Read additional exclude patterns that apply only to the\r
 215         directory and its subdirectories in &lt;file&gt;.\r
 216 </simpara>\r
 217 </listitem>\r
 218 </varlistentry>\r
 219 <varlistentry>\r
 220 <term>\r
 221 --exclude-standard\r
 222 </term>\r
 223 <listitem>\r
 224 <simpara>\r
 225         Add the standard git exclusions: .git/info/exclude, .gitignore\r
 226         in each directory, and the user's global exclusion file.\r
 227 </simpara>\r
 228 </listitem>\r
 229 </varlistentry>\r
 230 <varlistentry>\r
 231 <term>\r
 232 --error-unmatch\r
 233 </term>\r
 234 <listitem>\r
 235 <simpara>\r
 236         If any &lt;file&gt; does not appear in the index, treat this as an\r
 237         error (return 1).\r
 238 </simpara>\r
 239 </listitem>\r
 240 </varlistentry>\r
 241 <varlistentry>\r
 242 <term>\r
 243 --with-tree=&lt;tree-ish&gt;\r
 244 </term>\r
 245 <listitem>\r
 246 <simpara>\r
 247         When using --error-unmatch to expand the user supplied\r
 248         &lt;file&gt; (i.e. path pattern) arguments to paths, pretend\r
 249         that paths which were removed in the index since the\r
 250         named &lt;tree-ish&gt; are still present.  Using this option\r
 251         with <emphasis>-s</emphasis> or <emphasis>-u</emphasis> options does not make any sense.\r
 252 </simpara>\r
 253 </listitem>\r
 254 </varlistentry>\r
 255 <varlistentry>\r
 256 <term>\r
 257 -t\r
 258 </term>\r
 259 <listitem>\r
 260 <simpara>\r
 261         This feature is semi-deprecated. For scripting purpose,\r
 262         <xref linkend="git-status(1)" /> <emphasis>--porcelain</emphasis> and\r
 263         <xref linkend="git-diff-files(1)" /> <emphasis>--name-status</emphasis> are almost always\r
 264         superior alternatives, and users should look at\r
 265         <xref linkend="git-status(1)" /> <emphasis>--short</emphasis> or <xref linkend="git-diff(1)" />\r
 266         <emphasis>--name-status</emphasis> for more user-friendly alternatives.\r
 267 </simpara>\r
 268 <simpara>This option identifies the file status with the following tags (followed by\r
 269 a space) at the start of each line:</simpara>\r
 270 </listitem>\r
 271 </varlistentry>\r
 272 <varlistentry>\r
 273 <term>\r
 274 H\r
 275 </term>\r
 276 <listitem>\r
 277 <simpara>\r
 278 cached\r
 279 </simpara>\r
 280 </listitem>\r
 281 </varlistentry>\r
 282 <varlistentry>\r
 283 <term>\r
 284 S\r
 285 </term>\r
 286 <listitem>\r
 287 <simpara>\r
 288 skip-worktree\r
 289 </simpara>\r
 290 </listitem>\r
 291 </varlistentry>\r
 292 <varlistentry>\r
 293 <term>\r
 294 M\r
 295 </term>\r
 296 <listitem>\r
 297 <simpara>\r
 298 unmerged\r
 299 </simpara>\r
 300 </listitem>\r
 301 </varlistentry>\r
 302 <varlistentry>\r
 303 <term>\r
 304 R\r
 305 </term>\r
 306 <listitem>\r
 307 <simpara>\r
 308 removed/deleted\r
 309 </simpara>\r
 310 </listitem>\r
 311 </varlistentry>\r
 312 <varlistentry>\r
 313 <term>\r
 314 C\r
 315 </term>\r
 316 <listitem>\r
 317 <simpara>\r
 318 modified/changed\r
 319 </simpara>\r
 320 </listitem>\r
 321 </varlistentry>\r
 322 <varlistentry>\r
 323 <term>\r
 324 K\r
 325 </term>\r
 326 <listitem>\r
 327 <simpara>\r
 328 to be killed\r
 329 </simpara>\r
 330 </listitem>\r
 331 </varlistentry>\r
 332 <varlistentry>\r
 333 <term>\r
 334 ?\r
 335 </term>\r
 336 <listitem>\r
 337 <simpara>\r
 338 other\r
 339 </simpara>\r
 340 </listitem>\r
 341 </varlistentry>\r
 342 <varlistentry>\r
 343 <term>\r
 344 -v\r
 345 </term>\r
 346 <listitem>\r
 347 <simpara>\r
 348         Similar to <emphasis>-t</emphasis>, but use lowercase letters for files\r
 349         that are marked as <emphasis>assume unchanged</emphasis> (see\r
 350         <xref linkend="git-update-index(1)" />).\r
 351 </simpara>\r
 352 </listitem>\r
 353 </varlistentry>\r
 354 <varlistentry>\r
 355 <term>\r
 356 --full-name\r
 357 </term>\r
 358 <listitem>\r
 359 <simpara>\r
 360         When run from a subdirectory, the command usually\r
 361         outputs paths relative to the current directory.  This\r
 362         option forces paths to be output relative to the project\r
 363         top directory.\r
 364 </simpara>\r
 365 </listitem>\r
 366 </varlistentry>\r
 367 <varlistentry>\r
 368 <term>\r
 369 --abbrev[=&lt;n&gt;]\r
 370 </term>\r
 371 <listitem>\r
 372 <simpara>\r
 373         Instead of showing the full 40-byte hexadecimal object\r
 374         lines, show only a partial prefix.\r
 375         Non default number of digits can be specified with --abbrev=&lt;n&gt;.\r
 376 </simpara>\r
 377 </listitem>\r
 378 </varlistentry>\r
 379 <varlistentry>\r
 380 <term>\r
 381 --debug\r
 382 </term>\r
 383 <listitem>\r
 384 <simpara>\r
 385         After each line that describes a file, add more data about its\r
 386         cache entry.  This is intended to show as much information as\r
 387         possible for manual inspection; the exact format may change at\r
 388         any time.\r
 389 </simpara>\r
 390 </listitem>\r
 391 </varlistentry>\r
 392 <varlistentry>\r
 393 <term>\r
 394 --\r
 395 </term>\r
 396 <listitem>\r
 397 <simpara>\r
 398         Do not interpret any more arguments as options.\r
 399 </simpara>\r
 400 </listitem>\r
 401 </varlistentry>\r
 402 <varlistentry>\r
 403 <term>\r
 404 &lt;file&gt;\r
 405 </term>\r
 406 <listitem>\r
 407 <simpara>\r
 408         Files to show. If no files are given all files which match the other\r
 409         specified criteria are shown.\r
 410 </simpara>\r
 411 </listitem>\r
 412 </varlistentry>\r
 413 </variablelist>\r
 414 </simplesect>\r
 415 <simplesect id="_output">\r
 416 <title>Output</title>\r
 417 <simpara><emphasis>git ls-files</emphasis> just outputs the filenames unless <emphasis>--stage</emphasis> is specified in\r
 418 which case it outputs:</simpara>\r
 419 <literallayout class="monospaced">[&lt;tag&gt; ]&lt;mode&gt; &lt;object&gt; &lt;stage&gt; &lt;file&gt;</literallayout>\r
 420 <simpara><emphasis>git ls-files --unmerged</emphasis> and <emphasis>git ls-files --stage</emphasis> can be used to examine\r
 421 detailed information on unmerged paths.</simpara>\r
 422 <simpara>For an unmerged path, instead of recording a single mode/SHA1 pair,\r
 423 the index records up to three such pairs; one from tree O in stage\r
 424 1, A in stage 2, and B in stage 3.  This information can be used by\r
 425 the user (or the porcelain) to see what should eventually be recorded at the\r
 426 path. (see <xref linkend="git-read-tree(1)" /> for more information on state)</simpara>\r
 427 <simpara>When <emphasis>-z</emphasis> option is not used, TAB, LF, and backslash characters\r
 428 in pathnames are represented as <emphasis>\t</emphasis>, <emphasis>\n</emphasis>, and <emphasis>\\</emphasis>,\r
 429 respectively.</simpara>\r
 430 </simplesect>\r
 431 <simplesect id="_exclude_patterns">\r
 432 <title>Exclude Patterns</title>\r
 433 <simpara><emphasis>git ls-files</emphasis> can use a list of "exclude patterns" when\r
 434 traversing the directory tree and finding files to show when the\r
 435 flags --others or --ignored are specified.  <xref linkend="gitignore(5)" />\r
 436 specifies the format of exclude patterns.</simpara>\r
 437 <simpara>These exclude patterns come from these places, in order:</simpara>\r
 438 <orderedlist numeration="arabic">\r
 439 <listitem>\r
 440 <simpara>\r
 441 The command line flag --exclude=&lt;pattern&gt; specifies a\r
 442      single pattern.  Patterns are ordered in the same order\r
 443      they appear in the command line.\r
 444 </simpara>\r
 445 </listitem>\r
 446 <listitem>\r
 447 <simpara>\r
 448 The command line flag --exclude-from=&lt;file&gt; specifies a\r
 449      file containing a list of patterns.  Patterns are ordered\r
 450      in the same order they appear in the file.\r
 451 </simpara>\r
 452 </listitem>\r
 453 <listitem>\r
 454 <simpara>\r
 455 The command line flag --exclude-per-directory=&lt;name&gt; specifies\r
 456      a name of the file in each directory <emphasis>git ls-files</emphasis>\r
 457      examines, normally <emphasis>.gitignore</emphasis>.  Files in deeper\r
 458      directories take precedence.  Patterns are ordered in the\r
 459      same order they appear in the files.\r
 460 </simpara>\r
 461 </listitem>\r
 462 </orderedlist>\r
 463 <simpara>A pattern specified on the command line with --exclude or read\r
 464 from the file specified with --exclude-from is relative to the\r
 465 top of the directory tree.  A pattern read from a file specified\r
 466 by --exclude-per-directory is relative to the directory that the\r
 467 pattern file appears in.</simpara>\r
 468 </simplesect>\r
 469 <simplesect id="_see_also">\r
 470 <title>SEE ALSO</title>\r
 471 <simpara><xref linkend="git-read-tree(1)" />, <xref linkend="gitignore(5)" /></simpara>\r
 472 </simplesect>\r
 473 <simplesect id="_git">\r
 474 <title>GIT</title>\r
 475 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 476 </simplesect>\r
 477 </article>\r