Files
webb/CROSS_LOCATION_WORKFLOW.md
T

344 lines
13 KiB
Markdown

# 🌐 Complete Git Architecture & Cross-Location Workflow Guide
### For Working Between Office (🏢) and Home (🏠) on the WEBB Project
---
## Table of Contents
1. [Core Mental Model: What is Happening?](#1-core-mental-model-what-is-happening)
2. [Visual Architecture Diagrams](#2-visual-architecture-diagrams)
3. [Every Git Command Explained Line-by-Line](#3-every-git-command-explained-line-by-line)
4. [Step-by-Step Playbooks for Every Scenario](#4-step-by-step-playbooks-for-every-scenario)
- [Scenario A: Right Now & Tonight at HOME](#scenario-a-right-now--tonight-at-home)
- [Scenario B: Tomorrow Morning at the OFFICE](#scenario-b-tomorrow-morning-at-the-office)
- [Scenario C: Tomorrow Evening Leaving the OFFICE](#scenario-c-tomorrow-evening-leaving-the-office)
- [Scenario D: Tomorrow Night Arriving back HOME](#scenario-d-tomorrow-night-arriving-back-home)
5. [How and When to Merge (`work-at-home` ➔ `main`)](#5-how-and-when-to-merge-work-at-home--main)
6. [Emergency Troubleshooting & "What If?" Guide](#6-emergency-troubleshooting--what-if-guide)
---
## 1. Core Mental Model: What is Happening?
To feel 100% confident with Git, picture **three physical locations** and **two parallel tracks**:
```
[ Your Home PC 🏠 ] [ GitHub in the Cloud ☁️ ] [ Your Office PC 🏢 ]
Local storage Remote central repository Local storage
```
### The Two Parallel Tracks (Branches):
1. **`main`**: The official, production-ready website. This is what runs in the office. It must always stay clean and working.
2. **`work-at-home`**: Your private sandbox. Any experiments, optimizations, or incomplete features made at home stay here.
### Why this guarantees ZERO conflicts:
* If you edit files at home and push directly to `main`, your office machine might have different uncommitted edits on `main`. When you `git pull`, Git gets confused and creates **Merge Conflicts**.
* By keeping home work on `work-at-home`, the GitHub remote stores two completely independent sets of files.
* Your office computer never touches `work-at-home` unless you explicitly tell it to.
---
## 2. Visual Architecture Diagrams
### System Architecture Diagram
```
┌────────────────────────────────────────────────────────┐
│ GitHub Remote Repository │
│ vaishnosingh/webb │
│ │
│ [main branch] [work-at-home branch] │
│ (Production / Office) (Home Features / Sandbox) │
└──────────┬──────────────────────────┬──────────────────┘
│ │
git pull/push │ │ git pull/push
(on main) │ │ (on work-at-home)
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ Office PC 🏢 │ │ Home PC 🏠 │
│ Active branch: │ │ Active branch: │
│ `main` │ │ `work-at-home` │
└──────────────────────┘ └──────────────────────┘
```
### Timeline & Commit Tree Diagram
```mermaid
gitGraph
commit id: "Initial stable website"
commit id: "Office work commit A"
branch work-at-home
checkout work-at-home
commit id: "perf: remove smooth cursor & canvas"
commit id: "feat: home improvements"
checkout main
commit id: "Office work commit B"
checkout work-at-home
merge main id: "Sync office changes into home"
checkout main
merge work-at-home id: "Merge home features into main when ready"
```
---
## 3. Every Git Command Explained Line-by-Line
Here is the exact anatomy of every single command you will ever type, and what Git is doing behind the scenes:
### 1. `git status`
* **What it means:** "Git, inspect my folder right now and show me what changed."
* **What you see:** Green files (ready to save), red files (modified but not yet saved), or `"nothing to commit, working tree clean"`.
* **When to run it:** Anytime you are unsure what state your project is in. It never alters your files.
### 2. `git branch`
* **What it means:** "List all local branches and put a star (`*`) next to the one I am currently standing on."
* **Example Output:**
```text
main
* work-at-home
```
*(Here, `*` means you are currently editing inside `work-at-home`).*
### 3. `git checkout -b <new-branch-name>`
* **What it means:** "Create a brand new branch named `<new-branch-name>` and immediately switch my code to it."
* **Note:** The `-b` stands for **b**ranch. You only use `-b` the *first* time you create it.
### 4. `git checkout <existing-branch-name>`
* **What it means:** "Switch my active workspace to an already existing branch."
* **Example:** `git checkout main` switches all files on your screen back to the `main` version.
### 5. `git add .`
* **What it means:** "Stage all modified and newly created files in this directory."
* **The Dot (`.`):** Means "everything in the current folder".
* **Mental Model:** Putting all your changed files into a cardboard box before sealing it with tape.
### 6. `git commit -m "your message here"`
* **What it means:** "Permanently record a timestamped snapshot (checkpoint) of the staged files with an explanatory note."
* **The `-m` flag:** Stands for **m**essage.
* **Mental Model:** Sealing the cardboard box, putting a label on it, and stamping the date. This is stored on your local disk.
### 7. `git push origin <branch-name>`
* **What it means:** "Upload my local commits to the remote cloud server (`origin` = GitHub) into the branch `<branch-name>`."
* **Example:** `git push origin work-at-home` uploads your home work to the `work-at-home` branch on GitHub.
### 8. `git pull origin <branch-name>`
* **What it means:** "Download the latest commits from GitHub for `<branch-name>` and apply them directly to my local files."
* **When to use:** First thing in the morning before writing any code.
### 9. `git fetch origin`
* **What it means:** "Ask GitHub what branches exist and what changed, but do NOT modify my files yet."
* **When to use:** When you arrive at the office and want your office PC to discover the `work-at-home` branch from GitHub.
### 10. `git merge <branch-name>`
* **What it means:** "Take all the work from `<branch-name>` and combine it into whatever branch I am currently standing on."
### 11. `git stash` and `git stash pop`
* **`git stash`:** "Take my unsaved changes, put them into a temporary pocket, and revert my workspace to clean state so I can pull or switch branches."
* **`git stash pop`:** "Pull my unsaved changes out of the temporary pocket and re-apply them to my files."
---
## 4. Step-by-Step Playbooks for Every Scenario
---
### Scenario A: Right Now & Tonight at HOME 🏠
You are currently on your home machine. The branch `work-at-home` is already active and pushed.
#### 1. Check your branch:
```bash
git branch
```
*Confirm you see `* work-at-home`.*
#### 2. Do your coding:
```bash
npm run dev
```
Edit code, design components, test in your browser at `http://localhost:3000`.
#### 3. When you are done for the night (Push your work):
```bash
# Step 1: See what files you changed
git status
# Step 2: Stage all changes
git add .
# Step 3: Commit with a meaningful note
git commit -m "feat: added new sections and updated styles from home"
# Step 4: Push to your home branch on GitHub
git push origin work-at-home
```
*Your work is now securely stored in GitHub's cloud under `work-at-home`.*
---
### Scenario B: Tomorrow Morning at the OFFICE 🏢
You arrive at work, sit at your office PC (`/home/creserver/Desktop/WEBB` or similar).
You have **3 possible goals**:
#### Goal 1: You just want to do normal office work on `main`
```bash
# 1. Open terminal in project
cd /home/creserver/Desktop/WEBB
# 2. Make sure you are on main
git checkout main
# 3. Pull any latest office commits
git pull origin main
# 4. Start your day
npm run dev
```
*(Notice: The home work on `work-at-home` will NOT touch or break your office `main` branch).*
---
#### Goal 2: You want to PREVIEW the home work on your Office PC monitor
If you want to run and test the home optimizations on the office machine without affecting `main`:
```bash
# 1. Tell office Git to fetch all branches from GitHub
git fetch origin
# 2. Switch to the home branch
git checkout work-at-home
# 3. Run and test it
npm run dev
```
When you are done previewing, switch back to `main`:
```bash
git checkout main
```
---
#### Goal 3: You love the home work and want to MERGE it into `main` at the office
When you decide: *"The performance fixes made at home are awesome, let's make them part of our official main site!"*
```bash
# 1. Switch to main
git checkout main
# 2. Ensure main is up to date
git pull origin main
# 3. Merge the work-at-home branch into main
git merge work-at-home
# 4. Run tests or build to verify
npm test
npm run build
# 5. Push the updated main to GitHub
git push origin main
```
*Congratulations! The home optimizations are now officially in production on `main`.*
---
### Scenario C: Tomorrow Evening Leaving the OFFICE 🏢
Before turning off your office PC:
```bash
# 1. Check status
git status
# 2. Stage and commit anything you did in the office
git add .
git commit -m "feat: completed catalog manager changes at office"
# 3. Push to main
git push origin main
```
---
### Scenario D: Tomorrow Night Arriving back HOME 🏠
You get back home. Your office PC pushed new updates to `main`. You want those office updates inside your home setup so you don't fall behind.
```bash
# 1. Switch to your local main and pull the latest office updates
git checkout main
git pull origin main
# 2. Switch back to your home branch
git checkout work-at-home
# 3. Merge main into work-at-home (absorbs the office updates)
git merge main
# 4. Push your updated home branch to GitHub
git push origin work-at-home
```
*Now your home machine has BOTH your home work AND the latest office updates!*
---
## 5. Cheat Sheet Quick Reference
| Action | Machine | Commands |
|---|---|---|
| **Save & Push Home Work** | Home 🏠 | `git add .` <br> `git commit -m "..."` <br> `git push origin work-at-home` |
| **Download Updates at Office** | Office 🏢 | `git checkout main` <br> `git pull origin main` |
| **Inspect Home Work at Office** | Office 🏢 | `git fetch origin` <br> `git checkout work-at-home` |
| **Merge Home Work into Main** | Office 🏢 | `git checkout main` <br> `git merge work-at-home` <br> `git push origin main` |
| **Sync Office Updates into Home** | Home 🏠 | `git checkout work-at-home` <br> `git merge main` <br> `git push origin work-at-home` |
---
## 6. Emergency Troubleshooting & "What If?" Guide
### Q1: "Git says: 'error: Your local changes would be overwritten by checkout'"
* **Cause:** You edited a file, but didn't commit it before trying to switch branches.
* **Fix:**
```bash
# If you want to keep the edits:
git stash
git checkout <target-branch>
git stash pop
# If you want to throw away the edits:
git restore .
git checkout <target-branch>
```
### Q2: "What if there is a Merge Conflict?"
* **What it means:** You changed line 20 of a file at the office, AND you also changed line 20 of the same file at home. Git asks you to decide which line to keep.
* **Fix:**
1. Open the file in VS Code / Antigravity editor.
2. You will see markers:
```text
<<<<<<< HEAD
Office code
=======
Home code
>>>>>>> work-at-home
```
3. Delete the markers and keep the version you want.
4. Save the file and run:
```bash
git add .
git commit -m "fix: resolved merge conflict"
git push
```
### Q3: "How do I check what commits exist?"
```bash
git log --oneline -5
```
*Shows the last 5 commits in a clean one-line summary.*
### Q4: "How do I see what changed between main and work-at-home?"
```bash
git diff main..work-at-home
```
*Shows every line added or removed in the home branch compared to main.*