'\" t .\" Title: git-ls-files .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.76.1 .\" Date: 03/19/2016 .\" Manual: Git Manual .\" Source: Git 1.7.10.4 .\" Language: English .\" .TH "GIT\-LS\-FILES" "1" "03/19/2016" "Git 1\&.7\&.10\&.4" "Git Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" git-ls-files \- Show information about files in the index and the working tree .SH "SYNOPSIS" .sp .nf \fIgit ls\-files\fR [\-z] [\-t] [\-v] (\-\-[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (\-[c|d|o|i|s|u|k|m])* [\-x |\-\-exclude=] [\-X |\-\-exclude\-from=] [\-\-exclude\-per\-directory=] [\-\-exclude\-standard] [\-\-error\-unmatch] [\-\-with\-tree=] [\-\-full\-name] [\-\-abbrev] [\-\-] [\&...] .fi .sp .SH "DESCRIPTION" .sp This merges the file listing in the directory cache index with the actual working directory list, and shows different combinations of the two\&. .sp One or more of the options below may be used to determine the files shown: .SH "OPTIONS" .PP \-c, \-\-cached .RS 4 Show cached files in the output (default) .RE .PP \-d, \-\-deleted .RS 4 Show deleted files in the output .RE .PP \-m, \-\-modified .RS 4 Show modified files in the output .RE .PP \-o, \-\-others .RS 4 Show other (i\&.e\&. untracked) files in the output .RE .PP \-i, \-\-ignored .RS 4 Show only ignored files in the output\&. When showing files in the index, print only those matched by an exclude pattern\&. When showing "other" files, show only those matched by an exclude pattern\&. .RE .PP \-s, \-\-stage .RS 4 Show staged contents\*(Aq object name, mode bits and stage number in the output\&. .RE .PP \-\-directory .RS 4 If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents\&. .RE .PP \-\-no\-empty\-directory .RS 4 Do not list empty directories\&. Has no effect without \-\-directory\&. .RE .PP \-u, \-\-unmerged .RS 4 Show unmerged files in the output (forces \-\-stage) .RE .PP \-k, \-\-killed .RS 4 Show files on the filesystem that need to be removed due to file/directory conflicts for checkout\-index to succeed\&. .RE .PP \-z .RS 4 \e0 line termination on output\&. .RE .PP \-x , \-\-exclude= .RS 4 Skip untracked files matching pattern\&. Note that pattern is a shell wildcard pattern\&. See EXCLUDE PATTERNS below for more information\&. .RE .PP \-X , \-\-exclude\-from= .RS 4 Read exclude patterns from ; 1 per line\&. .RE .PP \-\-exclude\-per\-directory= .RS 4 Read additional exclude patterns that apply only to the directory and its subdirectories in \&. .RE .PP \-\-exclude\-standard .RS 4 Add the standard git exclusions: \&.git/info/exclude, \&.gitignore in each directory, and the user\(cqs global exclusion file\&. .RE .PP \-\-error\-unmatch .RS 4 If any does not appear in the index, treat this as an error (return 1)\&. .RE .PP \-\-with\-tree= .RS 4 When using \-\-error\-unmatch to expand the user supplied (i\&.e\&. path pattern) arguments to paths, pretend that paths which were removed in the index since the named are still present\&. Using this option with \-s or \-u options does not make any sense\&. .RE .PP \-t .RS 4 This feature is semi\-deprecated\&. For scripting purpose, \fBgit-status\fR(1) \-\-porcelain and \fBgit-diff-files\fR(1) \-\-name\-status are almost always superior alternatives, and users should look at \fBgit-status\fR(1) \-\-short or \fBgit-diff\fR(1) \-\-name\-status for more user\-friendly alternatives\&. .sp This option identifies the file status with the following tags (followed by a space) at the start of each line: .RE .PP H .RS 4 cached .RE .PP S .RS 4 skip\-worktree .RE .PP M .RS 4 unmerged .RE .PP R .RS 4 removed/deleted .RE .PP C .RS 4 modified/changed .RE .PP K .RS 4 to be killed .RE .PP ? .RS 4 other .RE .PP \-v .RS 4 Similar to \-t, but use lowercase letters for files that are marked as \fIassume unchanged\fR (see \fBgit-update-index\fR(1))\&. .RE .PP \-\-full\-name .RS 4 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\&. .RE .PP \-\-abbrev[=] .RS 4 Instead of showing the full 40\-byte hexadecimal object lines, show only a partial prefix\&. Non default number of digits can be specified with \-\-abbrev=\&. .RE .PP \-\-debug .RS 4 After each line that describes a file, add more data about its cache entry\&. This is intended to show as much information as possible for manual inspection; the exact format may change at any time\&. .RE .PP \-\- .RS 4 Do not interpret any more arguments as options\&. .RE .PP .RS 4 Files to show\&. If no files are given all files which match the other specified criteria are shown\&. .RE .SH "OUTPUT" .sp \fIgit ls\-files\fR just outputs the filenames unless \fI\-\-stage\fR is specified in which case it outputs: .sp .if n \{\ .RS 4 .\} .nf [ ] .fi .if n \{\ .RE .\} .sp \fIgit ls\-files \-\-unmerged\fR and \fIgit ls\-files \-\-stage\fR can be used to examine detailed information on unmerged paths\&. .sp 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 \fBgit-read-tree\fR(1) for more information on state) .sp When \-z option is not used, TAB, LF, and backslash characters in pathnames are represented as \et, \en, and \e\e, respectively\&. .SH "EXCLUDE PATTERNS" .sp \fIgit ls\-files\fR 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\&. \fBgitignore\fR(5) specifies the format of exclude patterns\&. .sp These exclude patterns come from these places, in order: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} The command line flag \-\-exclude= specifies a single pattern\&. Patterns are ordered in the same order they appear in the command line\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} The command line flag \-\-exclude\-from= specifies a file containing a list of patterns\&. Patterns are ordered in the same order they appear in the file\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} The command line flag \-\-exclude\-per\-directory= specifies a name of the file in each directory \fIgit ls\-files\fR examines, normally \&.gitignore\&. Files in deeper directories take precedence\&. Patterns are ordered in the same order they appear in the files\&. .RE .sp A pattern specified on the command line with \-\-exclude or read from the file specified with \-\-exclude\-from is relative to the top of the directory tree\&. A pattern read from a file specified by \-\-exclude\-per\-directory is relative to the directory that the pattern file appears in\&. .SH "SEE ALSO" .sp \fBgit-read-tree\fR(1), \fBgitignore\fR(5) .SH "GIT" .sp Part of the \fBgit\fR(1) suite