Braids - Intro to Git

# Braids - Intro to Git
Author: H&D

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

# Agenda (90 min)

1. Context: what Git is, what it does, who uses it (10 min)
2. Install Git (10 min)
3. Core concepts + core commands (20 min)
4. Forgejo: accounts + clone/push permissions (10 min)
5. Exercise: branch a page, publish live, iterate (35 min)
6. 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

- 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, GitLab, Bitbucket - Forgejo / Gitea (self-hosted)

# Typical workflow

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

# Workshop outcome

Each participant will:

- clone a repo
- create a branch
- edit a simple profile website
- commit changes with a clear message
- push branch to Forgejo
- see it appear in the live gallery

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

# Configure identity (once)

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

Check:

    git config --global --list

This shows up in commit metadata (provenance).

# Core concept: three areas

1. Working tree: your files right now
2. Staging area (index): selection for the next deposit
3. 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 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/<slug>

# Forgejo: account setup

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

We will provide:

- https://git.hackersanddesigners.nl/hrk/braids
- branch naming convention
- live gallery URL: braids.hackersanddesigners.nl

# 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

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

    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)
- Add a second commit that intentionally breaks something, then fix it with a third commit
- Show git log to narrate your work as a documented process

# Wrap-up

You should now be able to:

- create a branch safely
- record changes as commits
- publish to a remote
- read history and differences

Learn more:

- Learn Git Branching
- Oh My Git

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