Pro Git 中文版

Appearance

git-ls-files ​

显示索引和工作树中文件的信息。

概要 ​

txt
'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, --exclude* ​

在输出中仅显示被忽略的文件。必须与显式的 '-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 <pattern>, --exclude=<pattern> ​

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

-X <file>, --exclude-from=<file> ​

从 <file> 读取排除模式；每行一个。

--exclude-per-directory=<file> ​

：读取仅适用于目录及其子目录的附加排除模式。如果您试图模仿 Porcelain 命令的工作方式，使用 --exclude-standard 选项更容易也更彻底。

--exclude-standard ​

：添加标准 Git 排除：.git/info/exclude、每个目录中的 .gitignore 以及用户的全局排除文件。

--error-unmatch ​

：如果任何 <file> 未出现在索引中，将此视为错误（返回 1）。

--with-tree=<tree-ish> ​

：使用 --error-unmatch 展开用户提供的 <file>（即路径模式）参数为路径时，假装在指定的 <tree-ish> 之后在索引中删除的路径仍然存在。与 -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>] ​

：显示最短的唯一引用对象的前缀（至少 '<n>' 个十六进制数字长），而不是完整的 40 字节十六进制对象行。可以通过 --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=<format> ​

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

-- ​

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

<file> ​

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

输出 ​

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

    [&lt;tag&gt; ]&lt;mode&gt; &lt;object&gt; &lt;stage&gt; &lt;file&gt;

'git ls-files --eol' 将显示 i/<eolinfo><SPACES>w/<eolinfo><SPACES>attr/<eolattr><SPACE*><TAB><file>

'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=<format> 选项自定义，其中 <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=<pattern> 指定单个模式。模式按命令行中出现的顺序排列。

  2. 命令行标志 --exclude-from=<file> 指定包含模式列表的文件。模式按文件中出现的顺序排列。

  3. 命令行标志 --exclude-per-directory=<name> 指定 'git ls-files' 检查的每个目录中的文件名，通常是 .gitignore。更深层目录中的文件优先。模式按文件中出现的顺序排列。

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

通常，当您希望排除规则与 Porcelain 命令应用的方式相同时，应能够使用 --exclude-standard。要模拟 --exclude-standard 指定的内容，您可以给出 --exclude-per-directory=.gitignore，然后通过 --exclude-from= 选项指定：

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

  2. $GIT_COMMON_DIR/info/exclude 文件。

另请参阅 ​

git-read-tree(1)、gitignore(5)

Git ​

git(1) 套件的一部分

基于 CC BY-NC-SA 3.0 许可发布

Pro Git 中文版