From ca6954b2a5b639f6ba39697fb75f79159bab9afb Mon Sep 17 00:00:00 2001 From: Heerko Date: Fri, 9 Jan 2026 13:25:53 +0100 Subject: [PATCH] update readme --- README.md | 7 +- html_output/index.html | 26 +- html_output/slides.css | 7 + slides.css | 3 +- slides.rst | 581 ++++++++++++++++++++++++++++++++++++----- 5 files changed, 557 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index ecc4569..93ac10c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,5 @@ -# Soilpunk - Joulethief - -## [View the slides here](https://hackersanddesigners.github.io/soilpunk_joulethief_slides/html_output/index.html) or the [plain text document here](https://github.com/hackersanddesigners/soilpunk_joulethief_slides/blob/master/slides.rst) - ----- +Braids - Git workshop slides +============================ The slides are generated from a .rst by [Hovercraft](https://github.com/regebro/hovercraft). - [Docs](https://hovercraft.readthedocs.io/en/latest/presentations.html#) diff --git a/html_output/index.html b/html_output/index.html index 39e112d..8e40ce0 100644 --- a/html_output/index.html +++ b/html_output/index.html @@ -1,7 +1,29 @@ -Soilpunk Joulethief

Soilpunk 🌏🤘 - Joulethief

Soilpunk - Joulethief

This document is viewable as a webpage or as a slideshow

Joulethief

Transistor

Water analogy: the little bit of water from B to E opens the gate for the bigger flow from C to E

Joulethief

Joulethief

A small current flows from the battery through the coil and the base-emitter path of the transistor. This opens the emittor-collector path of the transistor.

Joulethief

Electricity is now able to travel through the second coil and through the collector-emitter channel of the transistor.

Joulethief

The increasing amount of electricity through the second coil generates a negative voltage in the first coil, which cause the transistor to close.

Joulethief

With the transistor closed the energy starts to flow through the output (led).

Joulethief

The inductor is now powered by the magnetic field of the coil.

Joulethief

When the magnetic field is gone, the whole process starts over.

Joulethief

A more detailed explanation can be found on instructables

Led

Make sure to get the LED polarity right. Short leg goes to ground!

Circuit

https://github.com/hackersanddesigners/Soilpunk_joulethief

\ No newline at end of file +

Braids - Intro to Git

Braids - Intro to Git

Goal: introduce Git as an archiving practice (history, provenance, selection), +then do a playful branch-based website exercise published live.

Agenda (90 min)

  1. Context: what Git is, what it does, who uses it (10 min)
  2. Install + quick sanity check (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.

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 <repo_url> <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 diff (what changed)

Unstaged changes:

git diff

Staged changes:

git diff --staged

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/SSH +- push your branch

Rules for today:

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

Forgejo: account setup

  1. Create account at: git.<your-domain>
  2. Confirm you can sign in
  3. Add SSH key (optional) OR use HTTPS credentials

We will provide:

  • repo URL
  • branch naming convention
  • live gallery URL: braids.<your-domain>

Exercise overview

You will build a deliberately simple “MySpace-style” page:

  • "Hi, I'm …"
  • one gif
  • one link
  • optional: background, glitter, bad taste encouraged

Workflow loop:

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

Exercise: step 1 (clone)

git clone <REPO_URL>
+cd <REPO_NAME>

Sanity check:

git status
+git branch

Exercise: step 2 (create your branch)

Choose a slug: lowercase, no spaces. Example: 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:

  • your name
  • one gif
  • one link

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>

If prompted for credentials, use your Forgejo login method.

Exercise: step 6 (view live)

Open the gallery:

  • https://braids.<your-domain>/

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/token/password
  • SSH: check key added to Forgejo + ssh -T

Concept recap in archiving terms

  • commit = deposit (with minimal metadata)
  • log = inventory / chain of custody
  • diff = conservation report (what changed)
  • branch = parallel dossier
  • push = 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"
  • "Refactor layout: move link block above gif"

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

Next steps:

  • merging via PRs (review workflow)
  • tags/releases (archival milestones)
  • basic collaboration patterns (feature branches)

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

\ No newline at end of file diff --git a/html_output/slides.css b/html_output/slides.css index f5fad89..e709ee6 100644 --- a/html_output/slides.css +++ b/html_output/slides.css @@ -98,4 +98,11 @@ div#the-slide-id img{ position: absolute; top: 0; left: 0; +} + +.bash { + background-color: #eee; + /* color: white; */ + padding: 1rem; + border-radius: 1rem; } \ No newline at end of file diff --git a/slides.css b/slides.css index f5fad89..01ec223 100644 --- a/slides.css +++ b/slides.css @@ -98,4 +98,5 @@ div#the-slide-id img{ position: absolute; top: 0; left: 0; -} \ No newline at end of file +} + diff --git a/slides.rst b/slides.rst index 1c0cfd7..3dd2e50 100644 --- a/slides.rst +++ b/slides.rst @@ -1,123 +1,586 @@ -:title: Soilpunk Joulethief -:author: Heerko van der Kooij +:title: Braids - Intro to Git +:author: H&D :description: :css: slides.css .. header:: - Soilpunk 🌏🤘 - Joulethief + Braids - Intro to Git ---- -Soilpunk - Joulethief +Braids - Intro to Git +===================== + +.. note:: + + Goal: introduce Git as an archiving practice (history, provenance, selection), + then do a playful branch-based website exercise published live. + +---- + +Agenda (90 min) +=============== + +1. Context: what Git is, what it does, who uses it (10 min) +2. Install + quick sanity check (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: + +.. code-block:: bash + + 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) +========================= + +.. code-block:: bash + + git config --global user.name "Your Name" + git config --global user.email "you@example.com" + +Check: + +.. code-block:: bash + + git config --global --list + +.. note:: + + 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. + +.. code-block:: bash + + git init + +Creates a `.git/` directory containing history + metadata. + +.. note:: + + For the exercise we will use `git clone` instead of `git init`. + + +---- + +Command: git clone +================== + +Cloen (copy) a repository in the current folder. + +.. code-block:: bash + + git clone + +Downloads a repo from the web, complete with the full commit history and all changes. + +---- + +Command: git status (your dashboard) +==================================== + +.. code-block:: bash + + git status + +Shows: + +- current branch +- staged vs unstaged changes +- untracked files + +---- + +Command: git add (select files) +=============================== + +Stage files for the next commit. + +.. code-block:: bash + + git add index.html + git add assets/ + +Stage everything (use carefully): + +.. code-block:: bash + + git add . + +.. note:: + + Staging is curatorial: select what belongs together. + +---- + +Command: git commit +======================================== + +.. code-block:: bash + + git commit -m "Added name to my page" + +Good commit message pattern: + +- What changed +- Why it changed (reason/intent) +- Scope stays small + +---- + +Command: git diff (what changed) +================================ + +Unstaged changes: + +.. code-block:: bash + + git diff + +Staged changes: + +.. code-block:: bash + + git diff --staged + +---- + +Command: git log (inventory) +============================ + +.. code-block:: bash + + git log --oneline --graph + +Gives a quick "finding aid" of earlier commits. Press 'q' to exit. + +---- + +Command: git branch and git checkout +==================================== + +List branches: + +.. code-block:: bash + + git branch + +Create a branch: + +.. code-block:: bash + + git branch people/yourname + +Switch to branch: + +.. code-block:: bash + + git checkout people/yourname + +Shortcut (create + switch): + +.. code-block:: bash + + git checkout -b people/yourname + +.. note:: + + Branches are parallel dossiers: safe space for changes. + +---- + +Command: git push / git pull +============================ + +Push your branch to the server: + +.. code-block:: bash + + git push -u origin people/yourname + +Pull updates from server: + +.. code-block:: bash + + git pull + +.. note:: + + 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: + +.. code-block:: bash + + 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/SSH + - push your branch + +Rules for today: + +- do NOT push to `main` +- create your branch under `people/` + +---- + +Forgejo: account setup ====================== -This document is viewable as `a webpage `_ or as `a slideshow `_ +1. Create account at: `git.` +2. Confirm you can sign in +3. Add SSH key (optional) OR use HTTPS credentials + +We will provide: + +- repo URL +- branch naming convention +- live gallery URL: `braids.` ---- -:id: joulethief +Exercise overview +================= -Joulethief +You will build a deliberately simple “MySpace-style” page: + +- "Hi, I'm …" +- one gif +- one link +- optional: background, glitter, bad taste encouraged + +Workflow loop: + +clone -> branch -> edit -> status -> add -> commit -> push -> view -> iterate + +---- + +Exercise: step 1 (clone) ======================== -.. image:: ./assets/images/joulethief_simple.jpeg +.. code-block:: bash + + git clone + cd + +Sanity check: + +.. code-block:: bash + + git status + git branch ---- -Transistor -========== +Exercise: step 2 (create your branch) +===================================== -.. image:: ./assets/images/transistor.png - :width: 300 -.. image:: ./assets/images/analogi-transistor-87050130.gif - :width: 500 +Choose a slug: lowercase, no spaces. Example: `people/alex`. -Water analogy: the little bit of water from B to E opens the gate for the bigger flow from C to E +.. code-block:: bash + + git checkout -b people/ + +Confirm: + +.. code-block:: bash + + git status ---- -Joulethief -======================== +Exercise: step 3 (edit the page) +================================ -.. image:: ./assets/images/joulethief.jpeg +Edit the root `index.html` (and optionally `style.css`, `assets/`). + +Make a visible change first: + +- your name +- one gif +- one link + +Then check changes: + +.. code-block:: bash + + git diff + git status ---- -:id: joulethief-step1 +Exercise: step 4 (stage + commit) +================================= -Joulethief -======================== +.. code-block:: bash -.. image:: ./assets/images/joulethief_1.png - -A small current flows from the battery through the coil and the base-emitter path of the transistor. This opens the emittor-collector path of the transistor. + git add index.html + git commit -m "Customize profile page for " + +If you added assets: + +.. code-block:: bash + + git add assets/ + git commit -m "Add assets for " + +.. note:: + + Small commits win. One change = one deposit. ---- -Joulethief -======================== +Exercise: step 5 (push your branch) +=================================== -.. image:: ./assets/images/joulethief_2.png - -Electricity is now able to travel through the second coil and through the collector-emitter channel of the transistor. +.. code-block:: bash + + git push -u origin people/ + +If prompted for credentials, use your Forgejo login method. ---- -Joulethief -======================== +Exercise: step 6 (view live) +============================ -.. image:: ./assets/images/joulethief_3.png - -The increasing amount of electricity through the second coil generates a negative voltage in the first coil, which cause the transistor to close. +Open the gallery: + +- `https://braids./` + +Find your card: + +- `people//` + +Iterate: + +edit -> status -> add -> commit -> push -> refresh ---- -Joulethief -======================== +Common problems (fast fixes) +============================ -.. image:: ./assets/images/joulethief_4.png +Wrong branch: -With the transistor closed the energy starts to flow through the output (led). +.. code-block:: bash + + git branch + git checkout people/ + +Nothing staged: + +.. code-block:: bash + + git status + git add index.html + +Push rejected (main protected): + +- You are on `main`. Switch to your branch. + +Auth issues: + +- HTTPS: check username/token/password +- SSH: check key added to Forgejo + `ssh -T` ---- -Joulethief -======================== +Concept recap in archiving terms +================================ -.. image:: ./assets/images/joulethief_5.png - -The inductor is now powered by the magnetic field of the coil. +- commit = deposit (with minimal metadata) +- log = inventory / chain of custody +- diff = conservation report (what changed) +- branch = parallel dossier +- push = deposit to institutional archive (remote) ---- -Joulethief -======================== +Suggested “good enough” commit messages +======================================= -.. image:: ./assets/images/joulethief_6.png +Bad: -When the magnetic field is gone, the whole process `starts over <#joulethief-step1>`_. +- "update" +- "stuff" +- "changes" + +Better: + +- "Add animated gif and profile link" +- "Change background and typography" +- "Fix broken image path" +- "Refactor layout: move link block above gif" + +Rule: message should still make sense in 6 months. ---- -Joulethief -======================== -A more detailed explanation can be found on `instructables `_ +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 ---- -Led -======================== +Wrap-up +======= -.. image:: ./assets/images/led_polarity.png +You should now be able to: -Make sure to get the LED polarity right. Short leg goes to ground! +- create a branch safely +- record changes as commits +- publish to a remote +- read history and differences ----- +Next steps: -Circuit -======================== +- merging via PRs (review workflow) +- tags/releases (archival milestones) +- basic collaboration patterns (feature branches) -.. image:: ./assets/images/circuit.png +.. note:: -https://github.com/hackersanddesigners/Soilpunk_joulethief + End: remind participants their branches will be removed after the workshop. \ No newline at end of file