worst commit ever im sorry it's too soon to be so detailed

html_output/slides.css

@@ -33,10 +33,26 @@ a {
 img {
   max-width: 100%;
 }
-
+.step tt {
+  font-size: smaller;
+  background-color: lightblue;
+  border-radius: 5px;
+  padding: 2px;
+}
 .step strong {
-  color: teal;
+  /* color: ; */
-  font-weight: normal;
+  /* font-weight: normal; */
+}
+
+.step:has(img) {
+  width: 1000px;
+}
+
+.step pre {
+  background-color: lightblue;
+  font-size: smaller;
+  padding: 5px 10px;
+  border-radius: 5px;
 }
 
 .header p,
@@ -75,6 +91,12 @@ h1, h2, h3, h4 {
   columns: 3;
 }
 
+.row {
+  display: flex;
+  gap: 1rem;
+  justify-content: space-around;
+}
+
 .no-list ul {
   margin: 0;
   list-style: none;
@@ -90,6 +112,8 @@ div#the-slide-id img{
   height: 100%;
 }
 
+
+
 /* for drawing machines */
 
 .code-slide h1 {
@@ -100,9 +124,3 @@ div#the-slide-id img{
   left: 0;
 }
 
-.bash {
-  background-color: #eee;
-  /* color: white; */
-  padding: 1rem;
-  border-radius: 1rem;
-}

slides.css

@@ -33,10 +33,26 @@ a {
 img {
   max-width: 100%;
 }
-
+.step tt {
+  font-size: smaller;
+  background-color: lightblue;
+  border-radius: 5px;
+  padding: 2px;
+}
 .step strong {
-  color: teal;
+  /* color: ; */
-  font-weight: normal;
+  /* font-weight: normal; */
+}
+
+.step:has(img) {
+  width: 1000px;
+}
+
+.step pre {
+  background-color: lightblue;
+  font-size: smaller;
+  padding: 5px 10px;
+  border-radius: 5px;
 }
 
 .header p,
@@ -75,6 +91,12 @@ h1, h2, h3, h4 {
   columns: 3;
 }
 
+.row {
+  display: flex;
+  gap: 1rem;
+  justify-content: space-around;
+}
+
 .no-list ul {
   margin: 0;
   list-style: none;
@@ -90,6 +112,8 @@ div#the-slide-id img{
   height: 100%;
 }
 
+
+
 /* for drawing machines */
 
 .code-slide h1 {

slides.rst

@@ -1,15 +1,15 @@
-:title: Braids - Intro to Git
+:title: Braids - Intro to git
 :author: H&D
 :description: 
 :css: slides.css
 
 .. header::
 
-  Braids - Intro to Git
+  Braids - Intro to git with H&D
 
 ----
 
-Braids - Intro to Git
+Braids - Intro to git
 =====================
 
 .. note::
@@ -22,71 +22,269 @@ Braids - Intro to Git
 Planning (90 min)
 =================
 
-1. Context: what Git is, what it does, who uses it (10 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
+If you have been working on a file on your computer and the directory starts to look like this:
-===========
+
+.. code-block:: bash
+
+   motivation-letter-first-draft.odt
+   motivation-letter.odt
+   motivation-letter-less-formal.odt
+   motivation-letter-less-formal-comments-HvK.odt
+   motivation-letter-less-formal-comments-HvK-LS.odt
+   motivation-letter-FINAL.odt
+   motivation-letter-FINAL-pictures.odt
+   motivation-letter-FINAL-pictures-small.odt
+
+
+Then git can be helpful!
+
+----
+
+What is git?
+============
+
+- git is a distributed version control system
+- git tracks changes over time to files inside a folder
+- git enables:
 
-- Distributed version control system
-- Tracks changes over time
-- Enables:
   - history (time)
   - collaboration (many authors)
   - experimentation (branches)
   - traceability (who/what/when/why)
 
-Archiving analogy:
 
+.. note::
+
+   is the archive analogy helpful? it feels a bit like comapring something abstract with something else thats abstract
+
+   Archiving analogy: 
    - commit = deposit with metadata
    - log = inventory / finding aid
    - branch = parallel dossier / alternative interpretation
 
 ----
 
-What Git is not
+What is git not?
-===============
+================
 
-- Git ≠ Github!
+- git ≠ Github!
 - Not a backup system (though it can help)
-- Not a file sync tool
+- Not a file sync tool (though it can be used like that)
-- Not a CMS
+- Not a CMS (though it can be used like that)
 - Not magic: it stores snapshots + metadata, you still choose what to record
 
+
+----
+
+Core concept: Commits
+=====================
+
+.. container:: row
+
+   .. container::
+
+      In git, a **commit** is a checkpoint in the repository timeline.
+      A commit contains this information:
+
+      1. **What** changes have taken place?
+      2. **Who** made these changes?
+      3. **When** were the changes made?
+      4. **Why** were the changes made?
+      5. **Where** was the last checkpoint?
+
+      Every time an author makes a set of changes that are meaningful together, she commits her changes by describing them, creating a checkpoint in the timeline to return to in the future.
+
+      The changes possible in a commit are:
+       - editing a file
+       - adding a file
+       - removing a file
+       - renaming (moving) a file
+
+      Commits do not know about the timeline they are in. They only know of their preceeding commit, otherwise known as their "parent".
+
+      You can always **checkout** a commit: visit the repository at that checkpoint on its timeline. Basically time-travel.
+
+   .. image:: assets/images/commits.png
+      :width: 400px
+      :scale: 100 %
+
+
+----
+
+Core concept: Three Areas
+=========================
+
+1. **Working tree**: your files right now
+2. **Staging area**: selection for the next deposit
+3. **Repository history**: overview of commits
+
+.. container:: row
+
+   .. image:: assets/images/working-tree.png
+      :width: 400px
+      :scale: 100 %
+   .. image:: assets/images/staging.png
+      :width: 400px
+      :scale: 100 %
+   .. image:: assets/images/timeline.png
+      :width: 400px
+      :scale: 100 %
+
+
+.. note::
+   This is why Git feels "archival":
+   - you intentionally select what becomes part of the record.
+
+----
+
+Core concept: Branching
+=======================
+
+.. container:: row
+
+   .. container::
+
+      In git, a **branch** is a named series of commits. In the previous example, there is only one branch, named "main" by default.
+
+      In a situation where you want to "take a detour" from the main course of the development of a repository, you can create a separate branch. Now, parrallel timelines of the same repository exist next to each other. 
+
+      Example use cases of branching:
+       - if you want to experiemnt with a new feature affecting many files
+       - if you want to propose an improvement to your collaborators without editing their work "main"
+       - If you want to make existing software compatible on another platform
+
+      There is a lot of discourse around when to branch and how often. It varies from person to person and group to group. 
+      
+      .. note::
+         From the perspective of git, since branching doesn't add any technical overload on a project, it is encouraged to branch more and branch often. From a logical perspective, every branch creates a parrallel timeline, and this might be a lot to keep track of mentally.
+
+      Branching allows for and encourages collaboration and is at the core of the free and open source software movement. 
+
+
+   .. image:: assets/images/branching.png
+      :width: 400px
+      :scale: 100 %
+
+
+
+----
+
+Core concept: Merging
+=====================
+
+.. container:: row
+
+   .. container::
+
+      In git, **merging** is when you incorporate commits from a separate branch into your own.
+
+      There are various merging techniques, and most of the time, the automated algorithm will work. Sometimes however, you might encounter a **merge confilct**: a section of a file where both branches have conflicting data that cannot be automatically resolved. In this case, you are prompted to manually resolve the conflicts, which can take the form of:
+       - accepting a change from one branch and rejecting the other
+       - accepting and keeping both changes
+       - re-editing the files to incorporate both changes
+
+      After merging two branches, a **merge commit** is created. This is an exceptional commit that has two parent commits instead of one.
+
+   .. image:: assets/images/branches.png
+      :width: 300px
+      :scale: 100 %
+
+----
+
+Terminology Overview
+====================
+
+- **repository**: a directory initialised with git
+- **commit**: a checkpoint in the repository timeline(s)
+- **checkout**: to visit the repository at a specific commit in its history.
+- **delta**: a set of changes of a single commit
+- **working tree**: your files as they are right now in the repository
+- **staging area**: a place to add changes to 
+- **branch**: a named series of commits, a detour, a prrallel timeline
+- **merge**: an incorporation of commits from another branch
+- **remote**: a copy of the repository on a different host
+- **clone**: to download an identical copy of a repository
+- **push**: to upload local commits to a remote repository
+- **pull**: to re-download commits from the remote repository
+
 ----
 
 Ecosystem
 =========
 
-- Git = the tool + file format
+- **git**: the version control system itself
-- Hosting platforms:
+- **.git**: a hidden subfolder where git operates
-  - GitHub, Bitbucket, GitLab
+- **git hosts**: platforms where git repositories are hosted
-  - Alternatives: 
+
+  - GitHub, Bitbucket, GitLab (operated by Big Tech Giants)
+  - 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
+- **git clients**: tools used to work with git on your computer
+
+  - ``git`` command line tool (free & open source)
+  - ``tig`` command line tool (free & open source)
+  - sourcetree, Github Desktop, VS Code (operated by Big Tech) 
+  - many code editors (e.g. sublime, atom) have git extensions  
+  - many, many more tools and extensions
+
 
 ----
 
-Typical workflow
-================
 
-- remote (server copy)
+Typical solo local workflow
-- clone (get a copy)
+===========================
-- push (send your commits back to the server)
+
-- pull/fetch (receive updates)
+1. You initalise a directory on your computer with git.
+2. You make changes on the directory.
+3. You stage your changes and commit them.
+4. Repeat steps **2** and **3**.
+
+Use case: tracking changes on a local, private folder, such as bookkeeping.
 
 ----
 
-..
+Typical solo remote workflow
+============================
+ 
+1. You clone a repository from a remote host to your local computer.
+2. You make your changes to the repository.
+3. You stage and commit your changes.
+4. You push (upload) your commit up to the remote.
+5. Repeat steps **2**, **3** and **4**
+
+Use case: tracking and backing up a private folder, such as a password store.
+
+----
+
+Typical collaborative remote workflow
+=====================================
+
+1. You clone a repository from a remote host to your local computer.
+2. You make your changes to the repository.
+3. You stage and commit your changes.
+4. You push (upload) your commit up to the remote.
+5. You pull (re-download) other people's commits from the remote.
+6. Repeat steps **5**, **2**, **3** and **4**
+
+Use case: tracking and collaborating on a repository with others such as a website project.
+
+----
+
+
 Workshop outcome
 ================
 
@@ -118,18 +316,8 @@ If missing:
 
 Minimum requirement: you can run `git` in a terminal.
 
-----
 
-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.
 
 ----
 
@@ -140,12 +328,11 @@ Commands: the essential set
 - `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 checkout` (visit the timeline at a specific checkpoint)
+- `git branch` (take a detour)
+- `git merge` (merge branches)
 - `git diff` (what changed)
 - `git log` (history)