The Geometry of Version Control

Concept:

Git moves your files between four areas: Working Directory (your files on disk), Staging Area (what you've chosen to include in the next commit), Local Repository (your committed history in .git/), and Remote Repository (GitHub). Every Git command is just moving something between these areas. Your desktop GUI hid the Staging Area from you — that's the key piece you were missing.

Socrates: Come, my friend. You tell me you know Git — that you have been using it daily. Is that so?

Student: Yes, Socrates. I commit, I push, I pull. I've been using GitHub Desktop for over a year.

Socrates: Excellent! Then tell me — when you click 'Commit' in your tool, where exactly does your code go?

Student: To... the repository?

Socrates: Which repository? The one on your machine, or the one on GitHub?

Student: I... hmm. I suppose the local one first? Then I push to GitHub?

Socrates: Good — you are already halfway there. Now, your tool has a checkbox beside each file before you commit. What is that?

Student: That's to select which files to include in the commit.

Socrates: Precisely. And in the terminal, that selection is its own distinct place — the Staging Area. Your tool hid it behind a checkbox. Look at the diagram: four areas, four arrows. Every Git command you will ever learn simply moves files between them.

Student: So 'git add' is the checkbox? And 'git commit' is clicking the Commit button?

Socrates: Now you see it. 'git add' moves a file from your Working Directory to the Staging Area. 'git commit' moves everything staged into the Local Repository. 'git push' sends it to the Remote. And 'git status' — that is your compass. It tells you exactly where each file lives right now.

Student: And 'git pull'?

Socrates: That is the reverse journey — from Remote to your machine. It fetches the commits, then merges them into your Working Directory. Two steps disguised as one. Now — let us not merely talk about it. Show me the complete journey of a file, from creation to committed history.

Example Code:

┌──────────────┐  git add   ┌──────────────┐  git commit  ┌──────────────┐  git push   ┌──────────────┐
│              │ ─────────► │              │ ───────────► │              │ ──────────► │              │
│  Working Dir │            │ Staging Area │              │  Local Repo  │             │  Remote Repo │
│  (your files)│ ◄───────── │  (the index) │              │   (.git/)    │ ◄────────── │   (GitHub)   │
└──────────────┘ git restore└──────────────┘              └──────────────┘  git fetch  └──────────────┘

                  git status tells you where each file currently lives
                  git pull  =  git fetch + git merge

Your Assignment

Create a file called 'notes.txt' with the content 'first draft', stage it with git add, then commit it with the message 'Add notes'.

Solution:

echo 'first draft' > notes.txt && git add notes.txt && git commit -m 'Add notes'

Git Console

git>