Documentation / git-ls-files.txton commit Merge branch 'jc/rebase-limit' (8fa40aa)
   1git-ls-files(1)
   2===============
   3
   4NAME
   5----
   6git-ls-files - Information about files in the index/working directory
   7
   8
   9SYNOPSIS
  10--------
  11'git-ls-files' [-z] [-t]
  12                (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
  13                (-[c|d|o|i|s|u|k|m])\*
  14                [-x <pattern>|--exclude=<pattern>]
  15                [-X <file>|--exclude-from=<file>]
  16                [--exclude-per-directory=<file>] 
  17                [--full-name] [--] [<file>]\*
  18
  19DESCRIPTION
  20-----------
  21This merges the file listing in the directory cache index with the
  22actual working directory list, and shows different combinations of the
  23two.
  24
  25One or more of the options below may be used to determine the files
  26shown:
  27
  28OPTIONS
  29-------
  30-c|--cached::
  31        Show cached files in the output (default)
  32
  33-d|--deleted::
  34        Show deleted files in the output
  35
  36-m|--modified::
  37        Show modified files in the output
  38
  39-o|--others::
  40        Show other files in the output
  41
  42-i|--ignored::
  43        Show ignored files in the output
  44        Note the this also reverses any exclude list present.
  45
  46-s|--stage::
  47        Show stage files in the output
  48
  49--directory::
  50        If a whole directory is classified as "other", show just its
  51        name (with a trailing slash) and not its whole contents.
  52
  53-u|--unmerged::
  54        Show unmerged files in the output (forces --stage)
  55
  56-k|--killed::
  57        Show files on the filesystem that need to be removed due
  58        to file/directory conflicts for checkout-index to
  59        succeed.
  60
  61-z::
  62        \0 line termination on output.
  63
  64-x|--exclude=<pattern>::
  65        Skips files matching pattern.
  66        Note that pattern is a shell wildcard pattern.
  67
  68-X|--exclude-from=<file>::
  69        exclude patterns are read from <file>; 1 per line.
  70
  71--exclude-per-directory=<file>::
  72        read additional exclude patterns that apply only to the
  73        directory and its subdirectories in <file>.
  74
  75-t::
  76        Identify the file status with the following tags (followed by
  77        a space) at the start of each line:
  78        H::     cached
  79        M::     unmerged
  80        R::     removed/deleted
  81        C::     modified/changed
  82        K::     to be killed
  83        ?::     other
  84
  85--full-name::
  86        When run from a subdirectory, the command usually
  87        outputs paths relative to the current directory.  This
  88        option forces paths to be output relative to the project
  89        top directory.
  90
  91--::
  92        Do not interpret any more arguments as options.
  93
  94<file>::
  95        Files to show. If no files are given all files which match the other
  96        specified criteria are shown.
  97
  98Output
  99------
 100show files just outputs the filename unless '--stage' is specified in
 101which case it outputs:
 102
 103        [<tag> ]<mode> <object> <stage> <file>
 104
 105"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
 106detailed information on unmerged paths.
 107
 108For an unmerged path, instead of recording a single mode/SHA1 pair,
 109the dircache records up to three such pairs; one from tree O in stage
 1101, A in stage 2, and B in stage 3.  This information can be used by
 111the user (or the porcelain) to see what should eventually be recorded at the
 112path. (see git-read-tree for more information on state)
 113
 114When `-z` option is not used, TAB, LF, and backslash characters
 115in pathnames are represented as `\t`, `\n`, and `\\`,
 116respectively.
 117
 118
 119Exclude Patterns
 120----------------
 121
 122'git-ls-files' can use a list of "exclude patterns" when
 123traversing the directory tree and finding files to show when the
 124flags --others or --ignored are specified.
 125
 126These exclude patterns come from these places:
 127
 128  1. command line flag --exclude=<pattern> specifies a single
 129     pattern.
 130
 131  2. command line flag --exclude-from=<file> specifies a list of
 132     patterns stored in a file.
 133
 134  3. command line flag --exclude-per-directory=<name> specifies
 135     a name of the file in each directory 'git-ls-files'
 136     examines, and if exists, its contents are used as an
 137     additional list of patterns.
 138
 139An exclude pattern file used by (2) and (3) contains one pattern
 140per line.  A line that starts with a '#' can be used as comment
 141for readability.
 142
 143There are three lists of patterns that are in effect at a given
 144time.  They are built and ordered in the following way:
 145
 146 * --exclude=<pattern> from the command line; patterns are
 147   ordered in the same order as they appear on the command line.
 148
 149 * lines read from --exclude-from=<file>; patterns are ordered
 150   in the same order as they appear in the file.
 151
 152 * When --exclude-per-directory=<name> is specified, upon
 153   entering a directory that has such a file, its contents are
 154   appended at the end of the current "list of patterns".  They
 155   are popped off when leaving the directory.
 156
 157Each pattern in the pattern list specifies "a match pattern" and
 158optionally the fate; either a file that matches the pattern is
 159considered excluded or included.  A filename is matched against
 160the patterns in the three lists; the --exclude-from list is
 161checked first, then the --exclude-per-directory list, and then
 162finally the --exclude list. The last match determines its fate.
 163If there is no match in the three lists, the fate is "included".
 164
 165A pattern specified on the command line with --exclude or read
 166from the file specified with --exclude-from is relative to the
 167top of the directory tree.  A pattern read from a file specified
 168by --exclude-per-directory is relative to the directory that the
 169pattern file appears in.
 170
 171An exclude pattern is of the following format:
 172
 173 - an optional prefix '!' which means that the fate this pattern
 174   specifies is "include", not the usual "exclude"; the
 175   remainder of the pattern string is interpreted according to
 176   the following rules.
 177
 178 - if it does not contain a slash '/', it is a shell glob
 179   pattern and used to match against the filename without
 180   leading directories (i.e. the same way as the current
 181   implementation).
 182
 183 - otherwise, it is a shell glob pattern, suitable for
 184   consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
 185   slash in the pattern must match a slash in the pathname.
 186   "Documentation/\*.html" matches "Documentation/git.html" but
 187   not "ppc/ppc.html".  As a natural exception, "/*.c" matches
 188   "cat-file.c" but not "mozilla-sha1/sha1.c".
 189
 190An example:
 191
 192--------------------------------------------------------------
 193    $ cat .git/ignore
 194    # ignore objects and archives, anywhere in the tree.
 195    *.[oa]
 196    $ cat Documentation/.gitignore
 197    # ignore generated html files,
 198    *.html
 199    # except foo.html which is maintained by hand
 200    !foo.html
 201    $ git-ls-files --ignored \
 202        --exclude='Documentation/*.[0-9]' \
 203        --exclude-from=.git/ignore \
 204        --exclude-per-directory=.gitignore
 205--------------------------------------------------------------
 206
 207
 208See Also
 209--------
 210gitlink:git-read-tree[1]
 211
 212
 213Author
 214------
 215Written by Linus Torvalds <torvalds@osdl.org>
 216
 217Documentation
 218--------------
 219Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 220
 221GIT
 222---
 223Part of the gitlink:git[7] suite
 224