Git
English ▾ 主題 ▾ 最新版本 ▾ 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 <pattern>
--exclude=<pattern>

略過符合模式的未追蹤檔案。請注意，模式是 shell 萬用字元模式。有關更多資訊，請參閱下方的排除模式。

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

未合併或跳過工作樹的追蹤檔案

S

跳過工作樹的追蹤檔案

M

未合併的追蹤檔案

R

具有未暫存移除/刪除的追蹤檔案

C

具有未暫存修改/變更的追蹤檔案

K

屬於檔案/目錄衝突一部分的未追蹤路徑，這些衝突會阻止簽出追蹤的檔案

?

未追蹤的檔案

U

具有 resolve-undo 資訊的檔案

-v

與 -t 類似，但是對標記為假設未變更的檔案使用小寫字母 (請參閱 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>。當 "text" 屬性為 "auto" (或未設定且 core.autocrlf 不為 false) 時，<eolinfo> 是 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，在這種情況下它會輸出

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

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。使用者（或瓷器）可以使用此資訊來查看最終應在路徑上記錄的內容。（有關狀態的更多資訊，請參閱 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

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

排除模式

當指定了 --others 或 --ignored 旗標時，git ls-files 可以在遍歷目錄樹並尋找要顯示的檔案時使用「排除模式」清單。gitignore[5] 指定了排除模式的格式。

這些排除模式可以依以下順序從以下位置指定

  1. 命令列旗標 --exclude=<pattern> 指定單一模式。模式的順序與它們在命令列中出現的順序相同。

  2. 命令列旗標 --exclude-from=<file> 指定一個包含模式清單的檔案。模式的順序與它們在檔案中出現的順序相同。

  3. 命令列旗標 --exclude-per-directory=<name> 指定 git ls-files 檢查的每個目錄中檔案的名稱，通常是 .gitignore。較深目錄中的檔案具有優先權。模式的順序與它們在檔案中出現的順序相同。

在命令列中使用 --exclude 指定或從使用 --exclude-from 指定的檔案中讀取的模式，是相對於目錄樹頂層的。從 --exclude-per-directory 指定的檔案中讀取的模式，是相對於模式檔案所在的目錄。

通常，當您希望排除規則的應用方式與瓷器命令相同時，您應該能夠使用 --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