docs: add GIT_README guide for cross-machine workflow and branching
This commit is contained in:
+181
@@ -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
|
||||
```
|
||||
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
Symlink
+1
@@ -0,0 +1 @@
|
||||
GIT_README.md
|
||||
Reference in New Issue
Block a user