Documentation/git-ls-files.txt

   1 git-ls-files(1)
   2 ===============
   3
   4 NAME
   5 ----
   6 git-ls-files - Show information about files in the index and the working tree
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git-ls-files' [-z] [-t] [-v]
  13                 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
  14                 (-[c|d|o|i|s|u|k|m])\*
  15                 [-x <pattern>|--exclude=<pattern>]
  16                 [-X <file>|--exclude-from=<file>]
  17                 [--exclude-per-directory=<file>]
  18                 [--error-unmatch] [--with-tree=<tree-ish>]
  19                 [--full-name] [--abbrev] [--] [<file>]\*
  20
  21 DESCRIPTION
  22 -----------
  23 This merges the file listing in the directory cache index with the
  24 actual working directory list, and shows different combinations of the
  25 two.
  26
  27 One or more of the options below may be used to determine the files
  28 shown:
  29
  30 OPTIONS
  31 -------
  32 -c|--cached::
  33         Show cached files in the output (default)
  34
  35 -d|--deleted::
  36         Show deleted files in the output
  37
  38 -m|--modified::
  39         Show modified files in the output
  40
  41 -o|--others::
  42         Show other files in the output
  43
  44 -i|--ignored::
  45         Show ignored files in the output.
  46         Note that this also reverses any exclude list present.
  47
  48 -s|--stage::
  49         Show stage files in the output
  50
  51 --directory::
  52         If a whole directory is classified as "other", show just its
  53         name (with a trailing slash) and not its whole contents.
  54
  55 --no-empty-directory::
  56         Do not list empty directories. Has no effect without --directory.
  57
  58 -u|--unmerged::
  59         Show unmerged files in the output (forces --stage)
  60
  61 -k|--killed::
  62         Show files on the filesystem that need to be removed due
  63         to file/directory conflicts for checkout-index to
  64         succeed.
  65
  66 -z::
  67         \0 line termination on output.
  68
  69 -x|--exclude=<pattern>::
  70         Skips files matching pattern.
  71         Note that pattern is a shell wildcard pattern.
  72
  73 -X|--exclude-from=<file>::
  74         exclude patterns are read from <file>; 1 per line.
  75
  76 --exclude-per-directory=<file>::
  77         read additional exclude patterns that apply only to the
  78         directory and its subdirectories in <file>.
  79
  80 --error-unmatch::
  81         If any <file> does not appear in the index, treat this as an
  82         error (return 1).
  83
  84 --with-tree=<tree-ish>::
  85         When using --error-unmatch to expand the user supplied
  86         <file> (i.e. path pattern) arguments to paths, pretend
  87         that paths which were removed in the index since the
  88         named <tree-ish> are still present.  Using this option
  89         with `-s` or `-u` options does not make any sense.
  90
  91 -t::
  92         Identify the file status with the following tags (followed by
  93         a space) at the start of each line:
  94         H::     cached
  95         M::     unmerged
  96         R::     removed/deleted
  97         C::     modified/changed
  98         K::     to be killed
  99         ?::     other
 100
 101 -v::
 102         Similar to `-t`, but use lowercase letters for files
 103         that are marked as 'always matching index'.
 104
 105 --full-name::
 106         When run from a subdirectory, the command usually
 107         outputs paths relative to the current directory.  This
 108         option forces paths to be output relative to the project
 109         top directory.
 110
 111 --abbrev[=<n>]::
 112         Instead of showing the full 40-byte hexadecimal object
 113         lines, show only handful hexdigits prefix.
 114         Non default number of digits can be specified with --abbrev=<n>.
 115
 116 \--::
 117         Do not interpret any more arguments as options.
 118
 119 <file>::
 120         Files to show. If no files are given all files which match the other
 121         specified criteria are shown.
 122
 123 Output
 124 ------
 125 show files just outputs the filename unless '--stage' is specified in
 126 which case it outputs:
 127
 128         [<tag> ]<mode> <object> <stage> <file>
 129
 130 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
 131 detailed information on unmerged paths.
 132
 133 For an unmerged path, instead of recording a single mode/SHA1 pair,
 134 the index records up to three such pairs; one from tree O in stage
 135 1, A in stage 2, and B in stage 3.  This information can be used by
 136 the user (or the porcelain) to see what should eventually be recorded at the
 137 path. (see git-read-tree for more information on state)
 138
 139 When `-z` option is not used, TAB, LF, and backslash characters
 140 in pathnames are represented as `\t`, `\n`, and `\\`,
 141 respectively.
 142
 143
 144 Exclude Patterns
 145 ----------------
 146
 147 'git-ls-files' can use a list of "exclude patterns" when
 148 traversing the directory tree and finding files to show when the
 149 flags --others or --ignored are specified.  gitlink:gitignore[5]
 150 specifies the format of exclude patterns.
 151
 152 These exclude patterns come from these places, in order:
 153
 154   1. The command line flag --exclude=<pattern> specifies a
 155      single pattern.  Patterns are ordered in the same order
 156      they appear in the command line.
 157
 158   2. The command line flag --exclude-from=<file> specifies a
 159      file containing a list of patterns.  Patterns are ordered
 160      in the same order they appear in the file.
 161
 162   3. command line flag --exclude-per-directory=<name> specifies
 163      a name of the file in each directory 'git-ls-files'
 164      examines, normally `.gitignore`.  Files in deeper
 165      directories take precedence.  Patterns are ordered in the
 166      same order they appear in the files.
 167
 168 A pattern specified on the command line with --exclude or read
 169 from the file specified with --exclude-from is relative to the
 170 top of the directory tree.  A pattern read from a file specified
 171 by --exclude-per-directory is relative to the directory that the
 172 pattern file appears in.
 173
 174 See Also
 175 --------
 176 gitlink:git-read-tree[1], gitlink:gitignore[5]
 177
 178
 179 Author
 180 ------
 181 Written by Linus Torvalds <torvalds@osdl.org>
 182
 183 Documentation
 184 --------------
 185 Documentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <git@vger.kernel.org>.
 186
 187 GIT
 188 ---
 189 Part of the gitlink:git[7] suite