Git

git-status 最後更新於 2.45.0

名稱

git-status - 顯示工作區狀態

概要

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

描述

顯示索引檔案與當前 HEAD 提交之間有差異的路徑，工作區與索引檔案之間有差異的路徑，以及工作區中未被 Git 跟蹤（且未被 gitignore[5] 忽略）的路徑。第一種是執行 git commit 將要提交的內容；第二種和第三種是執行 git commit 之前透過執行 git add 可以提交的內容。

選項

-s

--short

以短格式輸出。

-b

--branch

即使是短格式，也顯示分支和跟蹤資訊。

--show-stash

顯示當前暫存條目的數量。

--porcelain[=<version>]

以易於指令碼解析的格式輸出。這類似於短格式輸出，但在 Git 版本之間和使用者配置下保持穩定。詳情見下文。

版本引數用於指定格式版本。這是可選的，預設為原始版本 v1 格式。

--long

以長格式輸出。這是預設設定。

-v

--verbose

除了顯示已更改檔案的名稱外，還顯示已暫存待提交的文字更改（即，類似於 git diff --cached 的輸出）。如果指定兩次 -v，則還顯示工作區中尚未暫存的更改（即，類似於 git diff 的輸出）。

-u[<mode>]

--untracked-files[=<mode>]

顯示未跟蹤的檔案。

模式引數用於指定未跟蹤檔案的處理方式。它是可選的：預設為 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[=<when>]

查詢更改時忽略子模組的更改。<when> 可以是 "none"、"untracked"、"dirty" 或 "all"（預設值）。使用 "none" 將在子模組包含未跟蹤檔案或修改檔案，或者其 HEAD 與超級專案中記錄的提交不同時，將其視為已修改，並可用於覆蓋 git-config[1] 或 gitmodules[5] 中 ignore 選項的任何設定。當使用 "untracked" 時，如果子模組只包含未跟蹤內容，則不將其視為髒（但仍會掃描其修改內容）。使用 "dirty" 忽略子模組工作區的所有更改，只顯示超級專案中儲存的提交的更改（這是 1.7.0 之前的行為）。使用 "all" 隱藏所有子模組的更改（並在設定了配置選項 status.submoduleSummary 時抑制子模組摘要的輸出）。

--ignored[=<mode>]

也顯示被忽略的檔案。

模式引數用於指定被忽略檔案的處理方式。它是可選的：預設為 traditional。

可能的選項是

traditional - 顯示被忽略的檔案和目錄，除非指定了 --untracked-files=all，在這種情況下，將顯示被忽略目錄中的單個檔案。
no - 不顯示被忽略的檔案。
matching - 顯示與忽略模式匹配的被忽略檔案和目錄。

當指定 matching 模式時，將顯示明確匹配忽略模式的路徑。如果一個目錄匹配忽略模式，則顯示該目錄，但不顯示該忽略目錄中包含的路徑。如果一個目錄不匹配忽略模式，但所有內容都被忽略，則不顯示該目錄，但顯示所有內容。

-z

用 NUL 終止條目，而不是 LF。如果沒有給出其他格式，這意味著 --porcelain=v1 輸出格式。

--column[=<options>]

--no-column

以列顯示未跟蹤檔案。有關選項語法，請參見配置變數 column.status。--column 和不帶選項的 --no-column 分別等同於 always 和 never。

--ahead-behind

--no-ahead-behind

顯示或不顯示分支相對於其上游分支的詳細領先/落後計數。預設為 true。

--renames

--no-renames

無論使用者配置如何，開啟/關閉重新命名檢測。另請參見 git-diff[1] --no-renames。

--find-renames[=<n>]

開啟重新命名檢測，可選地設定相似度閾值。另請參見 git-diff[1] --find-renames。

<pathspec>…

請參閱 gitglossary[7] 中的 pathspec 條目。

輸出

此命令的輸出旨在用作提交模板註釋。預設的長格式旨在人類可讀、詳細和描述性強。其內容和格式可能隨時更改。

輸出中提到的路徑，與許多其他 Git 命令不同，如果您在子目錄中工作，則它們是相對於當前目錄的（這是故意的，有助於剪下和貼上）。請參閱下面的 status.relativePaths 配置選項。

短格式

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

XY PATH
XY ORIG_PATH -> PATH

其中 ORIG_PATH 是重新命名/複製內容來自的原始路徑。ORIG_PATH 僅在條目被重新命名或複製時顯示。XY 是兩位狀態碼。

欄位（包括 ->）之間用一個空格分隔。如果檔名包含空白或其他不可列印字元，則該欄位將以 C 字串文字的方式引用：由 ASCII 雙引號（34）字元包圍，內部特殊字元用反斜槓轉義。

使用此格式顯示三種不同型別的狀態，每種都以不同的方式使用 XY 語法

當合並正在發生且合併成功時，或在合併情況之外，X 顯示索引的狀態，Y 顯示工作區的狀態。
當發生合併衝突且尚未解決時，X 和 Y 顯示每個合併頭相對於共同祖先引入的狀態。這些路徑被稱為 未合併。
當路徑未被跟蹤時，X 和 Y 總是相同的，因為它們對索引是未知的。?? 用於未跟蹤的路徑。除非使用 --ignored，否則不會列出被忽略的檔案；如果使用，被忽略的檔案用 !! 表示。

請注意，此處的合併術語還包括使用預設 --merge 策略進行的變基、cherry-pick 以及任何其他使用合併機制的操作。

在下表中，這三類在單獨的部分中顯示，這些字元用於顯示跟蹤路徑的前兩個部分的 X 和 Y 欄位

' ' = 未修改
M = 已修改
T = 檔案型別已更改（普通檔案、符號連結或子模組）
A = 已新增
D = 已刪除
R = 已重新命名
C = 已複製（如果配置選項 status.renames 設定為 "copies"）
U = 已更新但未合併

X          Y     Meaning
-------------------------------------------------
	 [AMD]   not updated
M        [ MTD]  updated in index
T        [ MTD]  type changed in index
A        [ MTD]  added to index
D                deleted from index
R        [ MTD]  renamed in index
C        [ MTD]  copied in index
[MTARC]          index and work tree matches
[ MTARC]    M    work tree changed since index
[ MTARC]    T    type changed in work tree since index
[ MTARC]    D    deleted in work tree
	    R    renamed in work tree
	    C    copied in work tree
-------------------------------------------------
D           D    unmerged, both deleted
A           U    unmerged, added by us
U           D    unmerged, deleted by them
U           A    unmerged, added by them
D           U    unmerged, deleted by us
A           A    unmerged, both added
U           U    unmerged, both modified
-------------------------------------------------
?           ?    untracked
!           !    ignored
-------------------------------------------------

子模組有更多狀態並報告

M = 子模組的 HEAD 與索引中記錄的不同
m = 子模組有修改的內容
? = 子模組有未跟蹤的檔案

這是因為子模組中修改的內容或未跟蹤的檔案無法透過超級專案中的 git add 新增以準備提交。

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

如果使用 -b，則短格式狀態前面會有一行

## branchname tracking info

Porcelain 格式版本 1

版本 1 porcelain 格式類似於短格式，但保證在 Git 版本之間或基於使用者配置不會發生向後不相容的更改。這使其非常適合指令碼解析。上述短格式的描述也適用於 porcelain 格式，但有以下幾個例外

不遵守使用者的 color.status 配置；顏色將始終關閉。
不遵守使用者的 status.relativePaths 配置；顯示的路徑將始終相對於倉庫根目錄。

還有一個建議用於機器解析的替代 -z 格式。在該格式中，狀態欄位相同，但其他一些內容發生了變化。首先，重新命名條目中的 -> 被省略，並且欄位順序顛倒（例如 from -> to 變為 to from）。其次，每個檔名後跟一個 NUL（ASCII 0），取代空格作為欄位分隔符和終止換行符（但空格仍然分隔狀態欄位和第一個檔名）。第三，包含特殊字元的檔名沒有特殊格式；不執行引號或反斜槓轉義。

任何子模組更改都報告為已修改 M，而不是 m 或單個 ?。

Porcelain 格式版本 2

版本 2 格式增加了關於工作區狀態和已更改專案的更詳細資訊。版本 2 還定義了一組可擴充套件的、易於解析的可選標頭。

標頭行以 "#" 開頭，並根據特定的命令列引數新增。解析器應忽略它們無法識別的標頭。

分支標頭

如果給定 --branch，則列印一系列標頭行，其中包含有關當前分支的資訊。

Line                                     Notes
------------------------------------------------------------
# branch.oid <commit> | (initial)        Current commit.
# branch.head <branch> | (detached)      Current branch.
# branch.upstream <upstream-branch>      If upstream is set.
# branch.ab +<ahead> -<behind>           If upstream is set and
					 the commit is present.
------------------------------------------------------------

暫存資訊

如果給定 --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>

Field       Meaning
--------------------------------------------------------
<XY>        A 2 character field containing the staged and
	    unstaged XY values described in the short format,
	    with unchanged indicated by a "." rather than
	    a space.
<sub>       A 4 character field describing the submodule state.
	    "N..." when the entry is not a submodule.
	    "S<c><m><u>" when the entry is a submodule.
	    <c> is "C" if the commit changed; otherwise ".".
	    <m> is "M" if it has tracked changes; otherwise ".".
	    <u> is "U" if there are untracked changes; otherwise ".".
<mH>        The octal file mode in HEAD.
<mI>        The octal file mode in the index.
<mW>        The octal file mode in the worktree.
<hH>        The object name in HEAD.
<hI>        The object name in the index.
<X><score>  The rename or copy score (denoting the percentage
	    of similarity between the source and target of the
	    move or copy). For example "R100" or "C75".
<path>      The pathname.  In a renamed/copied entry, this
	    is the target path.
<sep>       When the `-z` option is used, the 2 pathnames are separated
	    with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
	    byte separates them.
<origPath>  The pathname in the commit at HEAD or in the index.
	    This is only present in a renamed/copied entry, and
	    tells where the renamed/copied contents came from.
--------------------------------------------------------

未合併的條目具有以下格式；第一個字元是 "u"，以區別於普通更改的條目。

u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>

Field       Meaning
--------------------------------------------------------
<XY>        A 2 character field describing the conflict type
	    as described in the short format.
<sub>       A 4 character field describing the submodule state
	    as described above.
<m1>        The octal file mode in stage 1.
<m2>        The octal file mode in stage 2.
<m3>        The octal file mode in stage 3.
<mW>        The octal file mode in the worktree.
<h1>        The object name in stage 1.
<h2>        The object name in stage 2.
<h3>        The object name in stage 3.
<path>      The pathname.
--------------------------------------------------------

其他專案

在跟蹤條目之後（如果請求），將列印一系列行，用於工作區中找到的未跟蹤專案，然後是被忽略的專案。

未跟蹤專案具有以下格式

? <path>

被忽略專案具有以下格式

! <path>

路徑名格式注意事項和 -z

當給出 -z 選項時，路徑名按原樣列印，不帶任何引用，並且行以 NUL (ASCII 0x00) 位元組終止。

如果沒有 -z 選項，則包含“不尋常”字元的路徑名將按照配置變數 core.quotePath 的解釋進行引用（參見 git-config[1]）。

配置

該命令遵循 color.status（或 status.color — 它們含義相同，後者是為了向後相容而保留）和 color.status.<slot> 配置變數來對輸出著色。

如果配置變數 status.relativePaths 設定為 false，則顯示的所有路徑都是相對於倉庫根目錄的，而不是相對於當前目錄的。

如果 status.submoduleSummary 設定為非零數字或 true（等同於 -1 或無限數字），則長格式的子模組摘要將被啟用，並顯示修改過的子模組的提交摘要（參見 git-submodule[1] 的 --summary-limit 選項）。請注意，當 diff.ignoreSubmodules 設定為 all 或僅當 submodule.<name>.ignore=all 時，狀態命令的摘要輸出將對所有子模組被抑制。要檢視被忽略子模組的摘要，您可以使用 --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=<hook-command-pathname>（參見 git-update-index[1]）：同時啟用未跟蹤快取和 FSMonitor 功能，並且只搜尋自上次 git status 命令以來已修改的目錄。這比單獨使用未跟蹤快取更快，因為 Git 還可以避免搜尋已修改的目錄。Git 只需列舉最近已更改的精確目錄集。雖然可以在不啟用未跟蹤快取的情況下啟用 FSMonitor 功能，但在這種情況下，收益會大大降低。

請注意，啟用未跟蹤快取和/或 FSMonitor 功能後，可能需要執行幾次 git status 命令才能使各種快取預熱，然後才能看到命令時間的改善。這是正常的。

另請參閱

gitignore[5]

Git[1] 套件的一部分

設定和配置

獲取和建立專案

基本快照

分支與合併

共享和更新專案

檢查和比較

打補丁

除錯

電子郵件

外部系統

伺服器管理

指南

管理

底層命令

名稱

概要

描述

選項

輸出

短格式