Add docs/restore_repo.md

docs/restore_repo.md

@@ -0,0 +1,182 @@
+# Restoring a Lost Git Repository (Simple Guide)
+
+This guide is for users who have a project folder on their computer/server, and the **remote repository** was deleted or lost.
+
+Goal: **Back up your project safely** and then **push it again** to a **new empty remote repository**, keeping **all history, branches, and tags**.
+
+---
+
+## What you need
+
+* You have the project folder on your computer/server.
+* Git is installed.
+* You can log in to the https://git.ourworld.tf website and create a **new empty repository**.
+
+> **Important:** The new remote repository should be **empty** (no README, no initial commit), if possible.
+
+---
+
+## Step 1 — Go to your project folder
+
+Open Terminal (or Command Prompt) and go into your project folder.
+
+Example:
+
+```bash
+cd /path/to/your/project
+```
+
+To confirm you’re in the right folder:
+
+```bash
+git status
+```
+
+If you see something like `On branch ...` you’re in the correct place.
+
+---
+
+## Step 2 — Make a safe backup (highly recommended)
+
+### Option A: Make a “Git bundle” (best and simplest)
+
+A **bundle** is a single file that contains your **full project history** (commits, branches, tags).
+
+Run:
+
+```bash
+git bundle create ~/my_project_backup.bundle --all
+```
+
+Then verify it:
+
+```bash
+git bundle list-heads ~/my_project_backup.bundle
+```
+
+You should see branch names like `refs/heads/master`, `refs/heads/main`, or others.
+
+✅ Keep this `.bundle` file somewhere safe.
+
+### Option B: Copy the entire folder
+
+You can also copy your whole project folder somewhere safe.
+
+Example:
+
+```bash
+cp -r /path/to/your/project /path/to/backup/location/
+```
+
+This protects you if something goes wrong.
+
+---
+
+## Step 3 — Create the new remote repository (on the website)
+
+On https://git.ourworld.tf :
+
+1. Click **New Repository**
+2. Choose a name (can be the same name or different)
+3. **Do not initialize** with README / .gitignore / license (recommended)
+4. Create the repository
+
+Copy the new repository URL. It will look like one of these:
+
+* HTTPS: `https://git.ourworld.tf/ourworld_web/www_threefold_io.git`
+* SSH: `git@git.ourworld.tf:ourworld_web/www_threefold_io.git`
+
+---
+
+## Step 4 — Point your local project to the new remote
+
+Check your current remote:
+
+```bash
+git remote -v
+```
+
+Now set the new remote URL (replace with your new URL):
+
+```bash
+git remote set-url origin https://git.ourworld.tf/org/repo.git
+```
+
+Confirm:
+
+```bash
+git remote -v
+```
+
+---
+
+## Step 5 — Make sure the new remote is empty
+
+Run:
+
+```bash
+git ls-remote origin
+```
+
+* If it prints **nothing**, the remote is empty ✅
+* If it prints commit hashes, the remote is not empty
+
+If it’s not empty, you can still restore, but you may need **force push** (see Step 7).
+
+---
+
+## Step 6 — Push everything (history + branches + tags)
+
+Push **all branches**:
+
+```bash
+git push -u origin --all
+```
+
+Push **all tags**:
+
+```bash
+git push origin --tags
+```
+
+✅ This restores the repository with full history.
+
+---
+
+## Step 7 — If the remote was not empty (force push)
+
+Only use this if the remote already has commits (like an auto README) and you want your local project to become the “truth”.
+
+```bash
+git push --force origin --all
+git push --force origin --tags
+```
+
+⚠️ Warning: Force push overwrites the remote history.
+
+---
+
+## Quick checklist
+
+* [ ] I made a backup (bundle or folder copy)
+* [ ] I created a **new empty** remote repo
+* [ ] I updated `origin` to the new URL
+* [ ] I pushed **all branches** and **all tags**
+* [ ] I verified with `git ls-remote`
+
+---
+
+## One‑page “Do This” summary
+
+```bash
+cd /path/to/project
+
+git bundle create ~/project_backup.bundle --all
+
+git remote set-url origin https://example.com/org/repo.git
+
+git push -u origin --all
+git push origin --tags
+
+git ls-remote --heads --tags origin
+```