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

显示未跟踪的文件。

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

也显示忽略的文件。

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 策略的变基 (rebases)、拣选提交 (cherry-picks) 以及任何其他使用合并机制的操作。

在下表中，这三个类别显示在单独的部分中，这些字符用于显示已跟踪路径的前两部分中的 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

瓷器格式版本 1

版本 1 的瓷器格式类似于简短格式，但保证在 Git 版本之间或基于用户配置不会以向后不兼容的方式更改。这使其成为脚本解析的理想选择。上面对简短格式的描述也描述了瓷器格式，但有一些例外

用户的 color.status 配置不受尊重；颜色将始终关闭。
用户的 status.relativePaths 配置不受尊重；显示的路径将始终相对于存储库根目录。

还有一种备用的 -z 格式，建议用于机器解析。在该格式中，状态字段相同，但其他一些内容会发生变化。首先，从重命名条目中省略 ->，并且字段顺序颠倒（例如，from -> to 变为 to from）。其次，NUL (ASCII 0) 跟随每个文件名，替换空格作为字段分隔符和终止换行符（但空格仍然将状态字段与第一个文件名分隔开）。第三，包含特殊字符的文件名不以特殊方式格式化；不执行引用或反斜杠转义。

任何子模块更改都报告为已修改的 M，而不是 m 或单个 ?。

瓷器格式版本 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>

更改的跟踪条目

在标头之后，会为跟踪的条目打印一系列行。可以使用三种不同的行格式之一来描述条目，具体取决于更改的类型。跟踪的条目以未定义的顺序打印；解析器应允许以任何顺序混合使用 3 种行类型。

普通的已更改条目具有以下格式

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 会自动刷新索引，从工作树更新缓存的 stat 信息并写出结果。写出更新的索引是一种优化，并非绝对必要（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] 套件的一部分

设置和配置

获取和创建项目

基本快照

分支和合并

共享和更新项目

检查和比较

打补丁

调试

电子邮件

外部系统

服务器管理

指南

管理

底层命令

名称

概要

描述

选项

输出