簡體中文 ▾ 主題 ▾ 最新版本 ▾ 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 <模式>
--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=<tree-ish>

當使用 --error-unmatch 將使用者提供的 <檔案>（即路徑模式）引數擴充套件為路徑時，假裝自指定的 <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

帶有解析撤銷資訊的檔案

-v

類似於 -t，但對標記為 *假定未更改* 的檔案使用小寫字母（參見 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=<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] 套件的一部分

scroll-to-top