Checking the Status of Your Files (git status)

When working with a Git repository, it's essential to understand its current state. You'll frequently need to know: Which files have you changed? Which files are ready to be committed? Are there new files Git doesn't know about yet? The command for answering these questions is git status. It's perhaps the most frequently used command in Git because it reports the current state of your working directory and the staging area. Think of it as your dashboard for the repository's current condition.

Running git status is always safe; it doesn't change any of your files or anything in the repository. It simply provides information.

Let's explore the different kinds of output you might see.

Clean Working Directory

If you run git status right after a git commit, or immediately after cloning a repository, and you haven't made any changes yet, you'll likely see output similar to this:

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

This message tells you a few things:

• On branch main: You are currently on the branch named main. Branches are lines of development, and main is the default branch name in Git. We will cover branches in detail later.
• nothing to commit, working tree clean: This is the main part. It means Git isn't tracking any modified files, and there are no changes staged for the next commit. Your working directory perfectly matches the last snapshot (commit) in the repository.

Untracked Files

Now, let's say you create a new file in your project directory, for example, README.md. If you run git status again, the output will change:

$ touch README.md # Create an empty file named README.md
$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        README.md

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

Here's the breakdown:

• Untracked files: This section lists files that exist in your working directory but are not part of your Git repository yet. Git sees the file (README.md) but isn't tracking its history.
• (use "git add <file>..." ...): Git helpfully suggests the next step: use git add to start tracking the new file and stage it for the next commit.

Changes Not Staged for Commit (Modified Files)

Imagine you have a file that Git is tracking (meaning it was part of a previous commit), and you modify it. Let's assume report.txt was already committed. If you edit report.txt and then run git status:

$ git status
On branch main
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:   report.txt

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

• Changes not staged for commit: This section lists files that Git knows about (they were in the last commit) but have been modified in your working directory since then. However, these changes have not yet been marked for inclusion in the next commit.
• modified: report.txt: Clearly indicates that report.txt has been changed.
• Git again provides helpful hints: use git add to stage the changes, or git restore (or git checkout -- <file> in older Git versions) to discard the changes you made in the working directory.

Changes to be Committed (Staged Files)

You tell Git which changes you want to include in the next commit by adding them to the staging area using git add. If you add the modified report.txt and the new README.md file:

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

• Changes to be committed: This section is important. It lists all the changes currently in the staging area. These are the changes that will be included if you run git commit right now.
• modified: report.txt: The modifications to report.txt are now staged.
• new file: README.md: The newly created README.md is now staged.
• Git also tells you how to unstage a file (git restore --staged <file>... or git reset HEAD <file>... in older versions) if you added it by mistake.

Mixed States

It's common to have files in multiple states simultaneously. For instance, you might stage report.txt but then modify it again before committing. Or you might stage one file while another remains modified but unstaged, and a third file is newly created but untracked. git status handles this clearly:

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

Changes not staged for commit:
  (use "git restore <file>..." to discard changes in working directory)
        modified:   report.txt # Modified *again* after staging
        modified:   utils.py   # Another modified file, not staged

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

This output shows:

1. report.txt is staged (the version you added with git add).
2. report.txt has also been modified in the working directory since it was staged. If you commit now, only the staged version goes into the commit. You'd need to run git add report.txt again to stage the latest changes.
3. utils.py has been modified but not staged.
4. config.yaml is a new file that Git doesn't track yet.

This diagram illustrates the different states a file can be in, as reported by git status, relative to the Working Directory and Staging Area.

Short Status Output

For a more compact view, you can use the -s or --short flag:

$ git status -s
 M report.txt  # M in the first column: Staged
 M report.txt  # M in the second column: Modified but not staged
 M utils.py    # M in the second column: Modified but not staged
?? config.yaml # ?? means Untracked

The letters indicate the status:

• M (first column, green): Modified and staged
• A (first column, green): Added (new file) and staged
• M (second column, red): Modified but not staged
• ?? (red): Untracked

This short format is useful once you become familiar with the status codes.

Using git status frequently is a good habit. It helps you keep track of your work, ensures you commit only the changes you intend to, and provides context for other Git commands like git add and git commit.