English ▾ 主題 ▾ 最新版本 ▾ git-ls-files 最後更新於 2.55.0

名稱

git-ls-files - 顯示索引（index）與工作區中檔案的相關資訊

概要

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

在輸出中顯示暫存內容的模式位元（mode bits）、物件名稱及暫存編號。

--directory

如果整個目錄被歸類為「其他」，僅顯示其名稱（後接斜線），而不顯示其完整內容。若無 -o/--others，此選項無效。

--no-empty-directory

不列出空目錄。若無 --directory，此選項無效。

-u
--unmerged

在輸出中顯示未合併檔案的資訊，但不顯示任何其他被追蹤的檔案（會強制執行 --stage，並覆蓋 --cached）。

-k
--killed

顯示檔案系統上因檔案/目錄衝突而需要刪除的未追蹤檔案，以便將被追蹤的檔案寫入檔案系統。

--resolve-undo

顯示索引中具有「解析-撤銷 (resolve-undo)」資訊的檔案及其資訊。（「解析-撤銷」資訊是用於實作「git checkout -m $PATH」的機制，即重建意外解決的合併衝突）

-z

輸出時以 \0 字元結尾，且不對檔名加引號。更多資訊請參閱下方的「輸出 (OUTPUT)」。

--deduplicate

當僅顯示檔名時，抑制可能因合併期間的多個暫存階段，或同時給予 --deleted 和 --modified 選項而產生的重複項目。當使用 -t、--unmerged 或 --stage 任何選項時，此選項無效。

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

跳過符合模式的未追蹤檔案。請注意，模式是 shell 通用字元模式。更多資訊請參閱下方的「排除模式 (EXCLUDE PATTERNS)」。

-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

被追蹤的檔案，非未合併 (unmerged) 且非跳過工作區 (skip-worktree)

S

被追蹤的檔案，為跳過工作區 (skip-worktree)

M

被追蹤的檔案，為未合併 (unmerged)

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

如果索引是稀疏 (sparse) 的，顯示稀疏目錄而不展開為其中包含的檔案。稀疏目錄將以斜線結尾顯示，例如稀疏目錄 "x" 顯示為 "x/"。

--format=<格式>

一個字串，用於插值從結果中顯示的 %(欄位名稱)。它也將 %% 插值為 %，並將 %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><空格*><TAB><檔案>

git ls-files --unmerged 和 git ls-files --stage 可用於檢查未合併路徑的詳細資訊。

對於未合併的路徑，索引不會記錄單一模式/SHA-1 對，而是記錄最多三個此類對；一個來自 stage 1 的樹狀物件 O，stage 2 的 A，以及 stage 3 的 B。此資訊可供使用者（或 Porcelain）用於查看最終該路徑應記錄什麼內容。（關於狀態的更多資訊，請參閱 git-read-tree[1]）

如果不使用 -z 選項，含有「不尋常」字元的路徑名會按照配置變數 core.quotePath 的說明加上引號（參見 git-config[1]）。使用 -z 時，檔名會按原樣輸出，且該行會以 NUL 位元組結尾。

可以使用 --format 選項以自訂格式列印，該選項能夠使用 %(欄位名稱) 標記法插值不同的欄位。例如，如果您只關心「objectname」和「path」欄位，您可以使用特定的 "--format" 來執行，如下所示：

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

欄位名稱

顯示每個路徑的方式可以透過使用 --format=<格式> 選項進行自訂，其中 <格式> 字串中的 %(欄位名稱) 會對索引條目的各個層面進行插值。可理解下列「欄位名稱」：

objectmode

記錄在索引中的檔案模式。

objecttype

記錄在索引中的檔案物件類型。

objectname

記錄在索引中的檔案名稱。

objectsize[:padded]

記錄在索引中的檔案物件大小（如果物件是 commit 或 tree 則為 "-"）。它也支援 "%(objectsize:padded)" 的填補大小格式。

stage

記錄在索引中的檔案暫存階段。

eolinfo:index
eolinfo:worktree

該路徑在索引或工作區中內容的 <eolinfo>（請參閱 --eol 選項的說明）。

eolattr

適用於該路徑的 <eolattr>（請參閱 --eol 選項的說明）。

path

記錄在索引中的檔案路徑名稱。

排除模式 (EXCLUDE PATTERNS)

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_COMMON_DIR/info/exclude 檔案。

透過 --exclude-from= 選項。

參見

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

GIT

git[1] 套件的一部分