簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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

顯示索引中有解決撤銷資訊的檔案及其解決撤銷資訊。（解決撤銷資訊是用於實現“git checkout -m $PATH”的資訊，即恢復意外解決的合併衝突）

-z

輸出使用 \0 終止，並且不引用檔名。有關更多資訊，請參見下面的 OUTPUT。

--deduplicate

當僅顯示檔名時，抑制由於合併期間有多個暫存區或同時給出 --deleted 和 --modified 選項而可能出現的重複項。當使用 -t、--unmerged 或 --stage 選項之一時，此選項無效。

-x <pattern>
--exclude=<pattern>

跳過匹配模式的未跟蹤檔案。請注意，模式是 shell 萬用字元模式。有關更多資訊，請參見下面的 EXCLUDE PATTERNS。

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

從 <file> 中讀取排除模式；每行一個。

--exclude-per-directory=<file>

從 <file> 中讀取僅適用於目錄及其子目錄的其他排除模式。如果你試圖模仿 Porcelain 命令的工作方式，使用 --exclude-standard 選項會更簡單、更全面。

--exclude-standard

新增標準 Git 排除：.git/info/exclude、每個目錄中的 .gitignore 以及使用者的全域性排除檔案。

--error-unmatch

如果任何 <file> 沒有出現在索引中，則將其視為錯誤（返回 1）。

--with-tree=<span class="hover-term" data-term="tree-ish"><tree-ish></span>

當使用 --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

具有解決撤銷資訊的檔案

-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> 是 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"。

索引中的 <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，在這種情況下它將輸出

[<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 對，而是記錄最多三個這樣的對；一個來自樹 O 在階段 1，A 在階段 2，B 在階段 3。這些資訊可供使用者（或 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，然後指定

  1. core.excludesfile 配置變數指定的檔案，如果存在，或者 $XDG_CONFIG_HOME/git/ignore 檔案。

  2. $GIT_DIR/info/exclude 檔案。

透過 --exclude-from= 選項。

另請參閱

git-read-tree[1], gitignore[5]

GIT

Git[1] 套件的一部分