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