doc/source/en/TortoiseGit/git_doc/git-ls-files.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-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;]\*</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 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 ignored files in the output.\r
 102         Note that this also reverses any exclude list present.\r
 103 </simpara>\r
 104 </listitem>\r
 105 </varlistentry>\r
 106 <varlistentry>\r
 107 <term>\r
 108 -s\r
 109 </term>\r
 110 <term>\r
 111 --stage\r
 112 </term>\r
 113 <listitem>\r
 114 <simpara>\r
 115         Show staged contents' object name, mode bits and stage number in the output.\r
 116 </simpara>\r
 117 </listitem>\r
 118 </varlistentry>\r
 119 <varlistentry>\r
 120 <term>\r
 121 --directory\r
 122 </term>\r
 123 <listitem>\r
 124 <simpara>\r
 125         If a whole directory is classified as "other", show just its\r
 126         name (with a trailing slash) and not its whole contents.\r
 127 </simpara>\r
 128 </listitem>\r
 129 </varlistentry>\r
 130 <varlistentry>\r
 131 <term>\r
 132 --no-empty-directory\r
 133 </term>\r
 134 <listitem>\r
 135 <simpara>\r
 136         Do not list empty directories. Has no effect without --directory.\r
 137 </simpara>\r
 138 </listitem>\r
 139 </varlistentry>\r
 140 <varlistentry>\r
 141 <term>\r
 142 -u\r
 143 </term>\r
 144 <term>\r
 145 --unmerged\r
 146 </term>\r
 147 <listitem>\r
 148 <simpara>\r
 149         Show unmerged files in the output (forces --stage)\r
 150 </simpara>\r
 151 </listitem>\r
 152 </varlistentry>\r
 153 <varlistentry>\r
 154 <term>\r
 155 -k\r
 156 </term>\r
 157 <term>\r
 158 --killed\r
 159 </term>\r
 160 <listitem>\r
 161 <simpara>\r
 162         Show files on the filesystem that need to be removed due\r
 163         to file/directory conflicts for checkout-index to\r
 164         succeed.\r
 165 </simpara>\r
 166 </listitem>\r
 167 </varlistentry>\r
 168 <varlistentry>\r
 169 <term>\r
 170 -z\r
 171 </term>\r
 172 <listitem>\r
 173 <simpara>\r
 174         \0 line termination on output.\r
 175 </simpara>\r
 176 </listitem>\r
 177 </varlistentry>\r
 178 <varlistentry>\r
 179 <term>\r
 180 -x &lt;pattern&gt;\r
 181 </term>\r
 182 <term>\r
 183 --exclude=&lt;pattern&gt;\r
 184 </term>\r
 185 <listitem>\r
 186 <simpara>\r
 187         Skips files matching pattern.\r
 188         Note that pattern is a shell wildcard pattern.\r
 189 </simpara>\r
 190 </listitem>\r
 191 </varlistentry>\r
 192 <varlistentry>\r
 193 <term>\r
 194 -X &lt;file&gt;\r
 195 </term>\r
 196 <term>\r
 197 --exclude-from=&lt;file&gt;\r
 198 </term>\r
 199 <listitem>\r
 200 <simpara>\r
 201         exclude patterns are read from &lt;file&gt;; 1 per line.\r
 202 </simpara>\r
 203 </listitem>\r
 204 </varlistentry>\r
 205 <varlistentry>\r
 206 <term>\r
 207 --exclude-per-directory=&lt;file&gt;\r
 208 </term>\r
 209 <listitem>\r
 210 <simpara>\r
 211         read additional exclude patterns that apply only to the\r
 212         directory and its subdirectories in &lt;file&gt;.\r
 213 </simpara>\r
 214 </listitem>\r
 215 </varlistentry>\r
 216 <varlistentry>\r
 217 <term>\r
 218 --exclude-standard\r
 219 </term>\r
 220 <listitem>\r
 221 <simpara>\r
 222         Add the standard git exclusions: .git/info/exclude, .gitignore\r
 223         in each directory, and the user&#8217;s global exclusion file.\r
 224 </simpara>\r
 225 </listitem>\r
 226 </varlistentry>\r
 227 <varlistentry>\r
 228 <term>\r
 229 --error-unmatch\r
 230 </term>\r
 231 <listitem>\r
 232 <simpara>\r
 233         If any &lt;file&gt; does not appear in the index, treat this as an\r
 234         error (return 1).\r
 235 </simpara>\r
 236 </listitem>\r
 237 </varlistentry>\r
 238 <varlistentry>\r
 239 <term>\r
 240 --with-tree=&lt;tree-ish&gt;\r
 241 </term>\r
 242 <listitem>\r
 243 <simpara>\r
 244         When using --error-unmatch to expand the user supplied\r
 245         &lt;file&gt; (i.e. path pattern) arguments to paths, pretend\r
 246         that paths which were removed in the index since the\r
 247         named &lt;tree-ish&gt; are still present.  Using this option\r
 248         with <literal>-s</literal> or <literal>-u</literal> options does not make any sense.\r
 249 </simpara>\r
 250 </listitem>\r
 251 </varlistentry>\r
 252 <varlistentry>\r
 253 <term>\r
 254 -t\r
 255 </term>\r
 256 <listitem>\r
 257 <simpara>\r
 258         Identify the file status with the following tags (followed by\r
 259         a space) at the start of each line:\r
 260 </simpara>\r
 261 </listitem>\r
 262 </varlistentry>\r
 263 <varlistentry>\r
 264 <term>\r
 265 H\r
 266 </term>\r
 267 <listitem>\r
 268 <simpara>\r
 269 cached\r
 270 </simpara>\r
 271 </listitem>\r
 272 </varlistentry>\r
 273 <varlistentry>\r
 274 <term>\r
 275 M\r
 276 </term>\r
 277 <listitem>\r
 278 <simpara>\r
 279 unmerged\r
 280 </simpara>\r
 281 </listitem>\r
 282 </varlistentry>\r
 283 <varlistentry>\r
 284 <term>\r
 285 R\r
 286 </term>\r
 287 <listitem>\r
 288 <simpara>\r
 289 removed/deleted\r
 290 </simpara>\r
 291 </listitem>\r
 292 </varlistentry>\r
 293 <varlistentry>\r
 294 <term>\r
 295 C\r
 296 </term>\r
 297 <listitem>\r
 298 <simpara>\r
 299 modified/changed\r
 300 </simpara>\r
 301 </listitem>\r
 302 </varlistentry>\r
 303 <varlistentry>\r
 304 <term>\r
 305 K\r
 306 </term>\r
 307 <listitem>\r
 308 <simpara>\r
 309 to be killed\r
 310 </simpara>\r
 311 </listitem>\r
 312 </varlistentry>\r
 313 <varlistentry>\r
 314 <term>\r
 315 ?\r
 316 </term>\r
 317 <listitem>\r
 318 <simpara>\r
 319 other\r
 320 </simpara>\r
 321 </listitem>\r
 322 </varlistentry>\r
 323 <varlistentry>\r
 324 <term>\r
 325 -v\r
 326 </term>\r
 327 <listitem>\r
 328 <simpara>\r
 329         Similar to <literal>-t</literal>, but use lowercase letters for files\r
 330         that are marked as <emphasis>assume unchanged</emphasis> (see\r
 331         <xref linkend="git-update-index(1)"/>).\r
 332 </simpara>\r
 333 </listitem>\r
 334 </varlistentry>\r
 335 <varlistentry>\r
 336 <term>\r
 337 --full-name\r
 338 </term>\r
 339 <listitem>\r
 340 <simpara>\r
 341         When run from a subdirectory, the command usually\r
 342         outputs paths relative to the current directory.  This\r
 343         option forces paths to be output relative to the project\r
 344         top directory.\r
 345 </simpara>\r
 346 </listitem>\r
 347 </varlistentry>\r
 348 <varlistentry>\r
 349 <term>\r
 350 --abbrev[=&lt;n&gt;]\r
 351 </term>\r
 352 <listitem>\r
 353 <simpara>\r
 354         Instead of showing the full 40-byte hexadecimal object\r
 355         lines, show only a partial prefix.\r
 356         Non default number of digits can be specified with --abbrev=&lt;n&gt;.\r
 357 </simpara>\r
 358 </listitem>\r
 359 </varlistentry>\r
 360 <varlistentry>\r
 361 <term>\r
 362 --\r
 363 </term>\r
 364 <listitem>\r
 365 <simpara>\r
 366         Do not interpret any more arguments as options.\r
 367 </simpara>\r
 368 </listitem>\r
 369 </varlistentry>\r
 370 <varlistentry>\r
 371 <term>\r
 372 &lt;file&gt;\r
 373 </term>\r
 374 <listitem>\r
 375 <simpara>\r
 376         Files to show. If no files are given all files which match the other\r
 377         specified criteria are shown.\r
 378 </simpara>\r
 379 </listitem>\r
 380 </varlistentry>\r
 381 </variablelist>\r
 382 </simplesect>\r
 383 <simplesect id="_output">\r
 384 <title>Output</title>\r
 385 <simpara>show files just outputs the filename unless <emphasis>--stage</emphasis> is specified in\r
 386 which case it outputs:</simpara>\r
 387 <literallayout class="monospaced">[&lt;tag&gt; ]&lt;mode&gt; &lt;object&gt; &lt;stage&gt; &lt;file&gt;</literallayout>\r
 388 <simpara><emphasis>git-ls-files --unmerged</emphasis> and <emphasis>git-ls-files --stage</emphasis> can be used to examine\r
 389 detailed information on unmerged paths.</simpara>\r
 390 <simpara>For an unmerged path, instead of recording a single mode/SHA1 pair,\r
 391 the index records up to three such pairs; one from tree O in stage\r
 392 1, A in stage 2, and B in stage 3.  This information can be used by\r
 393 the user (or the porcelain) to see what should eventually be recorded at the\r
 394 path. (see <xref linkend="git-read-tree(1)"/> for more information on state)</simpara>\r
 395 <simpara>When <literal>-z</literal> option is not used, TAB, LF, and backslash characters\r
 396 in pathnames are represented as <literal>\t</literal>, <literal>\n</literal>, and <literal>\\</literal>,\r
 397 respectively.</simpara>\r
 398 </simplesect>\r
 399 <simplesect id="_exclude_patterns">\r
 400 <title>Exclude Patterns</title>\r
 401 <simpara><emphasis>git-ls-files</emphasis> can use a list of "exclude patterns" when\r
 402 traversing the directory tree and finding files to show when the\r
 403 flags --others or --ignored are specified.  <xref linkend="gitignore(5)"/>\r
 404 specifies the format of exclude patterns.</simpara>\r
 405 <simpara>These exclude patterns come from these places, in order:</simpara>\r
 406 <orderedlist numeration="arabic">\r
 407 <listitem>\r
 408 <simpara>\r
 409 The command line flag --exclude=&lt;pattern&gt; specifies a\r
 410      single pattern.  Patterns are ordered in the same order\r
 411      they appear in the command line.\r
 412 </simpara>\r
 413 </listitem>\r
 414 <listitem>\r
 415 <simpara>\r
 416 The command line flag --exclude-from=&lt;file&gt; specifies a\r
 417      file containing a list of patterns.  Patterns are ordered\r
 418      in the same order they appear in the file.\r
 419 </simpara>\r
 420 </listitem>\r
 421 <listitem>\r
 422 <simpara>\r
 423 command line flag --exclude-per-directory=&lt;name&gt; specifies\r
 424      a name of the file in each directory <emphasis>git-ls-files</emphasis>\r
 425      examines, normally <literal>.gitignore</literal>.  Files in deeper\r
 426      directories take precedence.  Patterns are ordered in the\r
 427      same order they appear in the files.\r
 428 </simpara>\r
 429 </listitem>\r
 430 </orderedlist>\r
 431 <simpara>A pattern specified on the command line with --exclude or read\r
 432 from the file specified with --exclude-from is relative to the\r
 433 top of the directory tree.  A pattern read from a file specified\r
 434 by --exclude-per-directory is relative to the directory that the\r
 435 pattern file appears in.</simpara>\r
 436 </simplesect>\r
 437 <simplesect id="_see_also">\r
 438 <title>SEE ALSO</title>\r
 439 <simpara><xref linkend="git-read-tree(1)"/>, <xref linkend="gitignore(5)"/></simpara>\r
 440 </simplesect>\r
 441 <simplesect id="_author">\r
 442 <title>Author</title>\r
 443 <simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt;</simpara>\r
 444 </simplesect>\r
 445 <simplesect id="_documentation">\r
 446 <title>Documentation</title>\r
 447 <simpara>Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>\r
 448 </simplesect>\r
 449 <simplesect id="_git">\r
 450 <title>GIT</title>\r
 451 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
 452 </simplesect>\r
 453 </article>\r