1. Principles and Practices

Git & Version Control

The first thing we set up was Git — a version control software that tracks every change you make to your files over time. Each saved change is called a commit. Think of it as a detailed history of your work that you can always go back to.

Git runs locally on your machine through the terminal. It connects to GitLab — the cloud platform where Fab Academy hosts all student repositories. GitLab is open source and runs on Fab Academy’s own servers, which gives more control and long-term access compared to platforms like GitHub. The relationship between the two is simple: Git is the tool, GitLab is where the work lives.

Setting Up Git

• Step 1 — Install Git Open the terminal and install Git using Homebrew: brew install git Verify the installation ran correctly by typing:

git --version

• Step 2 — Configure your identity Tell Git who you are. This information gets attached to every commit you make:

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Setting Up SSH Authentication

SSH is how your local machine proves its identity to GitLab — instead of entering a password every time, GitLab recognizes your computer as a trusted device. Think of it like answering the phone and recognizing someone’s voice before they’ve even said who they are.

Step 1 — Generate an SSH key

In the terminal, run:

ssh-keygen -t rsa

This creates two files — a private key that stays on your machine, and a public key that you share with GitLab.

Step 2 — Add the public key to GitLab

Copy the contents of your public key:

cat ~/.ssh/id_rsa.pub

Then go to GitLab → Settings > SSH Keys and paste it in. GitLab will now recognize your machine.

Step 3 — Test the connection

ssh -T git@gitlab.fabcloud.org

If it responds with a welcome message, the connection is working.

Cloning the Repository

With SSH set up, the next step is to clone your remote GitLab repository to your local machine. This creates a local folder that is both a working directory and a live connection to the GitLab server.

Go to your personal repository on GitLab Click the Clone button and select Clone with SSH Copy the URL and run the following in your terminal:

git clone git@gitlab.fabcloud.org:your.username/fabacademy.git

You now have a local folder that mirrors your GitLab repository. Any changes you make here can be pushed back up to the server.

The Git Workflow

Every time you make changes and want to publish them, follow this four step sequence:

1. Check what has changed

git status

This shows you which files have been modified or added since your last commit.

1. Stage your changes

git add .

This prepares all modified files to be committed. If you only want to stage specific files, replace the . with the filename.

1. Commit with a message

git commit -m "describe what you changed"

Write a short, specific message — “Added week 3 documentation” is more useful than “update”. Your commit history becomes a readable log of your progress.

1. Push to GitLab

git push origin main

This uploads your committed changes to the GitLab server. After pushing, check the GitLab web interface to confirm the pipeline has run successfully and your changes are live.

Setting Up MkDocs MkDocs is the tool that turns your Markdown files into a website. Markdown is a simple writing language — you write plain text with basic formatting symbols and MkDocs renders it into clean web pages. It’s designed for beginners and does the heavy lifting of web development for you. Install MkDocs through the terminal with:

curl -LsSf https://astral.sh/uv/install.sh | sh

Once installed, your local repository folder contains a docs folder where all your Markdown files live. Edit those files, save, and push — the site updates automatically via the GitLab pipeline. To preview your site locally before pushing:

mkdocs serve

This runs a local version of your site at http://127.0.0.1:8000 so you can check everything looks right before it goes live.