From cf21bc469261b22637661544f2f03afc01d0fd66 Mon Sep 17 00:00:00 2001 From: Vaishno Singh Date: Sat, 7 Nov 2026 02:33:53 +0530 Subject: [PATCH] docs: add cross-location workflow guide for office and home --- CROSS_LOCATION_WORKFLOW.md | 343 +++++++++++++++++++++++++++++++++++++ 1 file changed, 343 insertions(+) create mode 100644 CROSS_LOCATION_WORKFLOW.md diff --git a/CROSS_LOCATION_WORKFLOW.md b/CROSS_LOCATION_WORKFLOW.md new file mode 100644 index 0000000..76ca024 --- /dev/null +++ b/CROSS_LOCATION_WORKFLOW.md @@ -0,0 +1,343 @@ +# 🌐 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.*