# Git Operations - Eric's Mental Model vs Actual Steps

## How This Document Came About

During a parity-check session on March 30, 2026, Eric noticed that after switching
to the `tablet-site-map` branch, Claude reported:

    Switched to branch 'tablet-site-map'
    On branch tablet-site-map
    nothing to commit, working tree clean

This prompted a question: what does "nothing to commit, working tree clean" actually mean?
That conversation led to unpacking the full reality of how git works vs how Eric was
naturally thinking about it.

Eric came in thinking in 3 steps:
- "commit"
- "push"
- "merge"

And those 3 words were always right - Claude understood exactly what to do.
But the actual execution is 6 steps. This document maps them.

---

## The 5 States a File Can Be In

Before understanding the steps, understand where a file can live at any moment:

1. **Untracked** - A brand new file you just created. Git sees it exists but has never
   been told to care about it. It will NOT be included in any commit until you add it.

2. **Modified** - An existing file you changed on disk. Git knows it changed but has
   not been told to do anything about it yet.

3. **Staged** - You ran `git add` on the file. Git has taken a snapshot of it at this
   exact moment and is holding it in a "waiting room" called the index (also called the
   staging area). It is ready to be committed.

4. **Committed** - You ran `git commit`. Git has locked that snapshot permanently into
   your LOCAL git history. This only exists on your machine. GitHub does not know yet.

5. **Pushed** - You ran `git push`. GitHub (the cloud) now has those commits.
   If your machine burned down, the work survives.

---

## A Note About SVN vs Git - The "Add" Difference

In SVN (the old system), `svn add` had a specific meaning: "start tracking this new
file permanently." You only ran it once per file, when it was brand new.

In Git, `git add` means something different: "include this file in my NEXT commit."
You run it every time - for new files AND for changes to existing files. Git does not
distinguish between "new file" and "changed file" at the add step. Both are just staged.

This is one of the bigger mental shifts coming from SVN to Git.

---

## The Staging Area (Level 1.5)

Between "changed on disk" and "committed," there is a half-step that is easy to miss
because in daily practice it happens so fast it feels invisible.

The staging area is a deliberate design choice in Git. It lets you:
- Have 10 files changed but only commit 3 of them
- Stage a file, keep editing it, and commit the staged version (not the newer disk version)
- Review exactly what will be in the commit before it's locked in

In practice, Claude does `git add` and `git commit` back to back, so you never have
to think about it separately. But it is always happening.

---

## The 3 Words You Say vs The 6 Steps That Happen

### When you say "commit push and merge":

**"commit"** triggers steps 1 and 2:
- Step 1: `git add filename.php` (or multiple files) - stage everything relevant
- Step 2: `git commit -m "description"` - lock into local git history

**"push"** triggers step 3:
- Step 3: `git push origin branch-name` - send commits to GitHub so the cloud knows
  this branch exists with these commits

**"merge"** triggers steps 4, 5, and 6:
- Step 4: `git checkout main` - switch your local working copy to the main branch
- Step 5: `git merge branch-name` - bring all the branch commits into main locally
- Step 6: `git push origin main` - send the updated main to GitHub

### Summary table:

| What you say | What actually happens                              |
|--------------|----------------------------------------------------|
| commit       | git add (stage) + git commit (lock locally)        |
| push         | git push origin branch (cloud knows about branch)  |
| merge        | git checkout main + git merge + git push origin main |

---

## The 4 Levels of "Where Is My Work"

Eric described this naturally during the conversation and got it exactly right:

1. **Work in progress** - on disk, git doesn't have it. "Needs to be committed."

2. **Committed** - git has it locally. Versioned and safe on your machine.
   GitHub does not know yet.

3. **Pushed** - GitHub knows. The cloud has it. Team can see it. Survives hardware failure.

4. **Merged** - the branch work is in main. The branch's purpose is complete.
   Main is then pushed so GitHub's main reflects it.

---

## What "Nothing to Commit, Working Tree Clean" Means

When you see this message after switching branches, it means:
- No files on disk have been changed since the last commit on this branch
- Nothing is staged waiting to be committed
- The branch is at rest - everything that was worked on has been committed

It does NOT mean the branch is empty or that no work was done. It means all the
work that was done has already been captured in commits.

---

## The Full Branch Lifecycle in One Picture

    Create branch
         |
    Edit files (untracked / modified - git doesn't have it)
         |
    git add (staged - git is holding a snapshot)
         |
    git commit (committed - locked in local history)
         |
    git push origin branch-name (pushed - GitHub knows the branch)
         |
    ... more edit / add / commit / push cycles as needed ...
         |
    git checkout main
    git merge branch-name (merged into main locally)
         |
    git push origin main (main is final on GitHub)
         |
    Branch purpose complete