Setup and Config
Getting and Creating Projects
Basic Snapshotting
Branching and Merging
Sharing and Updating Projects
Inspection and Comparison
Patching
Debugging
External Systems
Server Admin
Guides
- gitattributes
- Command-line interface conventions
- Everyday Git
- Frequently Asked Questions (FAQ)
- Glossary
- Hooks
- gitignore
- gitmodules
- Revisions
- Submodules
- Tutorial
- Workflows
- All guides...
Administration
Plumbing Commands
- 2.46.2 no changes
- 2.46.1 09/13/24
- 2.44.1 → 2.46.0 no changes
- 2.44.0 02/23/24
- 2.43.1 → 2.43.5 no changes
- 2.43.0 11/20/23
- 2.42.1 → 2.42.3 no changes
- 2.42.0 08/21/23
- 2.40.1 → 2.41.2 no changes
- 2.40.0 03/12/23
- 2.39.1 → 2.39.5 no changes
- 2.39.0 12/12/22
- 2.38.1 → 2.38.5 no changes
- 2.38.0 10/02/22
- 2.36.1 → 2.37.7 no changes
- 2.36.0 04/18/22
- 2.35.1 → 2.35.8 no changes
- 2.35.0 01/24/22
- 2.31.1 → 2.34.8 no changes
- 2.31.0 03/15/21
- 2.30.2 → 2.30.9 no changes
- 2.30.1 02/08/21
- 2.30.0 12/27/20
- 2.27.1 → 2.29.3 no changes
- 2.27.0 06/01/20
- 2.22.1 → 2.26.3 no changes
- 2.22.0 06/07/19
- 2.18.1 → 2.21.4 no changes
- 2.18.0 06/21/18
- 2.17.0 → 2.17.6 no changes
- 2.16.6 12/06/19
- 2.14.6 → 2.15.4 no changes
- 2.13.7 05/22/18
- 2.12.5 no changes
- 2.11.4 09/22/17
- 2.10.5 09/22/17
- 2.9.5 07/30/17
- 2.8.6 07/30/17
- 2.2.3 → 2.7.6 no changes
- 2.1.4 12/17/14
- 2.0.5 12/17/14
概述
git ls-files [-z] [-t] [-v] [-f] [-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 <模式>|--exclude=<模式>] [-X <文件>|--exclude-from=<文件>] [--exclude-per-directory=<文件>] [--exclude-standard] [--error-unmatch] [--with-tree=<树状对象>] [--full-name] [--recurse-submodules] [--abbrev[=<n>]] [--format=<格式>] [--] [<文件>…]
选项
- -c
- --cached
-
显示 Git 索引中缓存的所有文件,即所有被跟踪的文件。 (如果没有指定 -c/-s/-d/-o/-u/-k/-m/--resolve-undo 选项,默认情况下是这样。)
- -d
- --deleted
-
显示未分阶段删除的文件
- -m
- --modified
-
显示未暂存修改的文件(注意,未暂存删除也算作未暂存修改)
- -o
- --others
-
在输出中显示其他(即未跟踪)文件
- -i
- --ignored
-
在输出中只显示忽略的文件。 必须与明确的 -c 或 -o 一起使用。 显示索引中的文件时(即与 -c 一起使用时),只打印与排除模式匹配的文件。 显示 “其他” 文件时(即与 -o 一起使用时),只显示与排除模式匹配的文件。 标准忽略规则不会自动激活,因此至少需要一个
--exclude*
选项。 - -s
- --stage
-
在输出中显示暂存内容的模式位、对象名称和阶段编号。
- --directory
-
如果整个目录被归类为 “其他”,则只显示其名称(带尾部斜线),而不显示其全部内容。 不使用 -o/--others 时无效。
- --no-empty-directory
-
不列出空目录。不使用 --directory 时无效。
- -u
- --unmerged
-
在输出中显示未合并文件的信息,但不显示任何其他跟踪文件(强制执行 --stage 命令,覆盖 --cached 命令)。
- -k
- --killed
-
显示文件系统中由于文件/目录冲突而需要删除的未跟踪文件,以便跟踪文件能够写入文件系统。
- --resolve-undo
-
在索引中显示有解决 --undo 信息的文件及其解决 --undo 信息。 (解决 --undo 信息用于执行 "git checkout -m $PATH",即重新创建意外解决的合并冲突)
- -z
-
输出时以 \0 行结束,文件名不加引号。 更多信息,请参阅下面的输出一节。
- --deduplicate
-
当只显示文件名时,抑制在合并过程中出现多个阶段,或同时给出
--deleted
和--modified
选项时可能出现的重复。 当使用-t
,--unmerged
或--stage
选项时,此选项不起作用。 - -x <模式>
- --exclude=<模式>
-
跳过与模式匹配的未跟踪文件。 请注意,pattern 是 shell 通配符模式。更多信息,请参阅下面的 EXCLUDE PATTERNS。
- -X <文件>
- --exclude-from=<文件>
-
从 <文件> 中读取排除模式;每行 1 个。
- --exclude-per-directory=<文件>
-
读取仅适用于 <文件> 中目录及其子目录的附加排除模式。如果你想模仿 Porcelain 命令的工作方式,使用
--exclude-standard
选项会更简单、更彻底。 - --exclude-standard
-
添加标准的 Git 排除文件:.git/info/exclude、每个目录中的 .gitignore,以及用户的全局排除文件。
- --error-unmatch
-
如果索引中没有出现任何 <文件> 文件,则将其视为错误(返回 1)。
- --with-tree=<树状对象>
-
当使用 --error-unmatch 将用户提供的 <文件> (即路径模式)参数扩展为路径时,假定自命名为 <树状对象> 后在索引中删除的路径仍然存在。 将此选项与
-s
或-u
选项一起使用没有任何意义。 - -t
-
与文件名一起显示状态标签。 请注意,就脚本而言,git-status[1]
--porcelain
和 git-diff-files[1]--name-status
几乎总是更好的选择;用户应该查看 git-status[1]--short
或 git-diff[1]--name-status
,以获得更友好的选择。 - -v
-
与
-t
选项类似,但标记为 assume unchanged 的文件使用小写字母(参见 git-update-index[1])。 - -f
-
与
-t
类似,但标记为 fsmonitor 有效的文件使用小写字母(参见 git-update-index[1])。 - --full-name
-
当从一个子目录运行时,该命令通常会输出相对于当前目录的路径。 这个选项强制输出相对于项目顶层目录的路径。
- --recurse-submodules
-
在仓库中的每个活动子模块上递归调用 ls-files。 目前只支持 --cached 和 --stage 模式。
- --abbrev[=<n>]
-
不显示完整的 40 字节十六进制对象行,而是显示至少 <n> 个十六进制数字长度的最短前缀,该前缀唯一指向对象。 可以使用 --abbrev=<n> 指定非默认位数。
- --debug
-
在描述文件的每一行后,添加有关其缓存项的更多数据。 这样做的目的是显示尽可能多的信息,以方便人工检查;具体格式可能随时更改。
- --eol
-
显示文件的 <eolinfo> 和 <eolattr>。 <eolinfo> 是 Git 在 "text" 属性为 "auto"(或未设置且 core.autocrlf 不为 false)时使用的文件内容标识。 <eolinfo> 可以是 "-text"、"none"、"lf"、"crlf"、"mixed" 或 ""。
"" 表示该文件不是普通文件,不在索引中或在工作区中无法访问。
<eolattr> 是签出或提交时使用的属性,可以是 ""、"-text"、"text"、"text=auto"、"text eol=lf"、"text eol=crlf"。 Git 2.10 支持 "text=auto eol=lf" 和 "text=auto eol=crlf"。
对于常规文件,索引("i/<eolinfo>")中的 <eolinfo> 和工作树( "w/<eolinfo>" )中的 <eolinfo> 都会显示,其后是( "attr/<eolattr>" )。
- --sparse
-
如果索引是稀疏的,则显示稀疏目录,而不扩展到包含的文件。稀疏目录将以斜线显示,如 "x/" 表示稀疏目录 "x"。
- --format=<格式>
-
一个字符串,从显示的结果中插值出
%(字段名)
。 它还将%%
内插到%
,将%xx
内插到十六进制代码为xx
的字符;例如,将%00
内插到\0
(NUL),将%09
内插到\t
(TAB),将 %0a 内插到\n
(LF)。 --format 选项不能与`-s`、-o
、-k
、-t
、--resolve-undo
和--eol
选项结合使用。 - --
-
不将之后的参数解释为选项。
- <文件>
-
要显示的文件。如果没有给出文件,则会显示符合其他指定条件的所有文件。
输出
git ls-files 只输出文件名,除非指定了 --stage
选项,在这种情况下才输出:
[<标签> ]<模式> <对象> <暂存> <文件>
git ls-files --eol will show i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><文件>
git ls-files --unmerged 和 git ls-files --stage 可以用来检查未合并路径的详细信息。
对于未合并的路径,索引不会记录单个模式/SHA-1 对,而是最多记录三个此类对;一个来自第一阶段的目录树 O,一个来自第二阶段的目录树 A,一个来自第三阶段的目录树 B。 用户(或上层命令)可以利用这些信息来查看路径上最终应该记录的内容。(有关状态的更多信息,请参阅 git-read-tree[1])
如果没有 -z
选项,带 “不常见” 字符的路径名会被加上引号,正如配置变量 core.quotePath
所解释的那样(参见 git-config[1])。 使用 -z
选项,文件名将被逐字输出,并以 NUL 字节结束。
使用 --format
选项可以自定义打印格式,该选项可以使用 %(fieldname)
符号对不同字段进行插值。例如,如果只关心 “对象名” 和 “路径” 字段,可以使用特定的 "--format" 执行,如
git ls-files --format='%(对象名) %(路径)'
字段名
每个路径的显示方式可以通过使用 `--format=<格式>`选项进行自定义,在该选项中,<格式> 字符串中用于索引条目的不同方面的 %(字段名) 将被插值。 可以理解以下 “字段名”:
- objectmode
-
索引中记录的文件模式。
- objecttype
-
索引中记录的文件对象类型。
- objectname
-
索引中记录的文件名。
- objectsize[:padded]
-
索引中记录的文件对象大小(如果对象是
commit
或tree
,则为 "-")。 它还支持 "%(objectize:padded)" 的填充大小格式。 - stage
-
索引中记录的文件阶段。
- eolinfo:index
- eolinfo:worktree
-
路径的索引或工作树中内容的 <eolinfo>(参见
--eol
选项的说明)。 - eolattr
-
适用于路径的 <eolattr>(参见
--eol
选项的说明)。 - path
-
索引中记录的文件路径名。
排除模式
git ls-files 在遍历目录树时可以使用 “排除模式” 列表,并在指定—others 或—ignored 标志时查找要显示的文件。 gitignore[5] 指定了排除模式的格式。
这些排除模式可依次在以下位置指定:
-
命令行标志 --exclude=<模式> 可指定单一模式。 模式的排列顺序与命令行中出现的顺序相同。
-
命令行标志 --exclude-from=<文件> 可指定一个包含模式列表的文件。 模式的排列顺序与它们在文件中出现的顺序相同。
-
命令行标志 --exclude-per-directory=<名称> 指定了 git ls-files 检查的每个目录中的文件名,通常是
.gitignore
。 深目录中的文件优先。 模式的排列顺序与文件中出现的顺序相同。
在命令行中用 --exclude 指定的模式或从用 --exclude-from 指定的文件中读取的模式是相对于目录树顶层的。 通过 --exclude-per-directory 指定的文件读取的模式是相对于模式文件所在目录的。
一般来说,当你希望排除规则的应用方式与 Porcelain 命令相同时,可以使用 --exclude-standard
。要模仿 --exclude-standard`指定的方式,可以给出 `--exclude-per-directory=.gitignore
,然后指定:
-
配置变量
core.excludesfile
指定的文件(如果存在),或$XDG_CONFIG_HOME/git/ignore
文件。 -
$GIT_DIR/info/exclude
文件。
通过 --exclude-from=
选项。
GIT
属于 git[1] 文档