简体中文 ▾ Topics ▾ Latest version ▾ git-status last updated in 2.53.0

名称

git-status - 显示工作区状态

概述

git status' [<选项>…​] [--] [<路径规范>…​]

描述

显示索引文件和当前HEAD提交有差异的路径，工作区和索引文件有差异的路径，以及工作区中不被Git追踪的路径（也不被gitignore[5]忽略）。前者是你通过运行 "git commit "会提交的东西；第二和第三者是你在运行 "git commit "之前通过运行 "git add "可以提交的东西。

选项

-s
--short

以简短的形式给出输出。

-b
--branch

即使在短文中也要显示分支和跟踪信息。

--show-stash

显示目前藏匿的条目数量。

--porcelain[=<版本>]

以易于解析的格式给出脚本的输出。 这类似于简短的输出，但在不同的Git版本中，无论用户配置如何，都会保持稳定。详见下文。

版本参数用于指定格式版本。 这是可选的，默认为原始版本的 "v1 "格式。

--long

给出长格式的输出。这是默认的。

-v
--verbose

除了显示被修改的文件名外，还显示被分阶段提交的文本修改（即，像`git diff --cached`的输出）。如果`-v`被指定了两次，那么也会显示工作区中尚未分阶段的变化（即，像`git diff`的输出）。

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

显示未追踪文件。

模式参数用于指定对未跟踪文件的处理。 它是可选的：默认为 "所有"，如果指定，必须与选项卡在一起（例如，-uno，但不是`-u no`）。

可选项：

no

显示未追踪文件。

normal

normal - 显示未被追踪的文件和目录

all

all - 也显示未被追踪的目录中的单个文件。

当不使用`-u`选项时，将显示未跟踪的文件和目录（即与指定`normal`相同），以帮助你避免忘记添加新创建的文件。 因为在文件系统中寻找未跟踪的文件需要额外的工作，在一个大的工作区中，这种模式可能需要一些时间。 如果支持的话，考虑启用无痕缓存和分割索引（见`git update-index --untracked-cache`和`git update-index --split-index`），否则你可以使用`no`来让`git status`更快地返回而不显示无痕文件。

默认值可以用git-config[1]中记载的 status.showUntrackedFiles 配置变量来改变。

--ignore-submodules[=<when>]

在查找更改时忽略对子模块的更改。<when> 可以是 none、untracked、dirty 或 all（默认）。

none

当子模块包含未跟踪或已修改文件，或其 HEAD 与超级项目中记录的提交不同时，认为该子模块已修改；可用于覆盖 git-config[1] 或 gitmodules[5] 中 ignore 选项的设置。

untracked

当子模块仅包含未跟踪内容时，不认为其 dirty（但仍会扫描是否存在已修改内容）。

dirty

忽略对子模块工作区的所有更改，只显示超级项目中记录的提交变化（这是 1.7.0 之前的行为）。

all

隐藏对子模块的所有更改（并且当设置了 status.submoduleSummary 配置项时，抑制子模块摘要的输出）。

--ignored[=<模式>]

也显示忽略的文件。

模式参数用于指定对被忽略文件的处理。 它是可选的：默认为 "传统"。

可选项：

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

显示或不显示该分支相对于其上游分支的详细超前/滞后计数。 默认为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>

其中`ORIG_PATH`是重命名/复制的内容的来源。`ORIG_PATH`只有在条目被重命名或复制时才会显示。`XY`是一个双字母的状态代码。

各个字段（包括`→`）之间用一个空格隔开。如果一个文件名包含空白或其他不可打印的字符，该字段将以C语言字符串字面的方式被引用：由ASCII双引号（34）字符包围，内部的特殊字符被反斜线省略。

有三种不同类型的状态是使用这种格式显示的，每一种都以不同的方式使用 XY 语法：

  • 当一个合并正在发生并且合并成功时，或者在合并之外 情况，`X`显示索引的状态，`Y`显示工作区的状态。

  • 当发生合并冲突且尚未解决时，X 和 Y 就会出现 显示了相对于共同祖先而言，合并的每个头所引入的状态。这些路径被称为_未合并_。

  • 当一个路径没有被追踪时，X`和`Y`总是相同的，因为它们是 未知的索引。??` 用于未跟踪的路径。除非使用了 --ignored，否则不列出被忽略的文件；如果使用了，则用 !! 表示被忽略的文件。

请注意，这里的_merge_也包括使用默认的`--merge`策略的rebases，cherry-pick，以及其他任何使用merge机制的东西。

在下面的表格中，这三个类别分别显示在不同的部分，这些字符用于显示跟踪路径的前两个部分的 X 和 Y 字段：

'% '

--modified

M

--modified

T

T = 文件类型已更改（常规文件、符号链接或子模块）

A

A=添加

D

delete

R

rebase

C

C = 已复制（如果配置选项 status.renames 设置为 “副本”）

U

U=更新但未合并

-X Y remaining

[AMD]

update

M

[ MTD]

git-update-index(1)

-T

[ MTD]

索引中类型已更改

-A

[ MTD]

添加的内容

-D

从索引中删除

R

[ MTD]

rebase

C

[ MTD]

在索引中复制

[MTARC]

索引与工作树匹配

[ MTARC]

M

工作树自索引以来已更改

[ MTARC]

-T

比较工作区和索引中的文件。

[ MTARC]

-D

eolinfo:worktree

R

eolinfo:worktree

C

eolinfo:worktree

-D

-D

未合并，双方删除

-A

U

未合并，由我方添加

U

-D

未合并，由对方删除

U

-A

未合并，由对方添加

-D

U

未合并，由我方删除

-A

-A

合并后端

U

U

--modified

?

?

--untracked

!

!

--ignored

子模块有更多的状态，而不是报告

M

M = 子模块的 HEAD 与索引中记录的不同

m

m = 子模块修改了内容

m

? = 子模块有未跟踪文件

这是因为子模块中已修改的内容或未跟踪的文件无法在超级项目中通过 git add 添加，以准备提交。

m 和 ? 是递归应用的。例如，如果一个子模块中的嵌套子模块包含一个未跟踪的文件，这也会报告为 ?。

如果使用了-b，短格式的状态前面会有一行

{empty}## <分支名称> <跟踪信息>

瓷器格式版本1

第 1 版的上层命令格式与短格式类似，但保证不会在 Git 版本之间以向后兼容的方式或基于用户配置而改变。这使得它成为脚本解析的理想选择。 上面对短格式的描述也是对瓷器格式的描述，但有一些例外：

  1. 用户的color.status配置不被尊重，颜色将永远是关闭的。

  2. 用户的 status.relativePaths 配置不被尊重；显示的路径将总是相对于仓库根目录。

还有一种替代的-z格式，建议用于机器解析。在这种格式中，状态字段是相同的，但其他一些事情发生了变化。 首先，重命名条目中的"->"被省略，字段顺序被颠倒（例如 "from-> to "变成 to from）。第二，每个文件名后面都有一个NUL（ASCII 0），取代空格作为字段分隔符和终止换行符（但空格仍然将状态字段与第一个文件名分开）。 第三，包含特殊字符的文件名不被特别格式化；不进行引号或反斜线escaping。

任何子模块的变化都被报告为修改的`M`，而不是`m`或单一的`?`。

瓷器格式版本2

第二版格式增加了关于工作区的状态和变化的项目的更多详细信息。 第2版还定义了一套可扩展的、易于解析的可选头文件。

标头行以 `#`开头，是为响应特定的命令行参数而添加的。 解析器应该忽略他们不认识的标题。

分支机构负责人

如果给了`--branch`，就会打印出一系列标题行，其中有关于当前分支的信息。

行 备注

# branch.oid <commit> | (initial)

当前提交。

--branch <分支>

--detach

每个分支

# branch.upstream <upstream-branch>

如果设置了上游。

# branch.ab +<ahead> -<behind>

暂存信息

如果给出了 --show-stash，则打印一行，如果非零，则显示暂存条目的数量：

# 暂存 <N>

变更后的跟踪条目

在页眉之后，一系列的行被打印出来，用于追踪条目。 根据变化的类型，三种不同的行格式之一可用于描述一个条目。 追踪条目是以未定义的顺序打印的；解析器应允许以任何顺序混合使用这三种行类型。

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

1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <路径>

重命名或复制的条目有以下格式：

2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <路径><分隔符><源路径>
字段 remaining

<XY>

一个 2 字符的字段，包含短格式中描述的 已暂存和未暂存 XY 值， 未更改用 "." 而非空格表示。

概述

一个 4 字符的字段，描述子模块状态。 当条目不是子模块时为 "N…​"。 当条目是子模块时为 S<c><m><u>。

  • 如果提交已更改，<c> 为 "C"；否则为 "."。

  • 如果有已跟踪的更改，<m> 为 "M"；否则为 "."。

  • 如果有未跟踪的更改，<u> 为 "U"；否则为 "."。

<mH>

HEAD 中的八进制文件模式。

<mI>

索引中记录的文件模式。

<mW>

从索引中复制文件到工作区。

<hH>

HEAD 中的对象名称。

<hI>

索引中的对象名称。

<X><score>

重命名或复制分数（表示移动或复制的 源和目标之间的相似度百分比）。 例如 "R100" 或 "C75"。

<路径>

路径名。在重命名/复制条目中，这是目标路径。

<sep>

当使用 -z 选项时，两个路径名用 NUL (ASCII 0x00) 字节分隔；否则用 TAB (ASCII 0x09) 字节分隔。

<源路径>

头提交或索引当中的路径名称。 此字段仅存在于重命名或复制的条目中， 用于表示这个条目重命名或复制的来源。

未合并的条目有以下格式；第一个字符是 "u"，以区别于普通的变更条目。

u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <路径>
字段 remaining

<XY>

一个2个字符的字段用于描述冲突类型 使用简短格式。

概述

一个4个字符的字段用于描述子模块状态 如上所述。

<m1>

阶段1中的八进制文件模式。

<m2>

阶段2中的八进制文件模式。

<m3>

阶段3中的八进制文件模式。

<mW>

从索引中复制文件到工作区。

<h1>

阶段1中的对象名称。

<h2>

阶段2中的对象名称。

<h3>

阶段3中的对象名称。

<路径>

路径名。

其他项目

在跟踪的条目之后（如果要求的话），将打印一系列未跟踪的行，然后是在工作区中发现的忽略的条目。

未跟踪的项目有以下格式：

?<路径>

被忽略的项目有以下格式：

!<路径>的情况下

路径名格式说明和-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=false`：表示`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

属于 git[1] 文档