Git
简体中文 ▾ Topics ▾ Latest version ▾ git-ls-files last updated in 2.46.1

名称

git-ls-files - 显示索引和工作目录树中的文件信息

概述

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] --porcelaingit-diff-files[1] --name-status 几乎总是更好的选择;用户应该查看 git-status[1] --shortgit-diff[1] --name-status,以获得更友好的选择。

该选项以状态标记(后跟空格,然后是文件名)的形式提供了显示每个文件名的理由。 状态标记均为以下列表中的单字符:

H

未合并或未跳过工作区的跟踪文件

S

跳过工作区的跟踪文件

M

未合并的跟踪文件

R

未分阶段移除/删除的跟踪文件

C

跟踪的文件有未暂存的修改/更改

K

未跟踪路径,这些路径是文件/目录冲突的一部分,妨碍了跟踪文件的检出

?

显示未追踪文件

U

文件中的 resolve-undo 信息

-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 --unmergedgit 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]

索引中记录的文件对象大小(如果对象是 committree,则为 "-")。 它还支持 "%(objectize:padded)" 的填充大小格式。

stage

索引中记录的文件阶段。

eolinfo:index
eolinfo:worktree

路径的索引或工作树中内容的 <eolinfo>(参见 --eol 选项的说明)。

eolattr

适用于路径的 <eolattr>(参见 --eol 选项的说明)。

path

索引中记录的文件路径名。

排除模式

git ls-files 在遍历目录树时可以使用 “排除模式” 列表,并在指定—​others 或—​ignored 标志时查找要显示的文件。 gitignore[5] 指定了排除模式的格式。

这些排除模式可依次在以下位置指定:

  1. 命令行标志 --exclude=<模式> 可指定单一模式。 模式的排列顺序与命令行中出现的顺序相同。

  2. 命令行标志 --exclude-from=<文件> 可指定一个包含模式列表的文件。 模式的排列顺序与它们在文件中出现的顺序相同。

  3. 命令行标志 --exclude-per-directory=<名称> 指定了 git ls-files 检查的每个目录中的文件名,通常是 .gitignore。 深目录中的文件优先。 模式的排列顺序与文件中出现的顺序相同。

在命令行中用 --exclude 指定的模式或从用 --exclude-from 指定的文件中读取的模式是相对于目录树顶层的。 通过 --exclude-per-directory 指定的文件读取的模式是相对于模式文件所在目录的。

一般来说,当你希望排除规则的应用方式与 Porcelain 命令相同时,可以使用 --exclude-standard。要模仿 --exclude-standard`指定的方式,可以给出 `--exclude-per-directory=.gitignore,然后指定:

  1. 配置变量 core.excludesfile 指定的文件(如果存在),或 $XDG_CONFIG_HOME/git/ignore 文件。

  2. $GIT_DIR/info/exclude 文件。

通过 --exclude-from= 选项。

GIT

属于 git[1] 文档

scroll-to-top