13 KiB
🌐 Complete Git Architecture & Cross-Location Workflow Guide
For Working Between Office (🏢) and Home (🏠) on the WEBB Project
Table of Contents
- Core Mental Model: What is Happening?
- Visual Architecture Diagrams
- Every Git Command Explained Line-by-Line
- Step-by-Step Playbooks for Every Scenario
- How and When to Merge (
work-at-home➔main) - 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):
main: The official, production-ready website. This is what runs in the office. It must always stay clean and working.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 onmain. When yougit 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-homeunless 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:
(Here,
main * work-at-home*means you are currently editing insidework-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
-bstands for branch. You only use-bthe 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 mainswitches all files on your screen back to themainversion.
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
-mflag: 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-homeuploads your home work to thework-at-homebranch 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-homebranch 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:
- Open the file in VS Code / Antigravity editor.
- You will see markers:
<<<<<<< HEAD Office code ======= Home code >>>>>>> work-at-home - Delete the markers and keep the version you want.
- 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.