Git Course 0%

git status is your compass

Beginner Git CLI VS Code UI IntelliJ UI ≈ 12 min

Before this lesson

What you will learn

  • What git status compares and why it can never break anything
  • How to read each group of the output and the hints in parentheses
  • What the line about origin/main means, and when it is out of date
  • Where the same information lives in VS Code and IntelliJ IDEA

After this lesson you can

  • I can run git status and explain every line of its output
  • I can tell an untracked, a modified and a staged file apart
  • I know which command to run next in each situation

Why this matters

Almost every Git mistake starts the same way: acting without looking. Committing a file you did not mean to, pushing before you pulled, editing on the wrong branch. git status is the look before the act. It costs nothing, it changes nothing, and once you can read it fluently, Git stops being a mystery box. Run it before and after every other command while you learn, and you will never be surprised.

What git status compares

Remember the four areas: the working tree (your files on disk), the staging area (what the next commit will contain), the local repository (your commits) and the remote. git status looks at the first three and reports every difference between them. It also compares your branch with its copy of the remote branch, if it has one.

The four areas of Git Four boxes from left to right: Working tree, Staging area and Local repository inside a bracket labelled Your computer, and Remote repository on the right labelled GitLab or GitHub. Arrows show git add moving a change from the working tree to the staging area, git commit moving it to the local repository, git push sending it to the remote, git fetch bringing remote history into the local repository, and git pull bringing it all the way into the working tree. YOUR COMPUTER GITLAB / GITHUB Working tree the files you see and edit README.md ✎ docs/faq.md Staging area what goes into the next commit README.md ✓ Local repository your commits (the .git folder) main Remote repository the shared copy the team uses origin/main git add git commit git push git fetch git pull pull = fetch + merge into your working tree
The four areas. git status compares the working tree, the staging area and the last commit, and reports the differences.

Reading the output line by line

Here is a typical report. Ana staged her README change, edited the FAQ afterwards, and created a new file she has not added yet:

Terminal
$ 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
Line Meaning What you usually do next
On branch main The branch you are on. Always check it before committing. If it is the wrong branch, switch before doing anything else.
Changes to be committed: The staged group: exactly what git commit will save right now. Review it, then git commit.
(use "git restore --staged <file>..." to unstage) A hint: the command to take a file back out of this group. Use it if something was staged by mistake.
modified: README.md A tracked file whose staged version differs from the last commit. Nothing; it is ready.
Changes not staged for commit: The modified group: edits on disk that will not be in the next commit yet. git add the ones you want, or leave them for a later commit.
(use "git restore <file>..." to discard changes in working directory) The command that throws these edits away. Only when you are sure; this cannot be undone.
Untracked files: Files Git has never seen: untracked. git add them if they belong in the project; otherwise ignore them (see .gitignore).

The five states at a glance

State How git status shows it Next step
Clean nothing to commit, working tree clean Nothing to save. Maybe git pull or start editing.
Untracked under Untracked files: git add <file> to start tracking it
Modified (not staged) under Changes not staged for commit: git add <file>
Staged under Changes to be committed: git commit -m "…"
Staged and modified again the same file in both groups git add <file> again, or the commit takes only the earlier version

A folder whose files are all untracked is shown as one line ending with a slash, such as notes/, not as a list of files.

How to do it

Run it from anywhere inside the project folder:

Terminal
$ git status
On branch main
nothing to commit, working tree clean

The short form fits on one line per file. The first column is the staging area, the second is the working tree: M modified, A added, D deleted, R renamed, ?? untracked.

Terminal
$ git status -s
M  README.md
 M docs/faq.md
?? CONTRIBUTING.md

Read this as: README.md is staged (M in the first column); docs/faq.md is modified but not staged (M in the second column); CONTRIBUTING.md is untracked.

The line about origin

Once your branch is connected to a branch on the remote (this happens automatically when you clone), git status adds a second line. It compares your branch with your local copy of the remote branch, called origin/main, which is updated only when you run git fetch or git pull.

Terminal
$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

After you commit locally, you are ahead: you have commits the remote does not.

Output
On branch main
Your branch is ahead of 'origin/main' by 1 commit.
  (use "git push" to publish your local commits)

nothing to commit, working tree clean

After someone else pushed and you fetched, you are behind:

Output
On branch main
Your branch is behind 'origin/main' by 1 commit, and can be fast-forwarded.
  (use "git pull" to update your local branch)

nothing to commit, working tree clean

When both happened, the branches have diverged. This is the situation that makes a push fail with "rejected"; the fix is in When someone pushed before you.

Output
On branch main
Your branch and 'origin/main' have diverged,
and have 1 and 1 different commits each, respectively.
  (use "git pull" if you want to integrate the remote branch with yours)

nothing to commit, working tree clean

Do and don't

Do

  • Run git status before and after every command while you are learning.
  • Read the branch line first, every time.
  • Use the hints in parentheses: they are the correct next command for that situation.
  • Run git fetch before trusting the "up to date" line.
  • Use git status -s once the long form feels familiar.

Don't

  • Don't assume "working tree clean" means "everything is pushed".
  • Don't run the git restore <file> hint casually: it deletes your uncommitted edits.
  • Don't stage a file and then keep editing without staging again; the commit will miss your last edits.
  • Don't ignore an unexpected file in the list — find out what created it before you git add ..

Common mistakes

  • Wrong folder. You see fatal: not a git repository (or any of the parent directories): .git. You are outside the project. Check where you are with pwd and move into the project folder with cd.
  • A file appears twice. You staged it, then edited it again. Run git add <file> once more, or the commit contains only the first version.
  • Only a folder name is listed, such as notes/. Every file inside is untracked, so Git shows the folder once. git add notes/ adds them all.
  • "Nothing to commit" after editing a file. Either you saved the file somewhere else, or the file is ignored by .gitignore. Check with git status --ignored.
  • No line about origin at all. Your branch is not connected to a remote branch yet. That is normal for a brand-new branch; the first git push -u origin <branch> creates the connection.

Try it yourself

Goal: produce a git status report that shows all three groups at once, then read it.

  1. Open a terminal in your playground copy of trailguide (see Set up a safe playground) and confirm it is clean:

    Terminal
    $ git status

  2. Create a new file called CONTRIBUTING.md with one line of text, using your editor or:

    Terminal
    $ printf '# Contributing\n' > CONTRIBUTING.md

  3. Add one line to the end of README.md, then stage that file only:

    Terminal
    $ git add README.md

  4. Add one line to the end of docs/faq.md and do not stage it.

  5. Run git status and name each file's state before reading the solution.

Expected result: README.md under Changes to be committed, docs/faq.md under Changes not staged for commit, CONTRIBUTING.md under Untracked files. git status -s shows M README.md, M docs/faq.md and ?? CONTRIBUTING.md.

Show solution

Terminal
$ 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
To clean up afterwards without committing: git restore --staged README.md, then git restore README.md docs/faq.md, then delete CONTRIBUTING.md. Or keep going and commit; it is your playground.

Check yourself

1. Ana edited docs/faq.md and ran git status. The file appears under "Changes not staged for commit". What will git commit -m "Fix FAQ" do right now?
2. git status says Your branch is up to date with 'origin/main'. Which statement is true?
3. A file is listed under both "Changes to be committed" and "Changes not staged for commit". What happened?
4. Which of these can git status do?

Key terms

Working tree Staging area Untracked Modified Staged Tracked Commit origin

Related