docs: add GIT_README guide for cross-machine workflow and branching

This commit is contained in:
2026-11-06 18:46:04 +05:30
parent 1a2a3045f5
commit ef6cacb32d
3 changed files with 184 additions and 0 deletions
+181
View File
@@ -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
View File
@@ -2,6 +2,8 @@
> Built strictly to specification from `PROJECT_REQUIREMENT_DOCUMENTATION.md` (PRD v1.1). > 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`. > 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).
--- ---
+1
View File
@@ -0,0 +1 @@
GIT_README.md