GIT\-LS\-FILESSection: Git Manual (1)
Index Return to Main Contents
NAMEgit-ls-files - Show information about files in the index and the working tree
git-ls-files [-z] [-t] [-v] (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (-[c|d|o|i|s|u|k|m])* [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--abbrev] [--] [<file>]*
DESCRIPTIONThis merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two.
- Show cached files in the output (default)
- Show deleted files in the output
- Show modified files in the output
- Show other files in the output
- Show ignored files in the output. Note that this also reverses any exclude list present.
- Show stage files in the output
- If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents.
- Do not list empty directories. Has no effect without --directory.
- Show unmerged files in the output (forces --stage)
- Show files on the filesystem that need to be removed due to file/directory conflicts for checkout-index to succeed.
- \0 line termination on output.
- Skips files matching pattern. Note that pattern is a shell wildcard pattern.
- exclude patterns are read from <file>; 1 per line.
- read additional exclude patterns that apply only to the directory and its subdirectories in <file>.
- If any <file> does not appear in the index, treat this as an error (return 1).
- When using --error-unmatch to expand the user supplied <file> (i.e. path pattern) arguments to paths, pretend that paths which were removed in the index since the named <tree-ish> are still present. Using this option with -s or -u options does not make any sense.
Identify the file status with the following tags (followed by a space) at the start of each line:
H cached M unmerged R removed/deleted C modified/changed K to be killed ? other
- Similar to -t, but use lowercase letters for files that are marked as always matching index.
- When run from a subdirectory, the command usually outputs paths relative to the current directory. This option forces paths to be output relative to the project top directory.
- Instead of showing the full 40-byte hexadecimal object lines, show only handful hexdigits prefix. Non default number of digits can be specified with --abbrev=<n>.
- Do not interpret any more arguments as options.
- Files to show. If no files are given all files which match the other specified criteria are shown.
OUTPUTshow files just outputs the filename unless --stage is specified in which case it outputs:
[<tag> ]<mode> <object> <stage> <file>
For an unmerged path, instead of recording a single mode/SHA1 pair, the index records up to three such pairs; one from tree O in stage 1, A in stage 2, and B in stage 3. This information can be used by the user (or the porcelain) to see what should eventually be recorded at the path. (see git-read-tree for more information on state)
EXCLUDE PATTERNSgit-ls-files can use a list of "exclude patterns" when traversing the directory tree and finding files to show when the flags --others or --ignored are specified. gitignore(5) specifies the format of exclude patterns.
These exclude patterns come from these places, in order:
- 1.The command line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order they appear in the command line.
- 2.The command line flag --exclude-from=<file> specifies a file containing a list of patterns. Patterns are ordered in the same order they appear in the file.
- 3.command line flag --exclude-per-directory=<name> specifies a name of the file in each directory git-ls-files examines, normally .gitignore. Files in deeper directories take precedence. Patterns are ordered in the same order they appear in the files.
SEE ALSOgit-read-tree(1), gitignore(5)
AUTHORWritten by Linus Torvalds <firstname.lastname@example.org>
DOCUMENTATIONDocumentation by David Greaves, Junio C Hamano, Josh Triplett, and the git-list <email@example.com>.
GITPart of the git(7) suite