diff options
Diffstat (limited to 'Documentation/git-ls-files.txt')
| -rw-r--r-- | Documentation/git-ls-files.txt | 151 |
1 files changed, 114 insertions, 37 deletions
diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 5298f1bc30..1abdd3c21c 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -10,39 +10,45 @@ SYNOPSIS -------- [verse] 'git ls-files' [-z] [-t] [-v] [-f] - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* - (-[c|d|o|i|s|u|k|m])* - [--eol] + [-c|--cached] [-d|--deleted] [-o|--others] [-i|--ignored] + [-s|--stage] [-u|--unmerged] [-k|--killed] [-m|--modified] + [--resolve-undo] + [--directory [--no-empty-directory]] [--eol] + [--deduplicate] [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--recurse-submodules] - [--abbrev] [--] [<file>...] + [--abbrev[=<n>]] [--format=<format>] [--] [<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. +This merges the file listing in the 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: +shown, and each file may be printed multiple times if there are +multiple entries in the index or multiple statuses are applicable for +the relevant file selection options. OPTIONS ------- -c:: --cached:: - Show cached files in the output (default) + Show all files cached in Git's index, i.e. all tracked files. + (This is the default if no -c/-s/-d/-o/-u/-k/-m/--resolve-undo + options are specified.) -d:: --deleted:: - Show deleted files in the output + Show files with an unstaged deletion -m:: --modified:: - Show modified files in the output + Show files with an unstaged modification (note that an unstaged + deletion also counts as an unstaged modification) -o:: --others:: @@ -50,11 +56,14 @@ OPTIONS -i:: --ignored:: - 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. Standard ignore rules are not automatically activated, - therefore at least one of the `--exclude*` options is required. + Show only ignored files in the output. Must be used with + either an explicit '-c' or '-o'. When showing files in the + index (i.e. when used with '-c'), print only those files + matching an exclude pattern. When showing "other" files + (i.e. when used with '-o'), show only those matched by an + exclude pattern. Standard ignore rules are not automatically + activated, therefore at least one of the `--exclude*` options + is required. -s:: --stage:: @@ -63,24 +72,41 @@ OPTIONS --directory:: If a whole directory is classified as "other", show just its name (with a trailing slash) and not its whole contents. + Has no effect without -o/--others. --no-empty-directory:: Do not list empty directories. Has no effect without --directory. -u:: --unmerged:: - Show unmerged files in the output (forces --stage) + Show information about unmerged files in the output, but do + not show any other tracked files (forces --stage, overrides + --cached). -k:: --killed:: - Show files on the filesystem that need to be removed due - to file/directory conflicts for checkout-index to - succeed. + Show untracked files on the filesystem that need to be removed + due to file/directory conflicts for tracked files to be able to + be written to the filesystem. + +--resolve-undo:: + Show files having resolve-undo information in the index + together with their resolve-undo information. (resolve-undo + information is what is used to implement "git checkout -m + $PATH", i.e. to recreate merge conflicts that were + accidentally resolved) -z:: \0 line termination on output and do not quote filenames. See OUTPUT below for more information. +--deduplicate:: + When only filenames are shown, suppress duplicates that may + come from having multiple stages during a merge, or giving + `--deleted` and `--modified` option at the same time. + When any of the `-t`, `--unmerged`, or `--stage` option is + in use, this option has no effect. + -x <pattern>:: --exclude=<pattern>:: Skip untracked files matching pattern. @@ -93,7 +119,8 @@ OPTIONS --exclude-per-directory=<file>:: Read additional exclude patterns that apply only to the - directory and its subdirectories in <file>. + directory and its subdirectories in <file>. Deprecated; use + --exclude-standard instead. --exclude-standard:: Add the standard Git exclusions: .git/info/exclude, .gitignore @@ -111,23 +138,28 @@ OPTIONS with `-s` or `-u` options does not make any sense. -t:: - This feature is semi-deprecated. For scripting purpose, - linkgit:git-status[1] `--porcelain` and + Show status tags together with filenames. Note that for + scripting purposes, linkgit:git-status[1] `--porcelain` and linkgit:git-diff-files[1] `--name-status` are almost always superior alternatives, and users should look at linkgit:git-status[1] `--short` or linkgit:git-diff[1] `--name-status` for more user-friendly alternatives. + -This option identifies the file status with the following tags (followed by -a space) at the start of each line: - - H:: cached - S:: skip-worktree - M:: unmerged - R:: removed/deleted - C:: modified/changed - K:: to be killed - ?:: other +-- +This option provides a reason for showing each filename, in the form +of a status tag (which is followed by a space and then the filename). +The status tags are all single characters from the following list: + + H:: tracked file that is not either unmerged or skip-worktree + S:: tracked file that is skip-worktree + M:: tracked file that is unmerged + R:: tracked file with unstaged removal/deletion + C:: tracked file with unstaged modification/change + K:: untracked paths which are part of file/directory conflicts + which prevent checking out tracked files + ?:: untracked file + U:: file with resolve-undo information +-- -v:: Similar to `-t`, but use lowercase letters for files @@ -146,12 +178,13 @@ a space) at the start of each line: top directory. --recurse-submodules:: - Recursively calls ls-files on each submodule in the repository. - Currently there is only support for the --cached mode. + Recursively calls ls-files on each active submodule in the repository. + Currently there is only support for the --cached and --stage modes. --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '<n>' + hexdigits long that uniquely refers the object. Non default number of digits can be specified with --abbrev=<n>. --debug:: @@ -177,6 +210,18 @@ Both the <eolinfo> in the index ("i/<eolinfo>") and in the working tree ("w/<eolinfo>") are shown for regular files, followed by the ("attr/<eolattr>"). +--sparse:: + If the index is sparse, show the sparse directories without expanding + to the contained files. Sparse directories will be shown with a + trailing slash, such as "x/" for a sparse directory "x". + +--format=<format>:: + A string that interpolates `%(fieldname)` from the result being shown. + It also interpolates `%%` to `%`, and `%xx` where `xx` are hex digits + interpolates to character with hex code `xx`; for example `%00` + interpolates to `\0` (NUL), `%09` to `\t` (TAB) and %0a to `\n` (LF). + --format cannot be combined with `-s`, `-o`, `-k`, `-t`, `--resolve-undo` + and `--eol`. \--:: Do not interpret any more arguments as options. @@ -208,6 +253,36 @@ quoted as explained for the configuration variable `core.quotePath` (see linkgit:git-config[1]). Using `-z` the filename is output verbatim and the line is terminated by a NUL byte. +It is possible to print in a custom format by using the `--format` +option, which is able to interpolate different fields using +a `%(fieldname)` notation. For example, if you only care about the +"objectname" and "path" fields, you can execute with a specific +"--format" like + + git ls-files --format='%(objectname) %(path)' + +FIELD NAMES +----------- +The way each path is shown can be customized by using the +`--format=<format>` option, where the %(fieldname) in the +<format> string for various aspects of the index entry are +interpolated. The following "fieldname" are understood: + +objectmode:: + The mode of the file which is recorded in the index. +objectname:: + The name of the file which is recorded in the index. +stage:: + The stage of the file which is recorded in the index. +eolinfo:index:: +eolinfo:worktree:: + The <eolinfo> (see the description of the `--eol` option) of + the contents in the index or in the worktree for the path. +eolattr:: + The <eolattr> (see the description of the `--eol` option) + that applies to the path. +path:: + The pathname of the file which is recorded in the index. EXCLUDE PATTERNS ---------------- @@ -217,7 +292,9 @@ traversing the directory tree and finding files to show when the flags --others or --ignored are specified. linkgit:gitignore[5] specifies the format of exclude patterns. -These exclude patterns come from these places, in order: +Generally, you should just use --exclude-standard, but for historical +reasons the exclude patterns can be specified from the following +places, in order: 1. The command-line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order |