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]
  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 the 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 -t::
  85         Identify the file status with the following tags (followed by
  86         a space) at the start of each line:
  87         H::     cached
  88         M::     unmerged
  89         R::     removed/deleted
  90         C::     modified/changed
  91         K::     to be killed
  92         ?::     other
  93
  94 -v::
  95         Similar to `-t`, but use lowercase letters for files
  96         that are marked as 'always matching index'.
  97
  98 --full-name::
  99         When run from a subdirectory, the command usually
 100         outputs paths relative to the current directory.  This
 101         option forces paths to be output relative to the project
 102         top directory.
 103
 104 --abbrev[=<n>]::
 105         Instead of showing the full 40-byte hexadecimal object
 106         lines, show only handful hexdigits prefix.
 107         Non default number of digits can be specified with --abbrev=<n>.
 108
 109 \--::
 110         Do not interpret any more arguments as options.
 111
 112 <file>::
 113         Files to show. If no files are given all files which match the other
 114         specified criteria are shown.
 115
 116 Output
 117 ------
 118 show files just outputs the filename unless '--stage' is specified in
 119 which case it outputs:
 120
 121         [<tag> ]<mode> <object> <stage> <file>
 122
 123 "git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
 124 detailed information on unmerged paths.
 125
 126 For an unmerged path, instead of recording a single mode/SHA1 pair,
 127 the dircache records up to three such pairs; one from tree O in stage
 128 1, A in stage 2, and B in stage 3.  This information can be used by
 129 the user (or the porcelain) to see what should eventually be recorded at the
 130 path. (see git-read-tree for more information on state)
 131
 132 When `-z` option is not used, TAB, LF, and backslash characters
 133 in pathnames are represented as `\t`, `\n`, and `\\`,
 134 respectively.
 135
 136
 137 Exclude Patterns
 138 ----------------
 139
 140 'git-ls-files' can use a list of "exclude patterns" when
 141 traversing the directory tree and finding files to show when the
 142 flags --others or --ignored are specified.
 143
 144 These exclude patterns come from these places:
 145
 146   1. command line flag --exclude=<pattern> specifies a single
 147      pattern.
 148
 149   2. command line flag --exclude-from=<file> specifies a list of
 150      patterns stored in a file.
 151
 152   3. command line flag --exclude-per-directory=<name> specifies
 153      a name of the file in each directory 'git-ls-files'
 154      examines, and if exists, its contents are used as an
 155      additional list of patterns.
 156
 157 An exclude pattern file used by (2) and (3) contains one pattern
 158 per line.  A line that starts with a '#' can be used as comment
 159 for readability.
 160
 161 There are three lists of patterns that are in effect at a given
 162 time.  They are built and ordered in the following way:
 163
 164  * --exclude=<pattern> from the command line; patterns are
 165    ordered in the same order as they appear on the command line.
 166
 167  * lines read from --exclude-from=<file>; patterns are ordered
 168    in the same order as they appear in the file.
 169
 170  * When --exclude-per-directory=<name> is specified, upon
 171    entering a directory that has such a file, its contents are
 172    appended at the end of the current "list of patterns".  They
 173    are popped off when leaving the directory.
 174
 175 Each pattern in the pattern list specifies "a match pattern" and
 176 optionally the fate; either a file that matches the pattern is
 177 considered excluded or included.  A filename is matched against
 178 the patterns in the three lists; the --exclude-from list is
 179 checked first, then the --exclude-per-directory list, and then
 180 finally the --exclude list. The last match determines its fate.
 181 If there is no match in the three lists, the fate is "included".
 182
 183 A pattern specified on the command line with --exclude or read
 184 from the file specified with --exclude-from is relative to the
 185 top of the directory tree.  A pattern read from a file specified
 186 by --exclude-per-directory is relative to the directory that the
 187 pattern file appears in.
 188
 189 An exclude pattern is of the following format:
 190
 191  - an optional prefix '!' which means that the fate this pattern
 192    specifies is "include", not the usual "exclude"; the
 193    remainder of the pattern string is interpreted according to
 194    the following rules.
 195
 196  - if it does not contain a slash '/', it is a shell glob
 197    pattern and used to match against the filename without
 198    leading directories.
 199
 200  - otherwise, it is a shell glob pattern, suitable for
 201    consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
 202    slash in the pattern must match a slash in the pathname.
 203    "Documentation/\*.html" matches "Documentation/git.html" but
 204    not "ppc/ppc.html".  As a natural exception, "/*.c" matches
 205    "cat-file.c" but not "mozilla-sha1/sha1.c".
 206
 207 An example:
 208
 209 --------------------------------------------------------------
 210     $ cat .git/info/exclude
 211     # ignore objects and archives, anywhere in the tree.
 212     *.[oa]
 213     $ cat Documentation/.gitignore
 214     # ignore generated html files,
 215     *.html
 216     # except foo.html which is maintained by hand
 217     !foo.html
 218     $ git-ls-files --ignored \
 219         --exclude='Documentation/*.[0-9]' \
 220         --exclude-from=.git/info/exclude \
 221         --exclude-per-directory=.gitignore
 222 --------------------------------------------------------------
 223
 224 Another example:
 225
 226 --------------------------------------------------------------
 227     $ cat .gitignore
 228     vmlinux*
 229     $ ls arch/foo/kernel/vm*
 230     arch/foo/kernel/vmlinux.lds.S
 231     $ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
 232 --------------------------------------------------------------
 233
 234 The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file
 235 from getting ignored.
 236
 237
 238 See Also
 239 --------
 240 gitlink:git-read-tree[1]
 241
 242
 243 Author
 244 ------
 245 Written by Linus Torvalds <torvalds@osdl.org>
 246
 247 Documentation
 248 --------------
 249 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 250
 251 GIT
 252 ---
 253 Part of the gitlink:git[7] suite
 254