docs: add comprehensive cross-location git workflow and architecture guide
This commit is contained in:
@@ -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 <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.*
|
||||
Reference in New Issue
Block a user