English ▾ 主題 ▾ 最新版本 ▾ git-status 最後更新於 2.53.0

名稱

git-status - 顯示工作樹狀態

概要

git status [<options>] [--] [<pathspec>…​]

描述

顯示索引檔案與目前 HEAD 提交之間有差異的路徑、工作樹與索引檔案之間有差異的路徑，以及工作樹中未被 Git 追蹤（且未被 gitignore[5] 忽略）的路徑。第一類是執行 git commit 時「將會」提交的檔案；第二與第三類則是執行 git commit 前，先執行 git add 後「可以」提交的檔案。

選項

-s
--short

以簡短格式輸出。

-b
--branch

即使在簡短格式中，也顯示分支與追蹤資訊。

--show-stash

顯示目前儲存（stash）的項目數量。

--porcelain[=<版本>]

以易於指令碼解析的格式輸出。這與簡短輸出類似，但會在 Git 各版本間保持穩定，且不受使用者配置影響。詳細資訊請見下方說明。

<版本> 參數用於指定格式版本。這是選擇性的，預設為原始的 v1 格式。

--long

以詳細格式輸出。這是預設設定。

-v
--verbose

除了已變更檔案的名稱外，還顯示準備提交的文字變更（即類似 git diff --cached 的輸出）。若指定兩次 -v，則還會顯示工作樹中尚未暫存的變更（即類似 git diff 的輸出）。

-u[<模式>]
--untracked-files[=<模式>]

顯示未追蹤的檔案。

模式參數用於指定處理未追蹤檔案的方式。它是選擇性的：預設為 all，若要指定，必須緊貼選項（例如 -uno，而不是 -u no）。

可能的選項有：

no

不顯示未追蹤的檔案。

normal

顯示未追蹤的檔案與目錄。

all

亦顯示未追蹤目錄中的個別檔案。

當未使用 -u 選項時，預設會顯示未追蹤的檔案與目錄（即與指定 normal 相同），以協助您避免忘記加入新建立的檔案。由於在檔案系統中尋找未追蹤檔案需要額外作業，此模式在大型工作樹中可能耗時。若支援，建議啟用未追蹤快取與拆分索引（請參閱 git update-index --untracked-cache 與 git update-index --split-index）。否則，您可以使用 no 讓 git status 更快傳回且不顯示未追蹤檔案。所有布林值 true 的常見寫法皆視為 normal，而 false 則視為 no。

預設值可透過 git-config[1] 中記載的 status.showUntrackedFiles 配置變數進行更改。

--ignore-submodules[=<何時>]

在尋找變更時忽略子模組的變更。<何時> 可以是 none、untracked、dirty 或預設值 all。

none

當子模組包含未追蹤或已修改的檔案，或其 HEAD 與父專案中記錄的提交不同時，即視為已修改。可用於覆蓋 git-config[1] 或 gitmodules[5] 中 ignore 選項的任何設定。

untracked

若子模組僅包含未追蹤的內容，則不被視為髒（dirty）（但仍會掃描是否有已修改的內容）。

dirty

忽略工作樹中子模組的所有變更，僅顯示父專案中所儲存提交的變更（這是 1.7.0 之前的行為）。

all

隱藏子模組的所有變更（且當設定配置選項 status.submoduleSummary 時，會禁止輸出子模組摘要）。

--ignored[=<模式>]

同時顯示已忽略的檔案。

模式參數用於指定處理已忽略檔案的方式。它是選擇性的：預設為 traditional。

可能的選項有：

traditional

顯示已忽略的檔案與目錄，除非指定了 --untracked-files=all，在該情況下會顯示已忽略目錄中的個別檔案。

no

不顯示已忽略的檔案。

matching

顯示符合忽略規則的已忽略檔案與目錄。

會顯示明確符合忽略規則的路徑。如果目錄符合忽略規則，則會顯示該目錄，但不顯示目錄內含的路徑。如果目錄本身不符合規則，但其中所有內容皆被忽略，則不會顯示目錄本身，但會顯示其中所有內容。

-z

以 NUL 字元而非 LF (換行) 來終止項目。若未提供其他格式，這隱含使用 --porcelain=v1 輸出格式。

--column[=<選項>]
--no-column

以欄位方式顯示未追蹤檔案。選項語法請參閱 column.status 配置變數。未帶選項的 --column 與 --no-column 分別等同於 always 與 never。

--ahead-behind
--no-ahead-behind

顯示或不顯示相對於上游分支的詳細領先/落後（ahead/behind）統計。預設值為 true。

--renames
--no-renames

無論使用者配置為何，開啟/關閉重新命名偵測。請參閱 git-diff[1] 的 --no-renames。

--find-renames[=<n>]

開啟重新命名偵測，可選擇設定相似度閾值。請參閱 git-diff[1] 的 --find-renames。

<路徑規格>...

請參閱 gitglossary[7] 中的 pathspec (路徑規格) 條目。

輸出

此指令的輸出旨在作為提交範本的註解。預設的詳細格式旨在易於閱讀、冗長且具有描述性。其內容與格式可能隨時變更。

與許多其他 Git 指令不同，輸出中提到的路徑若您在子目錄中執行，將會是相對於該目錄的路徑（這是刻意設計的，以便於複製貼上）。請參閱下方 status.relativePaths 配置選項。

簡短格式

在簡短格式中，每個路徑的狀態顯示為以下形式之一：

<xy> <path>
<xy> <orig-path> -> <path>

其中 <原始路徑> 是重新命名/複製內容的來源。<原始路徑> 僅在項目被重新命名或複製時顯示。<xy> 為兩個字元的狀態代碼 XY。

欄位（包含 ->）之間以單一空格分隔。如果檔名包含空白或其他不可列印字元，該欄位將以 C 語言字串常值的方式引號標示：以 ASCII 雙引號 (34) 括住，並將內部的特殊字元以反斜線轉義。

此格式顯示三種不同類型的狀態，每種類型使用 <xy> 語法的方式皆不同：

  • 當合併正在發生且成功，或非合併狀態下，X 顯示索引的狀態，Y 顯示工作樹的狀態。

  • 當合併衝突發生且尚未解決時，X 和 Y 顯示相對於共同祖先的各個合併頭（head）所引入的狀態。這些路徑稱為 未合併 (unmerged)。

  • 當路徑為未追蹤時，X 和 Y 總是相同，因為索引對其一無所知。?? 用於未追蹤的路徑。除非使用 --ignored，否則不列出已忽略的檔案；若使用，已忽略的檔案以 !! 指示。

請注意，此處的 合併 一詞也包含使用預設 --merge 策略的重訂（rebase）、揀選（cherry-pick），以及任何其他使用合併機制的操作。

在下表中，這三類狀態分開呈現，且前兩類顯示已追蹤路徑的部分使用以下字元作為 X 和 Y 欄位：

' '

未修改

M

已修改

T

檔案類型已變更（一般檔案、符號連結或子模組）

A

已加入

D

已刪除

R

已重新命名

C

已複製（若配置選項 status.renames 設為 "copies"）

U

已更新但未合併

X Y 含義

[AMD]

未更新

M

[ MTD]

已在索引中更新

T

[ MTD]

索引中類型已變更

A

[ MTD]

已加入索引

D

已從索引刪除

R

[ MTD]

已在索引中重新命名

C

[ MTD]

已在索引中複製

[MTARC]

索引與工作樹匹配

[ MTARC]

M

工作樹自索引後已變更

[ MTARC]

T

工作樹自索引後類型已變更

[ MTARC]

D

工作樹中已刪除

R

工作樹中已重新命名

C

工作樹中已複製

D

D

未合併，雙方皆刪除

A

U

未合併，我方已加入

U

D

未合併，對方已刪除

U

A

未合併，對方已加入

D

U

未合併，我方已刪除

A

A

未合併，雙方皆加入

U

U

未合併，雙方皆修改

?

?

未追蹤

!

!

已忽略

子模組具有更多狀態，改為報告：

M

子模組的 HEAD 與索引中記錄的不一致

m

子模組內容已修改

?

子模組包含未追蹤的檔案

這是因為子模組中修改過的內容或未追蹤檔案，無法透過父專案的 git add 來準備提交。

m 和 ? 會遞迴套用。例如，若子模組中的巢狀子模組包含未追蹤檔案，這也會報告為 ?。

若使用 -b，簡短格式狀態前會有一行

{empty}## <branchname> <tracking-info>

Porcelain 格式版本 1

版本 1 的 porcelain 格式類似於簡短格式，但保證在 Git 版本之間或基於使用者配置時，不會以不向後相容的方式變更。這使其非常適合作為指令碼解析。上述對簡短格式的描述也適用於 porcelain 格式，僅有少數例外：

  1. 使用者的 color.status 配置不被尊重；色彩永遠關閉。

  2. 使用者的 status.relativePaths 配置不被尊重；顯示的路徑永遠相對於儲存庫根目錄。

還有一種替代的 -z 格式推薦用於機器解析。在該格式中，狀態欄位相同，但其他部分有所變更。首先，重新命名條目中省略了 -> 且欄位順序反轉（例如 來源 -> 目的 變為 目的 來源）。其次，每個檔名後跟隨一個 NUL (ASCII 0) 字元，取代空格作為欄位分隔符與終止換行（但狀態欄位與第一個檔名之間仍以空格分隔）。第三，包含特殊字元的檔名不會經過特殊格式化；不會執行任何引號標示或反斜線轉義。

所有子模組變更皆報告為已修改 M，而非 m 或單一 ?。

Porcelain 格式版本 2

版本 2 格式增加了有關工作樹與變更項目狀態的更詳細資訊。版本 2 還定義了一組可擴充且易於解析的選擇性標頭。

標頭行以 # 開頭，並根據特定的命令列參數加入。解析器應忽略不認識的標頭。

分支標頭

若給定 --branch，將列印一系列包含目前分支資訊的標頭行。

行 備註

# branch.oid <提交> | (initial)

目前提交。

# branch.head <分支> | (detached)

目前分支。

# branch.upstream <上游分支>

若已設定上游。

# branch.ab +<領先> -<落後>

若已設定上游且提交存在。

儲存 (Stash) 資訊

若給定 --show-stash，若儲存項目數量非零，將列印一行顯示數量。

# stash <N>

已變更的已追蹤項目

標頭之後，會為已追蹤的項目列印一系列行。根據變更類型，可能會使用三種不同行格式之一來描述項目。已追蹤項目以未定義的順序列印；解析器應允許這三種類型以任何順序混合出現。

一般變更條目格式如下：

1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>

重新命名或複製條目格式如下：

2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
欄位 含義

<XY>

包含簡短格式中所述已暫存與未暫存 XY 值的 2 字元欄位，未變更部分以 "." 而非空格表示。

<sub>

描述子模組狀態的 4 字元欄位。當條目非子模組時為 "N…"。當條目為子模組時為 S<c><m><u>。

  • <c> 若提交變更則為 "C"；否則為 "."。

  • <m> 若有已追蹤變更則為 "M"；否則為 "."。

  • <u> 若有未追蹤變更則為 "U"；否則為 "."。

<mH>

HEAD 中的八進位檔案模式。

<mI>

索引中的八進位檔案模式。

<mW>

工作樹中的八進位檔案模式。

<hH>

HEAD 中的物件名稱。

<hI>

索引中的物件名稱。

<X><score>

重新命名或複製評分（表示移動或複製來源與目標之間的相似度百分比）。例如 "R100" 或 "C75"。

<path>

路徑名稱。在重新命名/複製的條目中，這是目標路徑。

<sep>

當使用 -z 選項時，兩個路徑名稱以 NUL (ASCII 0x00) 位元組分隔；否則以 TAB (ASCII 0x09) 位元組分隔。

<origPath>

HEAD 提交或索引中的路徑名稱。僅在重新命名/複製條目中出現，指出重新命名/複製內容的來源。

未合併條目格式如下；第一個字元為 "u" 以區別於一般變更條目。

u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
欄位 含義

<XY>

描述簡短格式中所述衝突類型的 2 字元欄位。

<sub>

描述上述子模組狀態的 4 字元欄位。

<m1>

階段 1 的八進位檔案模式。

<m2>

階段 2 的八進位檔案模式。

<m3>

階段 3 的八進位檔案模式。

<mW>

工作樹中的八進位檔案模式。

<h1>

階段 1 的物件名稱。

<h2>

階段 2 的物件名稱。

<h3>

階段 3 的物件名稱。

<path>

路徑名稱。

其他項目

在已追蹤條目之後（且若有要求），會為工作樹中發現的未追蹤與已忽略項目列印一系列行。

未追蹤項目格式如下：

? <path>

已忽略項目格式如下：

! <path>

路徑名稱格式備註與 -z

當給定 -z 選項時，路徑名稱照原樣列印且不進行任何引號標示，行以 NUL (ASCII 0x00) 位元組終止。

若無 -z 選項，包含「異常」字元的路徑名稱將按照配置變數 core.quotePath 的說明進行引號標示（請參閱 git-config[1]）。

組態設定 (CONFIGURATION)

此指令會遵守 color.status（或 status.color —兩者意義相同，後者保留為了向後相容）與 color.status.<區塊> 配置變數來為輸出上色。

若配置變數 status.relativePaths 設為 false，則顯示的所有路徑均相對於儲存庫根目錄，而非目前目錄。

若 status.submoduleSummary 設為非零數字或 true（等同於 -1 或無限大），則詳細格式將啟用子模組摘要，並顯示已修改子模組的提交摘要（請參閱 git-submodule[1] 的 --summary-limit 選項）。請注意，當 diff.ignoreSubmodules 設為 all，或針對 submodule.<名稱>.ignore=all 的子模組，status 指令的摘要輸出將被禁止。若要查看被忽略子模組的摘要，您可以使用 --ignore-submodules=dirty 命令列選項或 git submodule summary 指令，該指令顯示相似輸出但不遵循這些設定。

背景重新整理

預設情況下，git status 會自動重新整理索引，從工作樹更新快取的統計資訊並寫入結果。寫入更新後的索引是一種最佳化，並非嚴格必要（status 會自行計算這些值，寫入它們只是為了避免後續程式重複計算）。當 status 在背景執行時，寫入期間持有的鎖定可能會與其他同時進行的處理程序衝突，導致它們失敗。在背景執行 status 的指令碼應考慮使用 git --no-optional-locks status（詳細資訊請見 git[1]）。

未追蹤檔案與效能

如果/當 git status 需要搜尋未追蹤的檔案與目錄時，在大型工作樹中可能會非常緩慢。有許多配置選項可用於透過避免作業或利用先前 Git 指令的快取結果來加速此過程。沒有單一組適合所有人的最佳設定。我們將列出相關選項摘要以協助您，但在閱讀列表之前，您可能想再次執行 git status，因為您的配置可能已經在快取 git status 的結果，因此在後續執行時可能會更快。

  • --untracked-files=no 旗標或 status.showUntrackedFiles=no 配置（上述兩者皆有說明）：表示 git status 不應報告未追蹤的檔案。這是最快的選項。git status 不會列出未追蹤檔案，因此您需要小心記住是否建立了任何新檔案並手動 git add 它們。

  • advice.statusUoption=false（參閱 git-config[1]）：將此變數設為 false 可停用枚舉未追蹤檔案耗時超過 2 秒時給出的警告訊息。在大型專案中，時間可能會更長，且使用者可能已經接受此權衡（例如對使用者來說使用 -uno 可能不是可接受的選項），在這種情況下，發出警告訊息沒有意義，這時停用警告可能是最好的選擇。

  • core.untrackedCache=true（參閱 git-update-index[1]）：啟用未追蹤快取功能，僅搜尋自上次 git status 指令後已修改的目錄。Git 會記住每個目錄內的未追蹤檔案集合，並假設若目錄未修改，則其中的未追蹤檔案集合也未變更。這比枚舉每個目錄的內容快得多，但仍有成本，因為 Git 仍必須搜尋已修改目錄的集合。未追蹤快取儲存在 .git/index 檔案中。搜尋未追蹤檔案的減少成本，會被索引尺寸增加與維護其更新的成本略微抵消。減少的搜尋時間通常值得額外付出的空間。

  • core.untrackedCache=true 與 core.fsmonitor=true 或 core.fsmonitor=<鉤子指令路徑名稱>（參閱 git-update-index[1]）：同時啟用未追蹤快取與 FSMonitor 功能，僅搜尋自上次 git status 指令後已修改的目錄。這比單獨使用未追蹤快取更快，因為 Git 也能避免搜尋已修改的目錄。Git 只需枚舉最近變更的確切目錄集合。雖然 FSMonitor 功能可在未啟用未追蹤快取的情況下使用，但在此情況下其效益會大幅降低。

請注意，在開啟未追蹤快取和/或 FSMonitor 功能後，可能需要執行幾次 git status 指令讓各個快取「暖機」，之後才會看到指令時間改善。這是正常的。

參見

gitignore[5]

GIT

git[1] 套件的一部分