git status

Summary: git status reports the state of your working tree and staging area compared with the last commit, plus whether your branch is ahead of or behind its remote counterpart. It never changes anything.

Safe — you can run it as often as you like, in any state, without side effects.

What it does

It compares three things — the last commit, the staging area and the files on disk — and lists every difference, grouped:

• Changes to be committed: staged changes that the next git commit will include.
• Changes not staged for commit: tracked files you edited or deleted but have not staged.
• Untracked files: files Git has never been told about.
• A first line about the branch: which branch you are on and, if the branch tracks a remote branch, whether you are up to date, ahead, behind, or diverged.

Each group comes with a hint in parentheses telling you the command for the usual next step.

Why it exists

Git keeps four copies of your project in different states (working tree, staging area, local repository, remote). git status is the one command that shows you where everything stands before you act, so you never commit the wrong thing or push into a surprise.

When to use it

• Before git add, to see what you are about to stage.
• Before git commit, to confirm exactly what will be saved.
• Before git push or git pull, to see whether you are ahead or behind.
• Any time an IDE shows a colour or a badge you do not understand.
• Any time you are unsure what state you are in — especially in the middle of a merge or rebase, where it tells you what to do next.

When not to use it

There is no wrong moment. The only "don't" is reading its output as a remote status: unless the first lines mention origin/…, it says nothing about what other people have pushed. Run git fetch first to update that information.

Syntax

Examples

A clean repository:

$ git status

On branch main
nothing to commit, working tree clean

One new file Git has never seen:

$ git status

On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	CONTRIBUTING.md

nothing added to commit but untracked files present (use "git add" to track)

A staged change, an unstaged change and an untracked file at the same time:

$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   README.md

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:   docs/faq.md

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

The same situation in short form (first column = staging area, second column = working tree):

$ git status -s

M  README.md
 M docs/faq.md
?? CONTRIBUTING.md

A file staged and then edited again — it appears in both groups because the staged version and the disk version now differ:

$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   README.md

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:   README.md
	modified:   docs/faq.md

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

A deleted file and a renamed file:

$ git status

On branch main
Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	deleted:    docs/faq.md

no changes added to commit (use "git add" and/or "git commit -a")

$ git mv docs/faq.md docs/questions.md
$ git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	renamed:    docs/faq.md -> docs/questions.md

Expected result

Nothing changes: no file, no commit, no branch. git status only reads. The short-form letters are: M modified, A added, D deleted, R renamed, ?? untracked, !! ignored (with --ignored), UU conflicted.

Common mistakes

• Running it in the wrong folder. You see fatal: not a git repository (or any of the parent directories): .git. Move into the project folder with cd, or check the path with pwd.
• Reading "nothing to commit, working tree clean" as "everything is pushed". It only means your files match your last commit. Look at the branch line: Your branch is ahead of 'origin/main' by 1 commit means you still need to push.
• Missing a file that is in both groups. After git add, editing the file again puts it in "Changes not staged" too. Run git add again before committing, or the commit contains only the earlier version.
• Expecting ignored files to appear. Files matching .gitignore are hidden; add --ignored to see them.

How to undo or recover

Nothing to undo: the command has no effect. The hints it prints are the undo commands for other operations (git restore --staged to unstage, git restore to discard edits).

In VS Code

The Source Control view (Ctrl+Shift+G, ⌃⇧G on macOS) is a permanent git status: Staged Changes = "Changes to be committed", Changes = "Changes not staged" plus untracked files marked U. See The Source Control view.

In IntelliJ IDEA

The Commit tool window (Alt+0, ⌘0 on macOS) lists changed files; unversioned (untracked) files have their own group and modified files are shown in blue. See Git, Commit and Log tool windows.

Related commands

git diff shows the content of the changes status only names · git add stages · git restore unstages or discards · git log shows the commits status does not list.

Lessons that use this command

git status is your compass · File states · Lab 1.