Synopsis

git status [-s] [-b] [--porcelain[=<version>]] [--ignored]

Description

The git status command displays the state of the working tree and the staging area. It shows which files are staged for the next commit, which are modified but not staged, and which are untracked. It also reports the current branch, whether it is ahead or behind the upstream, and any ongoing operations such as merges or rebases.

git status is the most-run Git command — it's safe, fast, and informational. Use it constantly to confirm what state your repository is in before making decisions. The default output is human-friendly with color and hints; the --porcelain output is stable, machine-readable, and meant for scripts.

In day-to-day use, git status integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git status --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.

Understanding how git status interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git status's side effects helps avoid all three.

Common Options

Examples

git status
# Full human-readable status

git status -sb
# Compact format with branch info

git status --porcelain=v2 --branch
# Stable output for shell scripts and editors

git status --ignored
# Include files matched by .gitignore

Common Mistakes

Beginners sometimes panic when git status shows many untracked files in a freshly cloned repo with build artifacts. Add a proper .gitignore to filter them out. Another pitfall is parsing the default output in scripts — the format may change between versions and translations. Always use --porcelain for automation. Finally, large untracked directories can slow status considerably; use -uno to skip them.

Related Commands

git diff, git log, git add, git stash