简体中文 ▾ 主题 ▾ 最新版本 ▾ git-ls-files 最后更新于 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 <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[=<n>]] [--format=<format>] [--] [<file>…​]

描述

该命令将索引中的文件列表与实际工作目录列表合并，并显示两者的不同组合。

可以使用多个标志来确定显示哪些文件。如果索引中有多个条目，或者相关的文件选择选项适用于多个状态，则每个文件可能会被多次打印。

选项

-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

显示索引中具有 resolve-undo 信息的文件及其 resolve-undo 信息。（resolve-undo 信息是用于实现 “git checkout -m $PATH” 的内容，即重新创建被意外解决的合并冲突）

-z

输出以 \0 终止，且不对文件名加引号。更多信息请参阅下方的“输出”部分。

--deduplicate

当仅显示文件名时，抑制可能因合并期间存在多个阶段，或同时提供 --deleted 和 --modified 选项而产生的重复项。当使用 -t、--unmerged 或 --stage 选项时，此选项无效。

-x <模式>
--exclude=<模式>

跳过匹配模式的未跟踪文件。注意，模式是 shell 通配符模式。更多信息请参阅下方的“排除模式”。

-X <文件>
--exclude-from=<文件>

从 <文件> 中读取排除模式；每行一个。

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

已跟踪文件，既未合并也未 skip-worktree

S

已跟踪文件，且为 skip-worktree

M

已跟踪文件，且未合并

R

已跟踪文件，具有未暂存的移除/删除

C

已跟踪文件，具有未暂存的修改/变更

K

未跟踪的路径，属于阻止检出已跟踪文件的文件/目录冲突的一部分

?

未跟踪文件

U

具有 resolve-undo 信息的文件

-v

类似于 -t，但对于标记为 *assume unchanged* 的文件使用小写字母（请参阅 git-update-index[1]）。

-f

类似于 -t，但对于标记为 *fsmonitor valid* 的文件使用小写字母（请参阅 git-update-index[1]）。

--full-name

从子目录运行此命令时，通常会输出相对于当前目录的路径。此选项强制路径相对于项目顶级目录输出。

--recurse-submodules

递归地在仓库中的每个活跃子模块上调用 ls-files。目前仅支持 --cached 和 --stage 模式。

--abbrev[=<n>]

不显示完整的 40 字节十六进制对象行，而是显示至少 <n> 个十六进制数字长的最短前缀，该前缀唯一地指代该对象。可以使用 --abbrev=<n> 指定非默认的数字位数。

--debug

在描述文件的每一行之后，添加有关其缓存条目的更多数据。这旨在显示尽可能多的信息以供人工检查；确切格式可能会随时更改。

--eol

显示文件的 <eolinfo> 和 <eolattr>。<eolinfo> 是当“text”属性为 “auto”（或未设置且 core.autocrlf 不为 false）时 Git 使用的文件内容标识符。<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"。

常规文件的索引中的 <eolinfo> ("i/<eolinfo>") 和工作树中的 <eolinfo> ("w/<eolinfo>") 都会被显示，后跟 ("attr/<eolattr>")。

--sparse

如果索引是稀疏的，则显示稀疏目录而不展开为包含的文件。稀疏目录将以末尾斜杠显示，例如稀疏目录 "x" 显示为 "x/"。

--format=<格式>

一个从显示结果中插入 %(fieldname) 的字符串。它还将 %% 插入为 %，将 %xXX（其中 XX 是十六进制数字）插入为十六进制代码为 XX 的字符；例如 %x00 插入为 \0 (NUL)，%x09 插入为 \t (TAB)，%x0a 插入为 \n (LF)。--format 不能与 -s、-o、-k、-t、--resolve-undo 和 --eol 结合使用。

--

不再将任何后续参数解释为选项。

<文件>

要显示的文件。如果未给出文件，则显示所有匹配其他指定条件的文件。

输出

git ls-files 仅输出文件名，除非指定了 --stage，此时它会输出

[<tag> ]<mode> <object> <stage> <file>

git ls-files --eol 将显示 i/<eolinfo><空格>w/<eolinfo><空格>attr/<eolattr><空格*><制表符><文件>

git ls-files --unmerged 和 git ls-files --stage 可用于查看有关未合并路径的详细信息。

对于未合并的路径，索引记录最多三个此类对，而不是记录单个模式/SHA-1 对；一个是来自阶段 1 的树 O，来自阶段 2 的 A，以及来自阶段 3 的 B。此信息可由用户（或 Porcelain 工具）用于查看最终应在路径处记录的内容。（有关状态的更多信息，请参阅 git-read-tree[1]）

如果不使用 -z 选项，则具有“特殊”字符的路径名将像 core.quotePath 配置变量（参见 git-config[1]）中解释的那样被引用。使用 -z 时，文件名将按原样输出，行以 NUL 字节结束。

可以通过使用 --format 选项以自定义格式打印，该选项能够使用 %(fieldname) 表示法插入不同的字段。例如，如果您只关心 “objectname” 和 “path” 字段，则可以执行特定的 "--format" 如下

git ls-files --format='%(objectname) %(path)'

字段名称

每个路径的显示方式可以通过使用 --format=<格式> 选项进行自定义，其中 <格式> 字符串中的 %(fieldname) 会根据索引条目的各个方面进行插入。支持以下 “fieldname”

objectmode

记录在索引中的文件模式。

objecttype

记录在索引中的文件对象类型。

objectname

记录在索引中的文件名。

objectsize[:padded]

记录在索引中的文件对象大小（如果对象是 commit 或 tree，则为 "-"）。它还支持使用 "%(objectsize: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] 套件的一部分