# git status: Usage, Options & Common CI Errors

> git status shows staged, unstaged, and untracked changes plus branch state. Reference for -s, --porcelain, -b, and using it to gate commits in CI.

Source: https://latchkey.dev/learn/command-reference/git-status  
Updated: 2026-06-25

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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git status: Usage, Options & Common CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt