GitChecking Status (git status)

Checking Status (git status)

git status is the most-used Git command by a wide margin. It is a non-destructive read of where things stand: which branch you are on, which files are modified, which are staged, which are untracked, and whether your branch is ahead/behind the remote. Running it before and after every operation is the single most useful habit a beginner can develop.

The plain version

Bash
git status

Typical output

Text
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   src/App.js
        new file:   src/Header.js

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   src/App.js

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        notes.md
Reading the output

  • On branch main — your current branch.

  • Your branch is up to date / ahead by N / behind by N — comparison with the upstream remote branch.

  • Changes to be committed — files in the staging area that will be included in the next commit.

  • Changes not staged for commit — files Git is tracking that you have modified since the last commit, but have not yet staged.

  • Untracked files — files in the working directory that Git has never been told to track.

A file may appear twice
If you `git add` a file then keep editing it, you’ll see the same path under both *Changes to be committed* (the staged version) AND *Changes not staged for commit* (the additional edits). Stage again to combine them.
The short form

Bash
git status -s
# or:
git status --short

Short output

Text
M  src/App.js          ← staged modification
 M src/App.js          ← additional unstaged modification
A  src/Header.js       ← staged new file
?? notes.md            ← untracked
D  old-thing.txt       ← staged deletion
 D test.spec.js        ← unstaged deletion
R  src/old.js -> src/new.js   ← rename

  • The first column is the staging area state, the second column is the working tree state.

  • M = modified, A = added, D = deleted, R = renamed, ?? = untracked.

  • Two columns let you see at a glance whether each change is staged.

Short form with branch info

Bash
git status -sb

Text
## main...origin/main [ahead 2, behind 1]
 M src/App.js
?? notes.md
Useful flags

  • -s or --short — compact one-line-per-file output.

  • -b or --branch — include branch + upstream info even in short mode.

  • --porcelain — machine-readable, very stable format (use in scripts).

  • --ignored — also list files Git is ignoring.

  • -u or --untracked-files=all — show untracked files inside untracked directories.

  • --column — multi-column output.

Ignored files

See what is being ignored

Bash
git status --ignored

Helpful when you wonder why a file is missing from git status — it might be matched by .gitignore.

Programmatic use

Use --porcelain in scripts

Bash
# Exit non-zero if there are any changes
if [ -n "$(git status --porcelain)" ]; then
  echo "You have uncommitted changes"
  exit 1
fi

The --porcelain flag guarantees the output will not change across Git versions, which makes it safe to parse in scripts. The default human output is not.

The branch comparison line

Possible branch states

Text
Your branch is up to date with 'origin/main'.
Your branch is ahead of 'origin/main' by 2 commits.
Your branch is behind 'origin/main' by 3 commits, and can be fast-forwarded.
Your branch and 'origin/main' have diverged, and have 2 and 3 different commits each.

  • Up to date — local and remote pointers match.

  • Ahead — you have commits the remote does not. git push will fast-forward.

  • Behind — the remote has commits you do not. git pull will fast-forward.

  • Diverged — both sides have new commits. You will need to merge or rebase.

What status does NOT show

  • Files inside ignored folders (unless you pass --ignored).

  • Differences between branches — use git diff branch1 branch2.

  • Differences between commits — use git diff commit1 commit2.

  • Remote branches the upstream itself has — use git fetch first to update Git’s view.

Make it faster

On big repos git status can be slow. Two settings help:

Speed-up settings

Bash
# Cache directory listings (huge speedup on big repos, macOS especially)
git config --global core.untrackedCache true

# Filesystem monitor (experimental but stable)
git config --global core.fsmonitor true
Tip
Add an alias: git config --global alias.s "status -sb" and you can type just git s for a compact, branch-aware status. After a few days it becomes muscle memory.