diff --git a/GIT_README.md b/GIT_README.md new file mode 100644 index 0000000..08c9622 --- /dev/null +++ b/GIT_README.md @@ -0,0 +1,181 @@ +# Git Guide: Cross-Machine Workflow & Branching + +This guide covers the daily Git workflow for working on the **WEBB** project across multiple locations (Office & Home), as well as an introduction to **Git Branching** for safe experimenting. + +--- + +## 🔄 1. Daily Multi-Location Workflow (Office 🏢 ↔ Home 🏠) + +Follow this exact loop to keep your work completely synchronized between your office machine and home machine without merge conflicts. + +``` + ┌──────────────────────┐ + │ GitHub Remote │ + │ vaishnosingh/webb │ + └──────────┬───────────┘ + ▲ ▲ + git push │ │ git push + (leave office) │ │ (leave home) + │ git pull │ git pull + │ (arrive office) │ (arrive home) + ▼ ▼ + ┌──────────────┐ ┌──────────────┐ + │ Office PC 🏢 │ │ Home PC 🏠 │ + └──────────────┘ └──────────────┘ +``` + +### 🏠 At Home (First Time Setup) +1. **Clone the repository**: + ```bash + git clone https://github.com/vaishnosingh/webb.git + cd webb + ``` +2. **Install dependencies**: + ```bash + npm install + ``` +3. **Start the local server**: + ```bash + npm run dev + ``` + +--- + +### 🏠 When You Finish Working at Home +Before stepping away or turning off your home computer, push your work to GitHub: + +1. **Check what changed**: + ```bash + git status + ``` +2. **Stage and commit your work**: + ```bash + git add . + git commit -m "feat: worked on components from home" + ``` +3. **Push to GitHub**: + ```bash + git push origin main + ``` + *(If prompted for credentials: username = your GitHub username, password = your GitHub Personal Access Token).* + +--- + +### 🏢 When You Arrive at the Office +Before making any edits, download the updates you made at home: + +1. **Open terminal in the project directory**: + ```bash + cd /home/creserver/Desktop/WEBB + ``` +2. **Pull latest changes**: + ```bash + git pull origin main + ``` + *(If you added any new npm packages at home, run `npm install`)* +3. You are now working directly from where you left off at home! + +--- + +### 🏢 When You Finish Working at the Office +Before leaving the office: + +```bash +git add . +git commit -m "feat: updates made at the office" +git push origin main +``` + +--- + +### 🌟 The Golden Rule +> **"Pull before you Start, Push before you Leave"** +> 1. **Morning / Start**: `git pull origin main` +> 2. **Evening / Finish**: `git add . && git commit -m "..." && git push origin main` + +--- + +## 🌿 2. Understanding Git Branching + +### What is a Branch? +In Git, **branching** is like making a safe, parallel sandbox of your website. It allows you to build features or test redesigns without any risk of breaking your main, working website. + +* **`main` (The Trunk)**: The stable, production-ready website code. +* **Feature Branch (The Sandbox)**: An isolated duplicate where you experiment freely. + +``` +main: ●──────●────────────────────────● (Merge back) + \ / +feature-redesign: ●──────●─────────────● (Safe experimenting) +``` + +--- + +### Why Use Branches? + +1. **Safety & Zero Risk**: If an experiment goes wrong, you simply delete the branch. Your `main` site stays completely untouched. +2. **Multiple Tasks Simultaneously**: Work on a big feature on a branch without blocking quick hotfixes on `main`. +3. **Clean Version History**: Each feature or experiment has its own organized log of commits. + +--- + +### 🛠️ Everyday Branching Cheat Sheet + +| Task | Command | +|---|---| +| **Create and jump into a new branch** | `git checkout -b feature-name` | +| **List all branches (highlights current)** | `git branch` | +| **Switch back to the main branch** | `git checkout main` | +| **Merge branch work into main** | `git merge feature-name` | +| **Delete feature branch when done** | `git branch -d feature-name` | +| **Discard branch without saving** | `git branch -D feature-name` | + +--- + +### 🎯 Real Example with Your Website (`WEBB`) + +Suppose you want to try a new redesign for the **Pricing Page**: + +1. **Create and switch to a feature branch**: + ```bash + git checkout -b redesign-pricing + ``` +2. **Make your code edits and test them locally**: + ```bash + npm run dev + ``` +3. **Commit your changes on the branch**: + ```bash + git add . + git commit -m "feat: experimental pricing layout" + ``` +4. **Choose your outcome**: + * **If you love it and want to keep it**: + ```bash + git checkout main + git merge redesign-pricing + git push origin main + ``` + * **If you don't like it and want to scrap it**: + ```bash + git checkout main + git branch -D redesign-pricing + ``` + *(Your project instantly returns to the stable working state!)* + +--- + +## 🧰 3. Troubleshooting & Quick Fixes + +### If you forgot to pull before editing: +If you edited code locally before pulling and Git says you have local changes: +```bash +git stash # Temporarily sets your local edits aside +git pull origin main # Gets the latest code from GitHub +git stash pop # Re-applies your local edits on top +``` + +### Save credentials so you don't retype tokens: +```bash +git config --global credential.helper store +``` diff --git a/README.md b/README.md index 3569032..4d7b639 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ > Built strictly to specification from `PROJECT_REQUIREMENT_DOCUMENTATION.md` (PRD v1.1). > Dynamic React (Next.js App Router + TypeScript + Tailwind CSS) marketing and try-it engine driven by JSON content and an external, replaceable API Catalogue connected to `FastAPI_BACKEND`. +> +> 📘 **Multi-Location Sync & Branching Guide:** See [GIT_README.md](./GIT_README.md). --- diff --git a/git_readme.md b/git_readme.md new file mode 120000 index 0000000..7dfc724 --- /dev/null +++ b/git_readme.md @@ -0,0 +1 @@ +GIT_README.md \ No newline at end of file