git status: what is going on in the repository

git status answers the question "where am I and what have I got": which branch you are on, which files changed, and what is already picked for the next commit.

The command changes nothing, so you can run it as often as you like. Experienced people type it dozens of times a day, between every other pair of commands.

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	new file:   steps.txt

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:   recipe.txt

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

Three sections of the output

Untracked files are files git can see but keeps no history for. They stay out of your snapshots until you say otherwise.

Changes not staged for commit means the file is already watched by git and has changed since the last commit, but those edits will not go into the next snapshot yet.

Changes to be committed is what git add picked into the index (staging area). This is the exact content the next git commit will save.

The same file can appear in two sections at once: part of its edits are staged, and the ones made after git add are not.

Read the hints in parentheses. Git prints the command that undoes or continues the current step right there, which saves you a search.

When everything is saved, the output is short:

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

Short form

git status -s fits the same information into one line per file:

$ git status -s
 M recipe.txt
A  steps.txt
?? shopping.txt
AM note.txt

There are two columns. The first is the state in the index, the second in the working directory. M is modified, A is a newly added file, ?? is untracked. The AM line reads like this: the file was added to the index, then edited again and not re-added since. The -sb flag adds a line with the branch name on top.

Common mistakes

Changes not staged for commit is not an error and not a warning. It is the normal state of work: you edit files, git reports it.

The other place people trip is expecting git status to show line-by-line differences. It shows only the list of files and their state. For the lines themselves you need git diff.

Where this is in the book

The topic is covered in Chapter 3. Three areas and your first commit.

To practise it by hand, take the interactive lesson Your first repository.