--fast-version-control
简体中文 ▾ Topics ▾ Latest version ▾ git-status last updated in 2.45.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 - 显示未被追踪的文件和目录。

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

When -u option is not used, untracked files and directories are shown (i.e. the same as specifying normal), to help you avoid forgetting to add newly created files. Because it takes extra work to find untracked files in the filesystem, this mode may take some time in a large working tree. Consider enabling untracked cache and split index if supported (see git update-index --untracked-cache and git update-index --split-index), Otherwise you can use no to have git status return more quickly without showing untracked files. All usual spellings for Boolean value true are taken as normal and false as no.

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

--ignore-submodules[=<when>]

在查找更改时忽略子模块的更改。<when> 可以是 "none"（无）、"untracked"（未跟踪）、"dirty"（脏）或 "all"（全部），这是默认值。使用 "none "时，如果子模块包含未跟踪或已修改的文件，或者其 HEAD 与上层项目中记录的提交不一致，则该子模块将被视为已修改，并可用于覆盖 git-config[1] 或 gitmodules[5] 中 "忽略 "选项的任何设置。当使用 "untracked "时，如果子模块只包含未跟踪的内容，则不会被视为 dirty（但仍会扫描修改过的内容）。使用 "dirty" 会忽略对子模块工作树的所有修改，只显示对存储在超级项目中的提交的修改（这是 1.7.0 之前的行为）。使用 "all "则会隐藏子模块的所有更改（并在设置配置选项 status.submoduleSummary 时抑制子模块摘要的输出）。

--ignored[=<模式>]

也显示忽略的文件。

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

可选项：

  • 传统 - 显示被忽略的文件和目录，除非 如果指定—​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 字段：

  • '' = 未修改的

  • M = 修改过的

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

  • A=添加

  • D = 删除

  • R = 重命名

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

  • 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，短格式的状态前面会有一行

## 分支名称跟踪信息

瓷器格式版本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> | (初始) 当前的提交。
# branch.head <branch> | (detached) 当前分支。
# branch.upstream <upstream_branch> 如果upstream被设置。
# 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> <path><sep><origPath>
领域含义
--------------------------------------------------------
<XY> 一个2个字符的字段，包含短格式中描述的阶段性和非阶段性XY值。
	    阶段性和非阶段性的XY值。
	    不变的用". "表示，而不是用空格。
	    而不是空格。
<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)分隔。
	    用一个NUL(ASCII 0x00)字节分开；否则，用一个TAB(ASCII 0x09)
	    字节来分隔它们。
<origPath> 在HEAD或索引中提交的路径名。
	    这只存在于重命名/复制的条目中，并且
	    告诉你重命名/复制的内容来自哪里。
--------------------------------------------------------

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

u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <路径>
领域含义
--------------------------------------------------------
<XY> 一个2个字符的字段，描述冲突类型
	    描述冲突类型。
<sub> 一个4个字符的字段，描述子模块的状态
	    如上所述。
<m1> 阶段1中的八进制文件模式。
<m2> 阶段2中的八进制文件模式。
<m3> 阶段3中的八进制文件模式。
<mW> 工作树中的八进制文件模式。
<h1> 阶段1中的对象名称。
<h2> 第二阶段的对象名称。
<h3> 第三阶段的对象名称。
<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 config (see above for both): indicate that git status should not report untracked files. This is the fastest option. git status will not list the untracked files, so you need to be careful to remember if you create any new files and manually git add them.

  • 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] 文档

scroll-to-top