Git
简体中文 ▾ Topics ▾ Latest version ▾ git-status last updated in 2.41.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[<模式>]
--untracked-files[=<模式>]

显示未追踪文件。

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

可选项：

  • no - 不显示未跟踪的文件。

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

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

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

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

--ignore-submodules[=<when>]

在寻找变化时忽略子模块的变化。<when>可以是 "none"、"untracked"、"dirty "或 "all"，这是默认的。 使用 "none"，當子模塊包含未被追蹤或修訂的檔案，或者它的頭部與超級工程中記錄的提交不同時，就會認為子模塊被修改了，可以用來覆蓋 git-config[1] 或 gitmodules[5] 中 "忽略 "選項的任何設定。当使用 "untracked "时，当子模块只包含未跟踪的内容时，不被认为是脏的（但它们仍然被扫描为修改的内容）。使用 "dirty "会忽略所有对子模块工作树的修改，只显示存储在超级项目中的提交的修改（这是1.7.0之前的行为）。使用 "all "会隐藏子模块的所有变化（当配置选项`status.submoduleSummary`被设置时，会抑制子模块摘要的输出）。

--ignored[=<模式>]

也显示忽略的文件。

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

可选项：

  • 传统 - 显示被忽略的文件和目录，除非 --untracked-files=all is specified, in which case individual files in ignored directories are displayed.

  • 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。

<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_也包括使用默认的`--merge`策略的rebases，cherry-pick，以及其他任何使用merge机制的东西。

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

  • '' = 未修改的

  • M = 修改过的

  • T = file type changed (regular file, symbolic link or submodule)

  • A=添加

  • D = 删除

  • R = 重命名

  • C = copied (if config option status.renames is set to "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，短格式的状态前面会有一行

## branchname tracking info

瓷器格式版本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> 如果上游被设置且
					 的提交是存在的。
------------------------------------------------------------

Stash Information

If --show-stash is given, one line is printed showing the number of stash entries if non-zero:

# 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> 一个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> <path>
领域含义
--------------------------------------------------------
<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]）。

UNTRACKED FILES AND PERFORMANCE

git status can be very slow in large worktrees if/when it needs to search for untracked files and directories. There are many configuration options available to speed this up by either avoiding the work or making use of cached results from previous Git commands. There is no single optimum set of settings right for everyone. We’ll list a summary of the relevant options to help you, but before going into the list, you may want to run git status again, because your configuration may already be caching git status results, so it could be faster on subsequent runs.

  • The --untracked-files=no flag or the status.showUntrackedfiles=false 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 (see git-config[1]): setting this variable to false disables the warning message given when enumerating untracked files takes more than 2 seconds. In a large project, it may take longer and the user may have already accepted the trade off (e.g. using "-uno" may not be an acceptable option for the user), in which case, there is no point issuing the warning message, and in such a case, disabling the warning may be the best.

  • core.untrackedCache=true (see git-update-index[1]): enable the untracked cache feature and only search directories that have been modified since the previous git status command. Git remembers the set of untracked files within each directory and assumes that if a directory has not been modified, then the set of untracked files within has not changed. This is much faster than enumerating the contents of every directory, but still not without cost, because Git still has to search for the set of modified directories. The untracked cache is stored in the .git/index file. The reduced cost of searching for untracked files is offset slightly by the increased size of the index and the cost of keeping it up-to-date. That reduced search time is usually worth the additional size.

  • core.untrackedCache=true and core.fsmonitor=true or core.fsmonitor=<hook_command_pathname> (see git-update-index[1]): enable both the untracked cache and FSMonitor features and only search directories that have been modified since the previous git status command. This is faster than using just the untracked cache alone because Git can also avoid searching for modified directories. Git only has to enumerate the exact set of directories that have changed recently. While the FSMonitor feature can be enabled without the untracked cache, the benefits are greatly reduced in that case.

Note that after you turn on the untracked cache and/or FSMonitor features it may take a few git status commands for the various caches to warm up before you see improved command times. This is normal.

参见

gitignore[5]

GIT

属于 git[1] 文档

scroll-to-top