info > GIT-STATUS(1)

man perldoc info pydoc3 ri search

📖 NAME

git-status - 🖥️ Show the working tree status

🚀 Quick Reference

Use Case	Command	Description
📄 Short status	git status -s	Show status in compact short format
🏷️ Show branch info	git status -b	Include branch and tracking information
🔍 Verbose staged changes	git status -v	Show staged textual differences
📂 Show untracked files	git status -u	Display untracked files (default: normal)
🚫 Show ignored files	git status --ignored	List ignored files as well
🤖 Machine-readable output	git status --porcelain	Stable format for scripts (v1 or v2)
💾 Stash information	git status --show-stash	Show number of stashed entries

📋 SYNOPSIS

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

📝 DESCRIPTION

Displays paths that have differences between the index file and the current HEAD commit, paths that have differences between the working tree and the index file, and paths in the working tree that are not tracked by Git (and are not ignored by gitignore(5)). The first are what you would commit by running git commit; the second and third are what you could commit by running git add before running git commit.

🔧 OPTIONS

🔹 -s, --short

📄 Give the output in the short-format.

🔹 -b, --branch

🏷️ Show the branch and tracking info even in short-format.

🔹 --show-stash

💾 Show the number of entries currently stashed away.

🔹 --porcelain[=<version>]

🤖 Give the output in an easy-to-parse format for scripts. Similar to short output, but stable across Git versions and regardless of user configuration. The version parameter (optional, defaults to v1) specifies the format version.

🔹 --long

📃 Give the output in the long-format (default).

🔹 -v, --verbose

🔍 In addition to changed file names, also show staged textual changes (like git diff --cached). Use -vv to also show unstaged working tree changes.

🔹 -u[<mode>], --untracked-files[=<mode>]

📂 Show untracked files. Mode can be:

• no – Show no untracked files.
• normal – Shows untracked files and directories (default if option omitted).
• all – Also shows individual files in untracked directories.

💡 Consider enabling untracked cache or split index for performance in large working trees. The default can be changed via status.showUntrackedFiles configuration.

🔹 --ignore-submodules[=<when>]

📦 Ignore changes to submodules. <when> values:

• none – Consider submodule modified if it contains untracked/modified files or HEAD differs.
• untracked – Ignore only untracked content (modified content still shown).
• dirty – Ignore all work tree changes; show only superproject commit changes.
• all – Hide all submodule changes.

🔹 --ignored[=<mode>]

🚫 Show ignored files as well. Mode can be:

• traditional – Shows ignored files/directories (or individual files with --untracked-files=all).
• no – Show no ignored files.
• matching – Show paths that explicitly match an ignore pattern.

🔹 -z

🔌 Terminate entries with NUL instead of LF. Implies --porcelain=v1 if no other format given.

🔹 --column[=<options>], --no-column

📊 Display untracked files in columns. See column.status configuration. --column = always, --no-column = never.

🔹 --ahead-behind, --no-ahead-behind

📈 Show (or hide) detailed ahead/behind counts relative to upstream branch. Default is true.

🔹 --renames, --no-renames

🔄 Enable/disable rename detection regardless of configuration. See git-diff(1) --no-renames.

🔹 --find-renames[=<n>]

🔎 Turn on rename detection with optional similarity threshold.

🔹 <pathspec>...

📁 See the pathspec entry in gitglossary(7).

📤 OUTPUT

The output from this command is designed to be used as a commit template comment. The default long format is human-readable and descriptive. Paths are relative to the current directory (see status.relativePaths).

🔹 Short Format

Status of each path shown as:

XY PATH
XY ORIG_PATH -> PATH

Where ORIG_PATH is shown for renames/copies. XY is a two-letter status code. Files with special characters are quoted in C string literal style.

Three types of states:

• Normal merge or no merge: X = index status, Y = working tree status.
• Unresolved merge conflict: X and Y represent conflicting heads relative to common ancestor.
• Untracked: ?? used; ignored files shown as !! with --ignored.

Status characters for tracked paths:

• = unmodified
• M = modified
• T = file type changed
• A = added
• D = deleted
• R = renamed
• C = copied (if status.renames=copies)
• U = updated but unmerged

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

Submodules: M = different HEAD, m = modified content, ? = untracked files. m and ? apply recursively.

With -b, a line ## branchname tracking info precedes the short status.

🔹 Porcelain Format Version 1

Similar to short format but stable across versions and ignores color.status and status.relativePaths configurations. Paths are relative to repository root.

With -z (NUL-terminated): rename entries omit -> and field order reversed (to from); filenames are not quoted/escaped; submodule changes reported as M.

🔹 Porcelain Format Version 2

Adds detailed information with an extensible header system. Headers start with #.

Branch Headers (with --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 commit is present.

Changed Tracked Entries

Three line formats:

• Ordinary changed: 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
• Renamed or copied: 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
• Unmerged: u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>

Field	Meaning
<XY>	2-character staged/unstaged status ( "." = unchanged).
<sub>	Submodule state: N... (not submodule) or S<c><m><u> (C=commit changed, M=tracked changes, U=untracked changes).
<mH>	Octal file mode in HEAD.
<mI>	Octal file mode in index.
<mW>	Octal file mode in worktree.
<hH>	Object name in HEAD.
<hI>	Object name in index.
<X><score>	Rename/copy score (e.g., R100, C75).
<path>	Pathname; for rename/copy, target path.
<sep>	NUL with -z, tab otherwise.
<origPath>	Source path for rename/copy.

Unmerged Entry Fields

Field	Meaning
<XY>	Conflict type (as in short format).
<sub>	Submodule state.
<m1>	Octal mode in stage 1.
<m2>	Octal mode in stage 2.
<m3>	Octal mode in stage 3.
<mW>	Octal mode in worktree.
<h1>	Object name in stage 1.
<h2>	Object name in stage 2.
<h3>	Object name in stage 3.
<path>	Pathname.

Other Items

• Untracked: ? <path>
• Ignored: ! <path>

With -z: pathnames printed as-is, NUL-terminated. Without -z: unusual characters quoted per core.quotePath.

⚙️ CONFIGURATION

The command honors color.status (or status.color) and color.status.<slot> configuration variables for colorizing output.

If status.relativePaths is false, paths are relative to repository root instead of current directory.

If status.submoduleSummary is set to non-zero or true, submodule summaries are shown in long format (see git-submodule(1) --summary-limit). Summaries are suppressed when diff.ignoreSubmodules=all or submodule.<name>.ignore=all. Use --ignore-submodules=dirty or git submodule summary to view them.

🔄 BACKGROUND REFRESH

By default, git status automatically refreshes the index by caching stat information from the working tree and writing it out. This optimization may conflict with other simultaneous processes. Scripts running status in the background should consider using git --no-optional-locks status (see git(1)).

📚 SEE ALSO

• gitignore(5)

🐙 GIT

Part of the git(1) suite

📖 NAME 🚀 Quick Reference 📋 SYNOPSIS 📝 DESCRIPTION 🔧 OPTIONS 📤 OUTPUT ⚙️ CONFIGURATION 🔄 BACKGROUND REFRESH 📚 SEE ALSO 🐙 GIT