git status

The cheap, safe, always-run-first command.

🎯 What & why

Show the state of the working tree and index relative to HEAD: what's staged, what's modified-but-unstaged, what's untracked, what branch you're on, how it relates to its upstream. Read-only and cheap — run it constantly.

🧠 Mental model

Status reads three things and diffs them: HEAD's tree, the index, and the working tree. 'Staged' = differences between HEAD and the index. 'Unstaged' = differences between the index and the working tree. 'Untracked' = files in the working tree that the index has never seen.

🛠️ Synopsis

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

🎚️ Switches & options

Flag	What it does
`-s, --short`	Compact output. Two columns: index state, working tree state.
`-b, --branch`	Show branch + upstream tracking info even in short form.
`--porcelain[=<v>]`	Stable, machine-readable format. Use this in scripts.
`-u, --untracked-files[=mode]`	Control how aggressively to scan for untracked files. `no` is fastest; `all` lists every file in untracked dirs.
`--ignored`	Also show ignored files. Helpful when figuring out why something isn't being tracked.
`--ahead-behind`	Show how many commits ahead/behind upstream you are.

💡 Use cases

Anytime, ever, before you do anything destructive.
Confirming that staging worked the way you wanted.
CI scripts: ensure the build hasn't dirtied the working tree.
Hooks: --porcelain output is parseable and won't change between Git versions.

🧪 Examples

Default — verbose, human-friendly.

$ git status
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
  modified:   src/main.c
Untracked files:
  notes.todo

Short form. Quick scan.

$ git status -sb
## main...origin/main
 M src/main.c
?? notes.todo

Why isn't build/output.log tracked?

$ git status --ignored | grep build/
  build/

Scriptable check: are there any changes?

$ test -z "$(git status --porcelain)" && echo clean || echo dirty

🎓 Recommendations

Alias gs='git status -sb' if you type it more than ten times a day — and you will.
Use --porcelain for any script. The non-porcelain output is for humans and will change between versions.
If status is slow on a large tree, look at core.fsmonitor and core.untrackedCache.

🪤 Common pitfalls

Status doesn't run hooks. If you have a pre-commit hook that lints, status won't show what the hook will reject.
Long status output in a clean repo means a recursive untracked scan; speed it up with core.untrackedCache=true.
Short output's first column is index state and second is working tree state. People constantly read it backwards.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.