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.

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 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 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:

# 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:

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:

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

Verification Step: 🔍

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:

# 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:

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

Visual Checkpoint:

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:

    %%{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:

# 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:

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:

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

Visual Checkpoint:

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:

git push origin feature/add_new_feature

Visual Checkpoint:

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.