Braids - Intro to Git

Goal: introduce Git as an archiving practice, then do a little branch-based website exercise published live.

Planning (90 min)

Context: what Git is, what it does, who uses it (10 min)
Install Git (10 min)
Core concepts + core commands (20 min)
Forgejo: accounts + clone/push permissions (10 min)
Exercise: branch a page, publish live, iterate (35 min)
Wrap-up: good practices + next steps (5 min)

What is Git

Distributed version control system
Tracks changes over time
Enables: - history (time) - collaboration (many authors) - experimentation (branches) - traceability (who/what/when/why)

Archiving analogy:

commit = deposit with metadata
log = inventory / finding aid
branch = parallel dossier / alternative interpretation

What Git is not

Git ≠ Github!
Not a backup system (though it can help)
Not a file sync tool
Not a CMS
Not magic: it stores snapshots + metadata, you still choose what to record

Ecosystem

Git = the tool + file format
Hosting platforms: - GitHub, Bitbucket, GitLab - Alternatives: - Codeberg (non-profit, community led) - Oxacab (riseup.net for activists, journalists) - Forgejo / Gitea (self-hosted)

@karl: should we add some apps for working with git here? VSC + Git lens, Github desktop, Sourcetree etc

Typical workflow

remote (server copy)
clone (get a copy)
push (send your commits back to the server)
pull/fetch (receive updates)

Install Git

Check first:

git --version

If missing:

macOS: Xcode Command Line Tools
Windows: Git for Windows
Linux: package manager (apt/dnf/pacman)

Minimum requirement: you can run git in a terminal.

Core concept: three areas

Working tree: your files right now
Staging area (index): selection for the next deposit
Repository history: commits (deposits)

This is why Git feels "archival":

you intentionally select what becomes part of the record.

Commands: the essential set

git status (always)
git init (initalise a repo)
git commit (store changes in the repo)
git add (add files to the commit)
git branch (take a detour)
git merge (merge branches)
git checkout (get the repo at a specific state)
git fetch (sync with a repo online)
git pull (sync with a repo online and merge)
git diff (what changed)
git log (history)
plus: log, diff

Command: git init

Create a repository in the current folder. Use this when you are creating and working on your own projects.

git init

Creates a .git/ directory containing history + metadata.

For the exercise we will use git clone instead of git init.

Command: git clone

Cloen (copy) a repository in the current folder.

git clone https://git.hackersanddesigners.nl/hrk/braids <destination>

Downloads a repo from the web, complete with the full commit history and all changes.

Command: git status (your dashboard)

git status

Shows:

current branch
staged vs unstaged changes
untracked files

Command: git add (select files)

Stage files for the next commit.

git add index.html
git add assets/

Stage everything (use carefully):

git add .

Staging is curatorial: select what belongs together.

Command: git commit

git commit -m "Added name to my page"

Good commit message pattern:

What changed
Why it changed (reason/intent)
Scope stays small

Command: git log (inventory)

git log --oneline --graph

Gives a quick "finding aid" of earlier commits. Press 'q' to exit.

Command: git branch and git checkout

List branches:

git branch

Create a branch:

git branch people/yourname

Switch to branch:

git checkout people/yourname

Shortcut (create + switch):

git checkout -b people/yourname

Branches are parallel dossiers: safe space for changes.

Command: git push / git pull

Push your branch to the server:

git push -u origin people/yourname

Pull updates from server:

git pull

During the exercise you mostly push your branch. Pull is mainly for getting new changes on main (if needed).

Optional: git rm

Remove a tracked file and stage the removal:

git rm old.html
git commit -m "Remove old page"

For this workshop you probably will not need it.

Forgejo: what we use today

Forgejo is an open-source alternative to Github
Forgejo hosts the central repository (remote)

You will: - create an account - clone via HTTPS - push your branch

Share your username with us so we can add you as a collaborator

Rules for today:

do NOT push to main
create your branch under people/<your-slug>

Forgejo: account setup

Create account at: git.hackersanddesigners.nl
Confirm you can sign in

Resources:

https://git.hackersanddesigners.nl/hrk/braids - the repo we will be working in
live gallery URL: https://braids.hackersanddesigners.nl
these slides: https://braids.hackersanddesigners.nl/slides

Exercise overview

You will build a (deliberately) simple page:

"Hi, I'm …"
maybe a gif?
a link?
optional: background, glitter, bad taste encouraged

Workflow loop:

clone -> branch -> edit -> status -> add -> commit -> push -> view -> iterate

Exercise: step 1 (clone)

cd to a logical location in your computer, then:

git clone https://git.hackersanddesigners.nl/hrk/braids
cd braids

If everything went well, check the repo with:

git status
git branch

The first time you checkout from https://git.hackersanddesigners.nl the server will ask you for credentials. These will be remembered, so only once.

Exercise: step 2 (create your branch)

Choose a slug: lowercase, no spaces. This can be your name or an alias. Example: change people/<your-slug> in the command below to people/alex. From here on out replace <your-slug> with your chosen name.

git checkout -b people/<your-slug>

Confirm:

git status

Exercise: step 3 (edit the page)

Edit the root index.html (and optionally style.css, assets/).

Make a visible change first:

Change the name to your name (or your alias)

Then check changes:

git diff
git status

Exercise: step 4 (stage + commit)

git add index.html
git commit -m "Customize profile page for <your-slug>"

If you added assets:

git add assets/
git commit -m "Add assets for <your-slug>"

Small commits win. One change = one deposit.

Exercise: step 5 (push your branch)

git push -u origin people/<your-slug>

(Again, change <your-slug>!)

If prompted for credentials, use your Forgejo login method.

Exercise: step 6 (view live)

Open the gallery:

https://braids.hackersanddesigners.nl/

Find your card:

people/<your-slug>/

Iterate:

edit -> status -> add -> commit -> push -> refresh

Common problems (fast fixes)

Wrong branch:

git branch
git checkout people/<your-slug>

Nothing staged:

git status
git add index.html

Push rejected (main protected):

You are on main. Switch to your branch.

Auth issues:

HTTPS: check username/password

Concept recap in archiving terms

commit = deposit (with minimal metadata)
log = inventory / chain of custody
diff = conservation report (what changed)
branch = parallel dossier
push = share publicly / deposit to institutional archive (remote)

Suggested “good enough” commit messages

Bad:

"update"
"stuff"
"changes"

Better:

"Add animated gif and profile link"
"Change background and typography"
"Fix broken image path"

Rule: message should still make sense in 6 months.

Optional extension (if time remains)

Compare two branches visually (gallery view)
Show git log to narrate your work as a documented process

Wrap-up

Learn more:

End: remind participants their branches will be removed after the workshop.