# Git & GitLab Onboarding: Working Safely on TechLit Computers

Welcome to the TechLit Africa contributor team! This guide will walk you through setting up your terminal environment on our workstations. Because our default user home is reset on logout, we must use specific persistent paths to ensure your security keys and code projects are never lost.

{{< callout type="error" >}}
⚠️ **CRITICAL: PERSISTENT vs. EPHEMERAL STORAGE**
On all standard **TechLit computers**, the default home directory (`~` or `/home/guest`) is wiped completely every time you log out or the system resets. To prevent losing your work, you **must** use the persistent storage area at `/srv/public/`.
{{< /callout >}}

{{< callout type="info" >}}
**Note on Usernames:** In the examples below, we use the name `denis`. **This is a placeholder.** Please replace `denis` with your actual TechLit username (e.g., `/srv/public/teachers/amina/guest/`) whenever you type a command.
{{< /callout >}}

---

## Phase 1: 🔑 Environment & Key Provisioning

> **Objective:** Setup your GitLab account, generate persistent security keys, and configure your global Git identity.
> **Estimated time:** 10 minutes

### 1.1 GitLab Account Setup

Before you start working in the terminal, you need a GitLab account to identify your contributions.

1. **Register:** Go to [GitLab.com](https://gitlab.com) and create a free account.
2. **Join the Group:** Once your account is ready, request **GitLab write access** on WhatsApp. Provide your GitLab username, and you will be added to the [techlit-africa](https://gitlab.com/techlit-africa) workspace.

### 1.2 Persistent SSH Configuration

To connect to GitLab without a password, we generate an SSH key. We store this in your persistent folder so it survives a logout.

**Action Commands:**

```bash
# 1. Create the secure folder (Use your actual username instead of 'denis')
mkdir -p /srv/public/teachers/denis/guest/.ssh

# 2. Cd into your persistent guest directory
cd /srv/public/teachers/denis/guest

# 3. Generate the key
ssh-keygen -t ed25519 -f .ssh/id_ed25519 -C "denis@techlitafrica.org"

# 4. Link for GitLab Access (Removes need for -i flag)
ln -s /srv/public/teachers/denis/guest/.ssh/id_ed25519 /srv/guest/gitlab_ssh
```

**Verification Step:** 🔍

**Visual Checkpoint:**
{{< asciinema file="casts/ssh-setup.cast" autoplay=false >}}

### 1.3 Git Identity Setup

Git needs to know who is making changes so that your name appears correctly in the project history.

**Action Commands:**

```bash
# Set your name and email
git config --global user.name "Denis"
git config --global user.email "denis@techlitafrica.org"
```

{{< callout type="warning" >}}
**Note:** Global Git configuration is stored in `~/.gitconfig`, which is wiped on logout. To make your identity persistent, you can symlink it to your persistent folder:
`ln -s /srv/public/teachers/denis/guest/.gitconfig ~/.gitconfig`
{{< /callout >}}

**Verification Step:** 🔍

```bash
git config --list
```

---

## Phase 2: 💡 Local Workspace & The 3-Stage Pipeline

> **Objective:** Create safety backups, clone the project, and master the local saving cycle.
> **Estimated time:** 15 minutes

### 2.1 🛡️ Safe Folder Backups: Your Manual Undo Button

Before practicing Git commands, always make a local duplicate of your folder. This is your 100% safe "undo button" if a command gets confusing.

**Action Commands:**

```bash
# 1. Navigate to your projects directory
cd /srv/public/teachers/denis/guest/projects

# 2. Duplicate your project folder before experimenting
cp -r websites websites_backup
```

### 2.2 🔍 The "Git Status" Mantra

Think of `git status` as the terminal user's eyes. Run it before you add a file, after you stage it, and right before you commit. If you ever feel lost, `git status` is the first command you should type.

### 2.3 Project Cloning

Pull the `websites` repository from GitLab into your persistent projects folder.

**Action Commands:**

```bash
git clone git@gitlab.com:techlit-africa/websites.git
cd websites
ls
```

**Visual Checkpoint:**
{{< asciinema file="casts/clone.cast" autoplay=false >}}

### 2.4 Saving Your Work: The Three Stages

Git uses a holding zone to help you organize what you save.

1. **Modified:** You have edited a file (e.g., `src/main.js`) but haven't told Git to save it yet.
2. **Staged (`git add`):** You have picked which changes you want to include in your next save. Think of this as putting files into a "to-be-saved" box.
3. **Committed (`git commit`):** You have permanently saved the snapshot of your staged files to your local history.

**Branching & Staging:**

```mermaid
%%{init: { 'theme': 'default', 'themeVariables': { 'fontSize': '28px' }}}%%
graph LR
    subgraph Remote["GitLab (Remote Server)"]
        RM[main branch]
        RFB[remote branch]
        MR{Merge Request}
    end

    subgraph Local["Your dev computer (Persistent)"]

        LM[main branch]
        FB[feature-branch]
        
        Edit[Edit Files] --> Modified(Modified)
        Modified -- "git add" --> Staged(Staged)
        Staged -- "git commit" --> Committed(Committed)
    end

    RM -- "git clone" --> LM
    LM -- "git switch -c feature-branch" --> FB
    FB --> Edit
    Committed -- "git push" --> RFB
    RFB -- "Open MR" --> MR
    MR -- "Merged" --> RM
```


---

## Phase 3: 🚀 Team Sync & Upstream Collaboration

> **Objective:** Master feature branching, keep your work current, and share changes via Merge Requests.
> **Estimated time:** 15 minutes

### 3.1 Feature Branching Workflow

We never edit the `main` branch directly. We use **Feature Branches** to keep our production code stable.

**Action Commands:**

```bash
# 1. Start with the latest code
git switch main
git fetch origin
git pull origin main

# 2. Create your experimental branch
git switch -c feature/add_new_feature
```

**Visual Checkpoint:**
{{< asciinema file="casts/sync.cast" autoplay=false >}}

### 3.2 🔍 Keeping Your Branch Current

If you haven't worked on your feature branch for a few days, rebase it to include the latest team changes.

**Action Commands:**

```bash
git switch main
git pull origin main
git switch feature/add_new_feature
git rebase main
```

**Visual Checkpoint:**
{{< asciinema file="casts/branch-commit.cast" autoplay=false >}}

### 3.3 Pushing Changes & Opening an MR

Once you have committed your work locally, send it to GitLab to share it with the team.

**Action Command:**

```bash
git push origin feature/add_new_feature
```

**Visual Checkpoint:**
{{< asciinema file="casts/push-mr.cast" autoplay=false >}}

### 3.4 ⚠️ Troubleshooting & Escape Hatches

* **The Escape Hatch:** If a rebase or merge becomes confusing, go back to safety with `git rebase --abort`.
* **Clean Workspaces:** Always check your `.gitignore` to ensure temporary files aren't being tracked.
* **The snapshot rule:** Anything left in `~/` or `/home/guest` **disappears forever** on logout. Always verify your path with `pwd`.

**Congratulations!** You are now ready to contribute safely and effectively to the TechLit Africa project.

