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] --porcelain 和 git-diff-files[1] --name-status 几乎总是更好的选择；用户应该查看 git-status[1] --short 或 git-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=<格式>

A string that interpolates %(fieldname) from the result being shown. It also interpolates %% to %, and %xXX where XX are hex digits interpolates to character with hex code XX; for example %x00 interpolates to \0 (NUL), %x09 to \t (TAB) and %x0a to \n (LF). --format cannot be combined with -s, -o, -k, -t, --resolve-undo and --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] 指定了排除模式的格式。

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

  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-read-tree[1], gitignore[5]

GIT

属于 git[1] 文档

scroll-to-top