255 lines
7.4 KiB
Plaintext
255 lines
7.4 KiB
Plaintext
git-ls-files(1)
|
|
===============
|
|
|
|
NAME
|
|
----
|
|
git-ls-files - Information about files in the index/working directory
|
|
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'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]
|
|
[--full-name] [--abbrev] [--] [<file>]\*
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
This merges the file listing in the directory cache index with the
|
|
actual working directory list, and shows different combinations of the
|
|
two.
|
|
|
|
One or more of the options below may be used to determine the files
|
|
shown:
|
|
|
|
OPTIONS
|
|
-------
|
|
-c|--cached::
|
|
Show cached files in the output (default)
|
|
|
|
-d|--deleted::
|
|
Show deleted files in the output
|
|
|
|
-m|--modified::
|
|
Show modified files in the output
|
|
|
|
-o|--others::
|
|
Show other files in the output
|
|
|
|
-i|--ignored::
|
|
Show ignored files in the output
|
|
Note the this also reverses any exclude list present.
|
|
|
|
-s|--stage::
|
|
Show stage files in the output
|
|
|
|
--directory::
|
|
If a whole directory is classified as "other", show just its
|
|
name (with a trailing slash) and not its whole contents.
|
|
|
|
--no-empty-directory::
|
|
Do not list empty directories. Has no effect without --directory.
|
|
|
|
-u|--unmerged::
|
|
Show unmerged files in the output (forces --stage)
|
|
|
|
-k|--killed::
|
|
Show files on the filesystem that need to be removed due
|
|
to file/directory conflicts for checkout-index to
|
|
succeed.
|
|
|
|
-z::
|
|
\0 line termination on output.
|
|
|
|
-x|--exclude=<pattern>::
|
|
Skips files matching pattern.
|
|
Note that pattern is a shell wildcard pattern.
|
|
|
|
-X|--exclude-from=<file>::
|
|
exclude patterns are read from <file>; 1 per line.
|
|
|
|
--exclude-per-directory=<file>::
|
|
read additional exclude patterns that apply only to the
|
|
directory and its subdirectories in <file>.
|
|
|
|
--error-unmatch::
|
|
If any <file> does not appear in the index, treat this as an
|
|
error (return 1).
|
|
|
|
-t::
|
|
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
|
|
|
|
-v::
|
|
Similar to `-t`, but use lowercase letters for files
|
|
that are marked as 'always matching index'.
|
|
|
|
--full-name::
|
|
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.
|
|
|
|
--abbrev[=<n>]::
|
|
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.
|
|
|
|
<file>::
|
|
Files to show. If no files are given all files which match the other
|
|
specified criteria are shown.
|
|
|
|
Output
|
|
------
|
|
show files just outputs the filename unless '--stage' is specified in
|
|
which case it outputs:
|
|
|
|
[<tag> ]<mode> <object> <stage> <file>
|
|
|
|
"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine
|
|
detailed information on unmerged paths.
|
|
|
|
For an unmerged path, instead of recording a single mode/SHA1 pair,
|
|
the dircache 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)
|
|
|
|
When `-z` option is not used, TAB, LF, and backslash characters
|
|
in pathnames are represented as `\t`, `\n`, and `\\`,
|
|
respectively.
|
|
|
|
|
|
Exclude Patterns
|
|
----------------
|
|
|
|
'git-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.
|
|
|
|
These exclude patterns come from these places:
|
|
|
|
1. command line flag --exclude=<pattern> specifies a single
|
|
pattern.
|
|
|
|
2. command line flag --exclude-from=<file> specifies a list of
|
|
patterns stored in a file.
|
|
|
|
3. command line flag --exclude-per-directory=<name> specifies
|
|
a name of the file in each directory 'git-ls-files'
|
|
examines, and if exists, its contents are used as an
|
|
additional list of patterns.
|
|
|
|
An exclude pattern file used by (2) and (3) contains one pattern
|
|
per line. A line that starts with a '#' can be used as comment
|
|
for readability.
|
|
|
|
There are three lists of patterns that are in effect at a given
|
|
time. They are built and ordered in the following way:
|
|
|
|
* --exclude=<pattern> from the command line; patterns are
|
|
ordered in the same order as they appear on the command line.
|
|
|
|
* lines read from --exclude-from=<file>; patterns are ordered
|
|
in the same order as they appear in the file.
|
|
|
|
* When --exclude-per-directory=<name> is specified, upon
|
|
entering a directory that has such a file, its contents are
|
|
appended at the end of the current "list of patterns". They
|
|
are popped off when leaving the directory.
|
|
|
|
Each pattern in the pattern list specifies "a match pattern" and
|
|
optionally the fate; either a file that matches the pattern is
|
|
considered excluded or included. A filename is matched against
|
|
the patterns in the three lists; the --exclude-from list is
|
|
checked first, then the --exclude-per-directory list, and then
|
|
finally the --exclude list. The last match determines its fate.
|
|
If there is no match in the three lists, the fate is "included".
|
|
|
|
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.
|
|
|
|
An exclude pattern is of the following format:
|
|
|
|
- an optional prefix '!' which means that the fate this pattern
|
|
specifies is "include", not the usual "exclude"; the
|
|
remainder of the pattern string is interpreted according to
|
|
the following rules.
|
|
|
|
- if it does not contain a slash '/', it is a shell glob
|
|
pattern and used to match against the filename without
|
|
leading directories.
|
|
|
|
- otherwise, it is a shell glob pattern, suitable for
|
|
consumption by fnmatch(3) with FNM_PATHNAME flag. I.e. a
|
|
slash in the pattern must match a slash in the pathname.
|
|
"Documentation/\*.html" matches "Documentation/git.html" but
|
|
not "ppc/ppc.html". As a natural exception, "/*.c" matches
|
|
"cat-file.c" but not "mozilla-sha1/sha1.c".
|
|
|
|
An example:
|
|
|
|
--------------------------------------------------------------
|
|
$ cat .git/ignore
|
|
# ignore objects and archives, anywhere in the tree.
|
|
*.[oa]
|
|
$ cat Documentation/.gitignore
|
|
# ignore generated html files,
|
|
*.html
|
|
# except foo.html which is maintained by hand
|
|
!foo.html
|
|
$ git-ls-files --ignored \
|
|
--exclude='Documentation/*.[0-9]' \
|
|
--exclude-from=.git/ignore \
|
|
--exclude-per-directory=.gitignore
|
|
--------------------------------------------------------------
|
|
|
|
Another example:
|
|
|
|
--------------------------------------------------------------
|
|
$ cat .gitignore
|
|
vmlinux*
|
|
$ ls arch/foo/kernel/vm*
|
|
arch/foo/kernel/vmlinux.lds.S
|
|
$ echo '!/vmlinux*' >arch/foo/kernel/.gitignore
|
|
--------------------------------------------------------------
|
|
|
|
The second .gitignore keeps `arch/foo/kernel/vmlinux.lds.S` file
|
|
from getting ignored.
|
|
|
|
|
|
See Also
|
|
--------
|
|
gitlink:git-read-tree[1]
|
|
|
|
|
|
Author
|
|
------
|
|
Written by Linus Torvalds <torvalds@osdl.org>
|
|
|
|
Documentation
|
|
--------------
|
|
Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
|
|
|
|
GIT
|
|
---
|
|
Part of the gitlink:git[7] suite
|
|
|