Files
webb/CROSS_LOCATION_WORKFLOW.md
T

13 KiB

🌐 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?
  2. Visual Architecture Diagrams
  3. Every Git Command Explained Line-by-Line
  4. Step-by-Step Playbooks for Every Scenario
  5. How and When to Merge (work-at-home ➔ main)
  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

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:
      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 branch. 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 message.
  • 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:

git branch

Confirm you see * work-at-home.

2. Do your coding:

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):

# 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

# 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:

# 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:

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!"

# 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:

# 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.

# 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:
    # 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:
      <<<<<<< HEAD
      Office code
      =======
      Home code
      >>>>>>> work-at-home
      
    3. Delete the markers and keep the version you want.
    4. Save the file and run:
      git add .
      git commit -m "fix: resolved merge conflict"
      git push
      

Q3: "How do I check what commits exist?"

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?"

git diff main..work-at-home

Shows every line added or removed in the home branch compared to main.