# 🌐 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 ` * **What it means:** "Create a brand new branch named `` 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 ` * **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 ` * **What it means:** "Upload my local commits to the remote cloud server (`origin` = GitHub) into the branch ``." * **Example:** `git push origin work-at-home` uploads your home work to the `work-at-home` branch on GitHub. ### 8. `git pull origin ` * **What it means:** "Download the latest commits from GitHub for `` 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 ` * **What it means:** "Take all the work from `` 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 .`
`git commit -m "..."`
`git push origin work-at-home` | | **Download Updates at Office** | Office 🏢 | `git checkout main`
`git pull origin main` | | **Inspect Home Work at Office** | Office 🏢 | `git fetch origin`
`git checkout work-at-home` | | **Merge Home Work into Main** | Office 🏢 | `git checkout main`
`git merge work-at-home`
`git push origin main` | | **Sync Office Updates into Home** | Home 🏠 | `git checkout work-at-home`
`git merge main`
`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 git stash pop # If you want to throw away the edits: git restore . git checkout ``` ### 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.*