git status: Usage, Options & Common CI Errors

By Daniel Zoghalchali·Latchkey

git status tells you what is staged, what is changed, and how your branch relates to its upstream.

Status is your orientation tool. The --porcelain format is the stable one to parse in scripts.

What it does

git status reports the state of the working tree and index: staged changes, unstaged changes, untracked files, and whether the branch is ahead/behind its upstream.

Common usage

Terminal

git status
git status -sb                # short + branch line
git status --porcelain        # stable, script-friendly output
# gate a commit on real changes:
[ -n "$(git status --porcelain)" ] && git commit -am "update"

Options

Flag	What it does
-s / --short	Compact one-line-per-file output
-b / --branch	Show branch and tracking info
--porcelain[=v1\|v2]	Stable machine-readable format
-u<mode>	Control untracked-file detail (no/normal/all)

Common errors in CI

A frequent mistake is parsing the human-readable output, which is localized and can change. Always parse --porcelain in scripts. An empty --porcelain result is the reliable signal that there is nothing to commit.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

Frequently asked questions

git status: Usage, Options & Common CI Errors?