Repositories, Status, and Commits

Core path: 30 minutes

What problem is Git actually solving?

Before Git, beginners often build a homemade history system:

project.py
project2.py
project-final.py
project-final-fixed.py
project-final-fixed2.py
project-final-REAL.py

That gives you copies.

It does not give you a trustworthy record of what changed, when it changed, or which version was known to work.

Git is a version-control system. It records project states and the relationships between those states so you can inspect, compare, recover, and collaborate without multiplying folders forever.

Git and GitHub are different systems

Git is the version-control software managing history in your repository.

GitHub is a service that can host a remote Git repository and add collaboration features around it.

Git works without GitHub.

You can create commits, inspect history, compare versions, and recover locally with no remote account at all.

Read the strip as two layers:

LOCAL DEVELOPMENT
files + Git repository + commits

REMOTE HOSTING
optional copy/history on a configured remote such as GitHub

git commit does not upload anything to GitHub.

git push does not create the local commit you forgot to make.

Keep those operations separate.

A repository is more than a folder

A normal project folder contains your files.

A Git repository also contains Git metadata recording history and state.

When Git is initialized or a repository is cloned, the hidden .git directory holds the repository database and references Git needs.

Do not manually edit .git because you are curious. Inspect Git through Git commands unless you specifically know what you are doing.

The working files you edit and the repository history are related but not identical layers.

Git compares states

Suppose the last commit contains:

threshold = 20

and you edit the file to:

threshold = 25

Git can now recognize that the working copy differs from the recorded checkpoint.

It does not understand the semantic reason you changed a battery threshold. It tracks content/state differences.

That is why your commit message and review matter: humans add intent to the history.

The three-state mental model

For beginner work, think about three places:

WORKING TREE
files as they currently exist while you edit
        ↓ git add
STAGING AREA / INDEX
selected content for the next commit
        ↓ git commit
LOCAL COMMIT HISTORY
recorded checkpoints

Interactive model

Move a change through Git's three states

Pause motionReset layout

Editing changes the working tree. git add selects the next snapshot. git commit records that staged snapshot in local history.

WORKING TREE files being edited

STAGING AREA selected changes

LOCAL HISTORY commit snapshots

git status inspect state anytime

React Flow

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Drag nodes to inspect the relationships. Motion shows the active path; the plain background keeps attention on the relationships instead of graph-paper decoration.

View static diagram

The arrows are state transitions caused by Git commands.

They do not mean the file physically disappears from the working directory and moves into a different folder.

The staging area is Git's selected snapshot/content state for the next commit.

That distinction is one of the most important things to explain when looking at the diagram.

Start every uncertain Git moment with git status

git status

This command can tell you:

current branch
files changed in the working tree
changes staged for commit
untracked files
whether the working tree is clean

Treat it like a dashboard for repository state.

Before running a Git command you are unsure about, check status.

After running it, check status again.

That simple habit makes invisible state changes visible.

git add does not mean "save"

Your editor already saves the file to the filesystem.

This:

git add main.py

means roughly:

Select the current content of main.py for inclusion in the next commit.

If you edit main.py again after staging it, the staging area can contain one version while the working tree contains a newer version.

That surprises people who think staging is just a checkbox permanently attached to the filename.

Git tracks content states.

A commit records the staged project state

git commit -m "Add player search"

creates a new local checkpoint from the staged content.

A commit is not:

a Ctrl+S save
a cloud upload
a backup zip
an automatic proof the code works

A good checkpoint should ideally represent a coherent, verified change.

The message helps humans understand its purpose:

Add player search
Fix empty roster crash
Document setup instructions

Compare those with:

stuff
changes
asdf
fixed

Git can store the vague message. Future you is the one who suffers.

Clean does not mean correct

After committing, git status may say the working tree is clean.

That means the checked-out files match the recorded state Git expects.

It does not mean:

all tests passed
the feature is correct
the program is secure
the requirement was satisfied

Git tracks repository state. Verification comes from other evidence.

That distinction becomes critical in Weeks 15–17 when AI agents can create perfectly clean commits containing wrong code.

Practice the state transitions

Robotnix Git simulation
The segmented prompt reflects repository state: ! changed, + staged, ↑ local commit, ✓ synced.
Type 'help' for supported commands.

$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)

        modified:   player.py

no changes added to commit

$ git diff
diff --git a/player.py b/player.py
-def find_player(name):
+def find_player(name, players):
+    return next((p for p in players if p["name"] == name), None)

$ git add .

$ git commit -m "Add player search"
[main a13f7c2] Add player search
 1 file changed, 2 insertions(+), 1 deletion(-)

$ git log --oneline
a13f7c2 Add player search
8b21fd4 Start player project

$ git push origin main
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (3/3), done.
To github.com:student/python-project.git
   8b21fd4..a13f7c2  main -> main

$ git pull origin main
From github.com:student/python-project
 * branch            main       -> FETCH_HEAD
Already up to date.

Use the terminal simulation to type:

git status
git diff
git add .
git status
git commit -m "Add player search"
git status
git log --oneline
git push origin main
git status

Watch the simulated prompt state change:

!1 → modified working tree
+1 → staged change
↑1 → local commit ahead of remote
✓  → synchronized/clean simulation state

Those prompt symbols summarize repository state. They are not a replacement for understanding git status.

One project, one visible timeline

A useful Git history might become:

Add player search
Add roster display
Save roster to JSON
Create roster application

Each commit gives you a point you can inspect later.

That is much stronger than trying to remember whether final_REAL_fixed2.py was the version before or after the JSON bug.

Follow one edit through the repository

Start from a clean repository.

Edit:

LOW_BATTERY = 20

to:

LOW_BATTERY = 25

Then trace:

file saved
↓
working tree differs from HEAD
↓ git status / git diff
change becomes visible
↓ git add
staging area records the selected content
↓ git commit
new local checkpoint created

At each step, ask what git status should show before running it.

That is how the three-state model becomes operational instead of decorative.