Git & GitLab Onboarding Guide

Welcome to the TechLit Africa team! This guide will help you set up your terminal environment so you can contribute to our lesson plans, websites, and system tools safely.

1. GitLab Account Setup

Before you start working in the terminal, you need a GitLab account.

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 or specific project.

2. GitLab Authentication

You have two ways to connect your computer to GitLab. Choose the one that works best for your workflow.

Option 1: SSH (Recommended)

SSH uses a “key pair” to prove your identity. Your private key stays on your machine, and your public key goes to GitLab.

Generate your key

Run this exact command to create a secure connection key. Note the -f flag—this ensures the key is saved where it won’t be deleted.

# Create the secure folder
mkdir -p /srv/public/teachers/zigzag/guest/.ssh

# Generate the key
ssh-keygen -t ed25519 -f /srv/public/teachers/zigzag/guest/.ssh/id_ed25519 -C "denis@techlitafrica.org"

Add the key to GitLab

1. View the key content:

   cat /srv/public/teachers/zigzag/guest/.ssh/id_ed25519.pub
2. Copy the output (the long string starting with ssh-ed25519).
3. Paste in GitLab: Navigate to Preferences → SSH Keys → Add new key. Paste your key and click “Add key”.

Verify the connection

Test the handshake by explicitly telling the computer to use your persistent key:

ssh -i /srv/public/teachers/zigzag/guest/.ssh/id_ed25519 -T git@gitlab.com

If you see Welcome to GitLab, @username!, you are ready to go.

Option 2: Personal Access Token (PAT)

If you prefer not to use SSH, you can use a Personal Access Token (PAT) to authenticate your Git commands over HTTPS.

1. Create your token:

   • Go to GitLab → Preferences (top right) → Access Tokens.
   • Click Add new token.
   • Name: “TechLit Laptop”.
   • Scopes: Select read_repository and write_repository.
   • Click Create personal access token and copy the string immediately. Store this safely—you won’t see it again.

2. Usage: When you git clone or git push a repository using an HTTPS URL, Git will ask for your username and password:

   • Username: Your GitLab username.
   • Password: Your newly created PAT.

The Git Status Mantra

Before you add a file, after you stage it, and right before you commit—run git status. Think of git status as the terminal user’s eyes. It tells you exactly what Git sees, what you have changed, and what needs to be saved. If you ever feel lost or aren’t sure what Git is doing, git status is the first command you should type. Make it a foundational habit!

The Golden Rule: Back Up Before You Edit

If you are about to try a Git command you don’t fully understand, or you’re doing a complex merge, always make a local duplicate of your project folder first. While Git is excellent at tracking history, a messy merge or an accidental file deletion can be stressful when you’re just starting out. A quick local copy gives you a 100% safe “undo button.”

# Navigate to your projects directory
cd /srv/public/teachers/zigzag/guest/projects/

# Duplicate your project folder as a safety backup before experimenting
cp -r websites websites-backup-before-git

# If everything goes completely wrong, you can easily restore it:
rm -rf websites
mv websites-backup-before-git websites

3. Working with Repositories

We keep all our projects organized in a central folder.

mkdir -p /srv/public/teachers/zigzag/guest/projects
cd /srv/public/teachers/zigzag/guest/projects

Cloning a Project

Choose one of our core repositories to start:

• techlit-africa/docs
• techlit-africa/websites
• techlit-africa/sheets
• techlit-africa/shell

git clone git@gitlab.com:techlit-africa/docs.git

4. Branching & Committing

Never work directly on the main branch. This ensures our production files stay clean while you experiment.

cd shell
# Create a "feature branch" for your task
git checkout -b feature/optimize-backup-script

Keep your branch current

If you haven’t worked on your feature branch for a few days, the main branch has likely moved forward. Keep your branch clean and conflict-free by rebasing:

# Update your local main
git switch main
git pull origin main

# Switch back to your feature branch
git switch feature/optimize-backup-script

# Rebase your changes on top of the updated main
git rebase main

5. Keeping Your Work Safe

Rule: If it isn’t pushed to GitLab, it doesn’t exist.

1. Commit early: Save your progress frequently with short, clear messages.

   git add .
   git commit -m "Update backup instructions for zigzag user"
2. Push immediately: Send your branch to GitLab so it’s backed up.

   git push origin feature/optimize-backup-script

6. Opening a Merge Request

Once your work is pushed, go to the project on GitLab and click the “Create Merge Request” button. This notifies the team that your changes are ready for review!

7. Crucial Warnings

Troubleshooting & Recovery: The Easiest Panic Buttons

Everyone gets stuck or makes a mistake eventually. Here are the two best ways to fix it:

The Folder-Level “Undo Button”

Remember the “Golden Rule” from earlier: if you are about to attempt a complex merge or a Git command you are unsure about, copy your project folder first!

# Duplicate the project folder before trying the tricky Git operation
cp -r /srv/public/teachers/zigzag/guest/projects/docs /srv/public/teachers/denis/guest/projects/docs-backup

If everything gets completely messy, you can simply remove the current folder and restore your backup:

rm -rf /srv/public/teachers/zigzag/guest/projects/docs
mv /srv/public/teachers/zigzag/guest/projects/docs-backup /srv/public/teachers/denis/guest/projects/docs

The Git-Level Escape Hatch

If you are in the middle of a git rebase and things are failing, don’t panic. You can stop the process entirely and revert to the state you were in before you started:

git rebase --abort

This command is your safe exit—it stops the rebase attempt and leaves your work exactly where it was.