hrk/Braid-slides
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: hrk:e75282a915c572df288666bfc41f5df362bc2079
Branches Tags
hrk:master
..
compare: hrk:c3635224a625d2bbaafd00cbdc8d8d50e5d42f36
Branches Tags
hrk:master

4 commits
e75282a915 ... c3635224a6

Author SHA1 Message Date
كارل مبارك c3635224a6 edits to slide contents 2026-01-14 13:38:41 +01:00
كارل مبارك a678ff5b6d reorganized order again, all theory firstg 2026-01-14 12:47:07 +01:00
كارل مبارك 85abfb10dc changed orde rto do brnaching/merging in secodn part 2026-01-14 11:39:07 +01:00
كارل مبارك a573ea27f4 added complex collaborative workflow with branching 2026-01-14 11:09:40 +01:00
3 changed files with 408 additions and 281 deletions
Show stats Expand all files Collapse all files

37
html_output/2026-01-14_km.html Normal file
View file

@ -0,0 +1,37 @@
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><title>Braids - Intro to git</title><meta charset="UTF-8"></meta><meta name="generator" content="Hovercraft! 1.0 http://regebro.github.com/hovercraft"></meta><meta name="author" content="H&amp;D"></meta><link rel="stylesheet" href="css/hovercraft.css" media="all"></link><link rel="stylesheet" href="css/highlight.css" media="all"></link><link rel="stylesheet" href="slides.css" media="screen,projection"></link><script type="text/x-mathjax-config">
MathJax.Hub.Config({
showProcessingMessages: false,
messageStyle: "none",
TeX : { extensions : ['color.js'] }
});
</script></head><body class="impress-not-supported"><div id="impress-help"></div><div class="header"><p>Braids - Intro to git with H&amp;D</p></div><div id="impress"><div class="step step-level-1" step="0" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="0" data-y="0" data-z="0"><h1 id="braids-intro-to-git">Braids - Intro to git</h1><div class="notes"><p>Goal: introduce Git as an archiving practice,
then do a little branch-based website exercise published live.</p></div></div><div class="step step-level-1" step="1" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="1600" data-y="0" data-z="0"><h1 id="planning-90-min">Planning (90 min)</h1><ol><li>Context: what git is, what it does, who uses it (5 min)</li><li>Core concepts (20 min)</li><li>Recap (5 min)</li><li>Install Git (10 min)</li><li>Core commands (15 min)</li><li>Exercise: accounts + clone/push permissions (10 min)</li><li>Exercise: branch a page, publish live, iterate (20 min)</li><li>Wrap-up: good practices + next steps (5 min)</li></ol></div><div class="step step-level-1" step="2" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="3200" data-y="0" data-z="0"><h1 id="workshop-outcome">Workshop outcome</h1><blockquote><p>Each participant will:</p><ul><li>have basic knowledge of git</li><li>clone a repository</li><li>create a branch</li><li>commit changes</li><li>push branch to our platform</li></ul></blockquote></div><div class="step step-level-1" step="3" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="4800" data-y="0" data-z="0"><h1 id="why-git">Why git?</h1><p>If you have been working on a file on your computer and the directory starts to look like this:</p><pre class="highlight code bash">motivation-letter-first-draft.odt<span class="w">
</span>motivation-letter.odt<span class="w">
</span>motivation-letter-less-formal.odt<span class="w">
</span>motivation-letter-less-formal-comments-HvK.odt<span class="w">
</span>motivation-letter-less-formal-comments-HvK-LS.odt<span class="w">
</span>motivation-letter-FINAL.odt<span class="w">
</span>motivation-letter-FINAL-pictures.odt<span class="w">
</span>motivation-letter-FINAL-pictures-small.odt</pre><p>Then git can be helpful!</p><blockquote><div class="notes"><p>this file has different chronological versions, features and collaborators, 3 things git is great at.</p></div></blockquote></div><div class="step step-level-1" step="4" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="6400" data-y="0" data-z="0"><h1 id="what-is-git">What is git?</h1><ul><li>git is a distributed version control system</li><li>git tracks changes over time to files inside a folder</li><li>git operates in a hidden sub-folder inside the tracked folder</li><li>git enables:<ul><li>history (time)</li><li>collaboration (many authors)</li><li>experimentation (branches)</li><li>traceability (who/what/when/why)</li></ul></li></ul><div class="notes"><p>is the archive analogy helpful? it feels a bit like comapring something abstract with something else thats abstract</p><p>Archiving analogy:
- commit = deposit with metadata
- log = inventory / finding aid
- branch = parallel dossier / alternative interpretation</p></div></div><div class="step step-level-1" step="5" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="8000" data-y="0" data-z="0"><h1 id="what-is-git-not">What is git not?</h1><ul><li>git &#x2260; Github!</li><li>git &#x2260; backup system (though it can help)</li><li>git &#x2260; file sync tool (though it can be used like that)</li><li>git &#x2260; CMS (though it can be used like that)</li><li>git &#x2260; magic: it stores snapshots + metadata, you still choose what to record</li></ul></div><div class="step step-level-1" step="6" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="9600" data-y="0" data-z="0"><h1 id="ecosystem">Ecosystem</h1><ul><li><strong>git</strong>: the version control system itself</li><li><strong>git hosts</strong>: platforms where git repositories are hosted<ul><li>GitHub, Bitbucket, GitLab (operated by Big Tech Giants)</li><li>Alternatives<ul><li>Codeberg (non-profit, community led)</li><li>Oxacab (riseup.net for activists, journalists)</li><li>Forgejo / Gitea (self-hosted)</li></ul></li></ul></li><li><strong>git clients</strong>: tools used to work with git on your computer<ul><li><tt>git</tt> command line tool (free &amp; open source)</li><li><tt>tig</tt> command line tool (free &amp; open source)</li><li>sourcetree, Github Desktop, VS Code (operated by Big Tech)</li><li>many code editors (e.g. sublime, atom) have git extensions</li><li>many, many more tools and extensions</li></ul></li></ul></div><div class="step step-level-1" step="7" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="11200" data-y="0" data-z="0"><h1 id="core-concept-commits">Core concept: Commits</h1><div class="row"><div><p>In git, a <strong>commit</strong> is a checkpoint in the repository timeline.
A commit contains this information:</p><ol><li><strong>What</strong> changes have taken place?</li><li><strong>Who</strong> made these changes?</li><li><strong>When</strong> were the changes made?</li><li><strong>Why</strong> were the changes made?</li><li><strong>Where</strong> was the last checkpoint?</li></ol><div class="notes"><p>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.</p><p>The changes possible in a commit are:
- editing a file
- adding a file
- removing a file
- renaming (moving) a file</p></div><p>Commits do not know about the timeline they are in. They only know of their preceeding commit, otherwise known as their <strong>parent</strong>.</p><p>You can always <strong>checkout</strong> a commit: visit the repository at that checkpoint on its timeline. Basically time-travel.</p></div><img src="assets/images/commits.png" width="400px"></img></div></div><div class="step step-level-1" step="8" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="12800" data-y="0" data-z="0"><h1 id="core-concept-working-areas">Core concept: Working Areas</h1><ol><li><strong>Working tree</strong>: your files right now</li><li><strong>Staging area</strong>: selection for the next commit</li><li><strong>Repository history</strong>: overview of commits</li></ol><div class="row"><img src="assets/images/working-tree.png" width="400px"></img><img src="assets/images/staging.png" width="400px"></img><img src="assets/images/timeline.png" width="400px"></img></div><div class="notes"><p>This is why Git feels "archival":
- you intentionally select what becomes part of the record.</p></div></div><div class="step step-level-1" step="9" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="14400" data-y="0" data-z="0"><h1 id="typical-solo-local-workflow">Typical solo local workflow</h1><ol><li>You initalise a directory on your computer with git.</li><li>You make changes on the directory.</li><li>You stage your changes and commit them.</li><li>Repeat steps <strong>2</strong> and <strong>3</strong>.</li></ol><p><strong>Use case</strong>: tracking changes on a local, private folder, such as bookkeeping.</p></div><div class="step step-level-1" step="10" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="16000" data-y="0" data-z="0"><h1 id="typical-solo-remote-workflow">Typical solo remote workflow</h1><ol><li>You clone a repository from a remote host to your local computer.</li><li>You make your changes to the repository.</li><li>You stage and commit your changes.</li><li><strong>You push (upload) your commit up to the remote</strong>.</li><li>Repeat steps <strong>2</strong>, <strong>3</strong> and <strong>4</strong></li></ol><p><strong>Use case</strong>: tracking and backing up a private folder, such as a password store.</p></div><div class="step step-level-1" step="11" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="17600" data-y="0" data-z="0"><h1 id="typical-collaborative-remote-workflow">Typical collaborative remote workflow</h1><ol><li>You clone a repository from a remote host to your local computer.</li><li>You make your changes to the repository.</li><li>You stage and commit your changes.</li><li>You push (upload) your commit up to the remote.</li><li><strong>You pull (download) other people's commits from the remote</strong>.</li><li>Repeat steps <strong>5</strong>, <strong>2</strong>, <strong>3</strong> and <strong>4</strong></li></ol><p><strong>Use case</strong>: tracking and collaborating on a repository with others such as a website project.</p></div><div class="step step-level-1" step="12" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="19200" data-y="0" data-z="0"><h1 id="core-concept-branching">Core concept: Branching</h1><div class="row"><div><p>In git, a <strong>branch</strong> is a named series of commits.</p><div class="notes"><p>In the previous example, there is only one branch, named "main" by default.</p></div><p>When you want to "take a detour" from the main course of a repository, you can create a separate branch.</p><div class="notes"><p>Now, parrallel timelines of the same repository exist next to each other.</p></div><p>Example <strong>use cases</strong> of branching:</p><ul><li>Experiment with a new feature affecting many files</li><li>Proposing an improvement to your collaborators</li><li>Have multiple versions of a website online</li><li>Making existing software compatible somewhere else</li></ul><div class="notes"><p>There is a lot of discourse around when to branch and how often. It varies from person to person and group to group.</p><p>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.</p><p>Branching allows for and encourages collaboration and is at the core of the free and open source software movement.</p></div></div><img src="assets/images/branching.png" width="400px"></img></div></div><div class="step step-level-1" step="13" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="20800" data-y="0" data-z="0"><h1 id="core-concept-merging">Core concept: Merging</h1><div class="row"><div><p>In git, <strong>merging</strong> is when you consolidate commits from a separate branch into your own.</p><div class="notes"><p>There are various merging techniques, and most of the time, the automated algorithm will work.</p></div><p>Sometimes, you might encounter a <strong>merge confilct</strong>: a section of a file where both branches have conflicting changes that cannot be automatically resolved. Here, you have to manually resolve the conflicts.</p><div class="notes"><p>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</p></div><p>After merging two branches, a <strong>merge commit</strong> is created. This is an exceptional commit that has two parent commits instead of one.</p></div><img src="assets/images/branches.png" width="200px"></img></div></div><div class="step step-level-1" step="14" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="22400" data-y="0" data-z="0"><h1 id="complex-collaborative-remote-workflow">Complex collaborative remote workflow</h1><ol><li>You clone a repository from a remote host to your local computer.</li><li><strong>You create a new branch "my-feature" for your changes</strong>.</li><li>You make your changes to the repository.</li><li>You stage and commit your changes.</li><li>You push your commit (and new branch) up to the remote.</li><li>You pull other people's commits on this branch from the remote.</li><li>Repeat steps <strong>6</strong>, <strong>3</strong>, <strong>4</strong> and <strong>5</strong></li><li><strong>You switch back to "main" and merge "my-feature" into it</strong>.</li><li><strong>You push your new merge commit up to the "main" branch</strong>.</li></ol><p><strong>Use case</strong>: you are designing a website for a client and want to show 3 different versions of it with different background colours.</p><p><strong>Use case</strong>: tracking and collaborating on a repository with others such as a website project, where two online versions of the website exist, a "safe" one that is available to the public, and an "experimental" one that is reserved for trying new features together.</p></div><div class="step step-level-1" step="15" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="24000" data-y="0" data-z="0"><h1 id="recap">Recap</h1><ul><li><strong>repository</strong>: a directory initialised with git</li><li><strong>commit</strong>: a checkpoint in the repository timeline(s)</li><li><strong>checkout</strong>: to visit the repository at a specific commit in its history.</li><li><strong>working tree</strong>: your files as they are right now in the repository</li><li><strong>staging area</strong>: a place to add changes to</li><li><strong>remote</strong>: a copy of the repository on a different host</li><li><strong>clone</strong>: to download an identical copy of a repository</li><li><strong>push</strong>: to upload local commits to a remote repository</li><li><strong>pull</strong>: to re-download commits from the remote repository</li><li><strong>branch</strong>: a named series of commits, a detour, a parallel timeline</li><li><strong>merge</strong>: a consolidation of commits from another branch</li></ul></div><div class="step step-level-1" step="16" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="25600" data-y="0" data-z="0"><h1 id="install-git">Install Git</h1><p>Check first:</p><pre class="highlight code bash">git<span class="w"> </span>--version</pre><p>If missing:</p><ul><li>macOS: Xcode Command Line Tools</li><li>Windows: Git for Windows</li><li>Linux: package manager (apt/dnf/pacman)</li></ul><p>Minimum requirement: you can run git in a terminal.</p></div><div class="step step-level-1" step="17" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="27200" data-y="0" data-z="0"><h1 id="commands-the-essentials">Commands: the essentials</h1><ul><li><tt>git init</tt> (initalise a repo)</li><li><tt>git status</tt> (what's happening?)</li><li><tt>git add</tt> (add changes to the commit)</li><li><tt>git rm</tt> (remove a tracked file)</li><li><tt>git commit</tt> (store changes in the repo)</li><li><tt>git log</tt> (see the timeline)</li><li><tt>git checkout</tt> (visit the timeline at a specific checkpoint)</li><li><tt>git clone</tt> (an existing repo)</li><li><tt>git push</tt> (your commits to a remote server)</li><li><tt>git pull</tt> (sync with a repo online and merge)</li><li><tt>git branch</tt> (take a detour)</li><li><tt>git merge</tt> (merge branches)</li></ul></div><div class="step step-level-1" step="18" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="28800" data-y="0" data-z="0"><h1 id="command-git-init">Command: git init</h1><p>Create a repository in the current folder.
Use this when you are creating and working on your own projects.</p><pre class="highlight code bash">git<span class="w"> </span>init</pre><p>Creates a .git/ directory containing history + metadata.</p><div class="notes"><p>For the exercise we will use git clone instead of git init.</p></div></div><div class="step step-level-1" step="19" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="30400" data-y="0" data-z="0"><h1 id="command-git-status-your-dashboard">Command: git status (your dashboard)</h1><pre class="highlight code bash">git<span class="w"> </span>status</pre><p>Shows:</p><ul><li>current branch</li><li>staged vs unstaged changes</li><li>untracked files</li></ul></div><div class="step step-level-1" step="20" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="32000" data-y="0" data-z="0"><h1 id="command-git-add-select-files">Command: git add (select files)</h1><p>First, create a file</p><pre class="highlight code bash">nano<span class="w"> </span>index.html</pre><p>Stage files for the next commit.</p><pre class="highlight code bash">git<span class="w"> </span>add<span class="w"> </span>index.html</pre><p>Stage everything (use carefully):</p><pre class="highlight code bash">git<span class="w"> </span>add<span class="w"> </span>.</pre><div class="notes"><p>Staging is curatorial: select what belongs together.</p></div></div><div class="step step-level-1" step="21" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="33600" data-y="0" data-z="0"><h1 id="optional-git-rm">Optional: git rm</h1><p>Remove a tracked file and stage the removal:</p><pre class="highlight code bash">git<span class="w"> </span>rm<span class="w"> </span>old.html<span class="w">
</span>git<span class="w"> </span>commit<span class="w"> </span>-m<span class="w"> </span><span class="s2">"Remove old page"</span></pre><p>For this workshop you probably will not need it.</p></div><div class="step step-level-1" step="22" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="35200" data-y="0" data-z="0"><h1 id="command-git-commit-checkpoint">Command: git commit (checkpoint)</h1><pre class="highlight code bash">git<span class="w"> </span>commit<span class="w"> </span>-m<span class="w"> </span><span class="s2">"Added name to my page"</span></pre><p>Good commit message pattern:</p><ul><li>What changed</li><li>Why it changed (reason/intent)</li><li>Scope stays small</li></ul><div class="notes"><p>repeat edit &gt; stage &gt; commit a couple times?</p></div></div><div class="step step-level-1" step="23" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="36800" data-y="0" data-z="0"><h1 id="command-git-log-timeline">Command: git log (timeline)</h1><pre class="highlight code bash">git<span class="w"> </span>log<span class="w"> </span>--oneline<span class="w"> </span>--graph</pre><p>Gives a quick "finding aid" of earlier commits. Press 'q' to exit.</p></div><div class="step step-level-1" step="24" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="38400" data-y="0" data-z="0"><h1 id="command-git-checkout-timetravel">Command: git checkout (timetravel)</h1><pre class="highlight code bash">git<span class="w"> </span>checkout<span class="w"> </span>your_commit_id</pre><p>See your working tree as it would have been at a specific commit on the timeline.</p></div><div class="step step-level-1" step="25" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="40000" data-y="0" data-z="0"><h1 id="command-git-clone">Command: git clone</h1><p>Cloen (copy) a repository in the current folder. First, cd to a logical location in your computer, then:</p><pre class="highlight code bash">git<span class="w"> </span>clone<span class="w"> </span>https://git.hackersanddesigners.nl/hrk/braids<span class="w">
</span><span class="nb">cd</span><span class="w"> </span>braids</pre><p>Downloads a repo from the web, complete with the full commit history and all changes.</p><p>Make edits here as you wish then stage and commit them.</p></div><div class="step step-level-1" step="26" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="41600" data-y="0" data-z="0"><h1 id="command-git-push">Command: git push</h1><p>Push your commits to the server:</p><pre class="highlight code bash">git<span class="w"> </span>push<span class="w"> </span>-u<span class="w"> </span>origin<span class="w"> </span>main</pre><pre class="highlight code bash">git<span class="w"> </span>push</pre><div class="notes"><p>disabled push rights for now, only for demonstration purposes, will fail</p></div></div><div class="step step-level-1" step="27" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="43200" data-y="0" data-z="0"><h1 id="command-git-pull">Command: git pull</h1><div class="notes"><p>before we do this, one of us changes the background colour and pushes</p></div><p>Pull updates from server:</p><pre class="highlight code bash">git<span class="w"> </span>pull</pre><div class="notes"><p>During the exercise you mostly push your branch.
Pull is mainly for getting new changes on main (if needed).</p><p>fact: git pull is actually a git fetch &amp;&amp; git merge</p></div></div><div class="step step-level-1" step="28" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="44800" data-y="0" data-z="0"><h1 id="command-git-branch">Command: git branch</h1><p>Choose a slug: lowercase, no spaces. This can be your name or an alias. Example: change people/&lt;your-slug&gt; in the command below to people/alex. From here on out replace &lt;your-slug&gt; with your chosen name.</p><p>List branches:</p><pre class="highlight code bash">git<span class="w"> </span>branch</pre><p>Create a branch:</p><pre class="highlight code bash">git<span class="w"> </span>branch<span class="w"> </span>people/&lt;your-slug&gt;</pre><p>Switch to branch:</p><pre class="highlight code bash">git<span class="w"> </span>checkout<span class="w"> </span>people/&lt;your-slug&gt;</pre><p>Shortcut (create + switch):</p><pre class="highlight code bash">git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>people/&lt;your-slug&gt;</pre><div class="notes"><p>Branches are parallel dossiers: safe space for changes.</p></div></div><div class="step step-level-1" step="29" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="46400" data-y="0" data-z="0"><h1 id="command-git-merge">Command: git merge</h1><p>?</p></div><div class="step step-level-1" step="30" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="48000" data-y="0" data-z="0"><h1 id="forgejo-what-we-use-today">Forgejo: what we use today</h1><ul><li>Forgejo is an open-source alternative to Github</li><li>Forgejo hosts the central repository (remote)</li></ul><p>You will:</p><ul><li>create an account</li><li>clone via HTTPS</li><li>push your branch</li></ul><p>Share your username with us so we can add you as a collaborator</p><p>Rules for today:</p><ul><li>do NOT push to main</li><li>create your branch under people/&lt;your-slug&gt;</li></ul></div><div class="step step-level-1" step="31" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="49600" data-y="0" data-z="0"><h1 id="forgejo-account-setup">Forgejo: account setup</h1><ol><li>Create account at: git.hackersanddesigners.nl</li><li>Confirm you can sign in</li></ol><p>Resources:</p><ul><li><a href="https://git.hackersanddesigners.nl/hrk/braids">https://git.hackersanddesigners.nl/hrk/braids</a> - the repo we will be working in</li><li>live gallery URL: <a href="https://braids.hackersanddesigners.nl">https://braids.hackersanddesigners.nl</a></li><li>these slides: <a href="https://braids.hackersanddesigners.nl/slides">https://braids.hackersanddesigners.nl/slides</a></li></ul></div><div class="step step-level-1" step="32" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="51200" data-y="0" data-z="0"><h1 id="exercise-overview">Exercise overview</h1><p>You will build a (deliberately) simple page:</p><ul><li>"Hi, I'm &#x2026;"</li><li>maybe a gif?</li><li>a link?</li><li>optional: background, glitter, bad taste encouraged</li></ul><p>Workflow loop:</p><p>clone -&gt; branch -&gt; edit -&gt; status -&gt; add -&gt; commit -&gt; push -&gt; view -&gt; iterate</p></div><div class="step step-level-1" step="33" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="52800" data-y="0" data-z="0"><h1 id="exercise-step-1-clone-branch">Exercise: step 1 (clone &amp; branch)</h1><p>If everything went well in your initial clone &amp; branch, check the repo with:</p><pre class="highlight code bash">git<span class="w"> </span>status<span class="w">
</span>git<span class="w"> </span>branch</pre><p>The first time you checkout from <a href="https://git.hackersanddesigners.nl">https://git.hackersanddesigners.nl</a> the server will ask you for credentials. These will be remembered, so only once.</p></div><div class="step step-level-1" step="34" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="54400" data-y="0" data-z="0"><h1 id="exercise-step-2-edit-the-page">Exercise: step 2 (edit the page)</h1><p>Edit the root index.html (and optionally style.css, assets/).</p><p>Make a visible change first:</p><ul><li>Change the name to your name (or your alias)</li></ul><p>Then check changes:</p><pre class="highlight code bash">git<span class="w"> </span>diff<span class="w">
</span>git<span class="w"> </span>status</pre></div><div class="step step-level-1" step="35" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="56000" data-y="0" data-z="0"><h1 id="exercise-step-3-stage-commit">Exercise: step 3 (stage + commit)</h1><pre class="highlight code bash">git<span class="w"> </span>add<span class="w"> </span>index.html<span class="w">
</span>git<span class="w"> </span>commit<span class="w"> </span>-m<span class="w"> </span><span class="s2">"Customize profile page for &lt;your-slug&gt;"</span></pre><p>If you added assets:</p><pre class="highlight code bash">git<span class="w"> </span>add<span class="w"> </span>assets/<span class="w">
</span>git<span class="w"> </span>commit<span class="w"> </span>-m<span class="w"> </span><span class="s2">"Add assets for &lt;your-slug&gt;"</span></pre><div class="notes"><p>Small commits win. One change = one deposit.</p></div></div><div class="step step-level-1" step="36" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="57600" data-y="0" data-z="0"><h1 id="exercise-step-4-push-your-branch">Exercise: step 4 (push your branch)</h1><pre class="highlight code bash">git<span class="w"> </span>push<span class="w"> </span>-u<span class="w"> </span>origin<span class="w"> </span>people/&lt;your-slug&gt;</pre><p>(Again, change &lt;your-slug&gt;!)</p><p>If prompted for credentials, use your Forgejo login method.</p></div><div class="step step-level-1" step="37" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="59200" data-y="0" data-z="0"><h1 id="exercise-step-5-view-live">Exercise: step 5 (view live)</h1><p>Open the gallery:</p><ul><li>https://braids.hackersanddesigners.nl/</li></ul><p>Find your card:</p><ul><li>people/&lt;your-slug&gt;/</li></ul><p>Iterate:</p><p>edit -&gt; status -&gt; add -&gt; commit -&gt; push -&gt; refresh</p></div><div class="step step-level-1" step="38" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="60800" data-y="0" data-z="0"><h1 id="common-problems-fast-fixes">Common problems (fast fixes)</h1><p>Wrong branch:</p><pre class="highlight code bash">git<span class="w"> </span>branch<span class="w">
</span>git<span class="w"> </span>checkout<span class="w"> </span>people/&lt;your-slug&gt;</pre><p>Nothing staged:</p><pre class="highlight code bash">git<span class="w"> </span>status<span class="w">
</span>git<span class="w"> </span>add<span class="w"> </span>index.html</pre><p>Push rejected (main protected):</p><ul><li>You are on main. Switch to your branch.</li></ul><p>Auth issues:</p><ul><li>HTTPS: check username/password</li></ul></div><div class="step step-level-1" step="39" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="62400" data-y="0" data-z="0"><h1 id="suggested-good-enough-commit-messages">Suggested &#x201C;good enough&#x201D; commit messages</h1><p>Bad:</p><ul><li>"update"</li><li>"stuff"</li><li>"changes"</li></ul><p>Better:</p><ul><li>"Add animated gif and profile link"</li><li>"Change background and typography"</li><li>"Fix broken image path"</li></ul><p>Rule: message should still make sense in 6 months.</p></div><div class="step step-level-1" step="40" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="64000" data-y="0" data-z="0"><h1 id="optional-extension-if-time-remains">Optional extension (if time remains)</h1><ul><li>Compare two branches visually (gallery view)</li><li>Show git log to narrate your work as a documented process</li><li>Merge other branches into your own</li></ul></div><div class="step step-level-1" step="41" data-rotate-x="0" data-rotate-y="0" data-rotate-z="0" data-scale="1" data-x="65600" data-y="0" data-z="0"><h1 id="wrap-up">Wrap-up</h1><p>Learn more:</p><ul><li><a href="https://learngitbranching.js.org/">Learn Git Branching</a></li><li><a href="https://ohmygit.org/">Oh My Git</a></li></ul><div class="notes"><p>End: remind participants their branches will be removed after the workshop.</p></div></div></div><script type="text/javascript" src="js/impress.js"></script><script type="text/javascript" src="js/gotoSlide.js"></script><script type="text/javascript" src="js/hovercraft.js"></script></body></html>

37
html_output/index.html
View file

File diff suppressed because one or more lines are too long

615
slides.rst
View file

@ -22,16 +22,34 @@ Braids - Intro to git
Planning (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)
1. Context: what git is, what it does, who uses it (5 min)
2. Core concepts (20 min)
3. Recap (5 min)
4. Install Git (10 min)
5. Core commands (15 min)
6. Exercise: accounts + clone/push permissions (10 min)
7. Exercise: branch a page, publish live, iterate (20 min)
8. Wrap-up: good practices + next steps (5 min)
----
Workshop outcome
================
Each participant will:
- have basic knowledge of git
- clone a repository
- create a branch
- commit changes
- push branch to our platform
----
Why git?
================
If you have been working on a file on your computer and the directory starts to look like this:
.. code-block:: bash
@ -48,13 +66,21 @@ If you have been working on a file on your computer and the directory starts to
Then git can be helpful!
.. note::
this file has different chronological versions, features and collaborators, 3 things git is great at.
----
What is git?
============
- git is a distributed version control system
- git tracks changes over time to files inside a folder
- git operates in a hidden sub-folder inside the tracked folder
- git enables:
- history (time)
@ -78,152 +104,18 @@ What is git not?
================
- git ≠ Github!
- Not a backup system (though it can help)
- Not a file sync tool (though it can be used like that)
- Not a CMS (though it can be used like that)
- Not magic: it stores snapshots + metadata, you still choose what to record
- git ≠ backup system (though it can help)
- git ≠ file sync tool (though it can be used like that)
- git ≠ CMS (though it can be used like that)
- git ≠ 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 version control system itself
- **.git**: a hidden subfolder where git operates
- **git hosts**: platforms where git repositories are hosted
- GitHub, Bitbucket, GitLab (operated by Big Tech Giants)
@ -242,6 +134,70 @@ Ecosystem
- many, many more tools and extensions
----
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?
.. note::
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: Working Areas
===========================
1. **Working tree**: your files right now
2. **Staging area**: selection for the next commit
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.
----
@ -253,7 +209,7 @@ Typical solo local workflow
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.
**Use case**: tracking changes on a local, private folder, such as bookkeeping.
----
@ -263,10 +219,10 @@ 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.
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.
**Use case**: tracking and backing up a private folder, such as a password store.
----
@ -277,28 +233,124 @@ Typical collaborative remote workflow
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.
5. **You pull (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.
**Use case**: tracking and collaborating on a repository with others such as a website project.
----
Workshop outcome
================
Core concept: Branching
=======================
.. container:: row
.. container::
In git, a **branch** is a named series of commits.
.. note::
In the previous example, there is only one branch, named "main" by default.
When you want to "take a detour" from the main course of a repository, you can create a separate branch.
.. note::
Now, parrallel timelines of the same repository exist next to each other.
Example **use cases** of branching:
- Experiment with a new feature affecting many files
- Proposing an improvement to your collaborators
- Have multiple versions of a website online
- Making existing software compatible somewhere else
.. note::
There is a lot of discourse around when to branch and how often. It varies from person to person and group to group.
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 %
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
----
Core concept: Merging
=====================
.. container:: row
.. container::
In git, **merging** is when you consolidate commits from a separate branch into your own.
.. note::
There are various merging techniques, and most of the time, the automated algorithm will work.
Sometimes, you might encounter a **merge confilct**: a section of a file where both branches have conflicting changes that cannot be automatically resolved. Here, you have to manually resolve the conflicts.
.. note::
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: 200px
:scale: 100 %
----
Complex collaborative remote workflow
=====================================
1. You clone a repository from a remote host to your local computer.
2. **You create a new branch "my-feature" for your changes**.
3. You make your changes to the repository.
4. You stage and commit your changes.
5. You push your commit (and new branch) up to the remote.
6. You pull other people's commits on this branch from the remote.
7. Repeat steps **6**, **3**, **4** and **5**
8. **You switch back to "main" and merge "my-feature" into it**.
9. **You push your new merge commit up to the "main" branch**.
**Use case**: you are designing a website for a client and want to show 3 different versions of it with different background colours.
**Use case**: tracking and collaborating on a repository with others such as a website project, where two online versions of the website exist, a "safe" one that is available to the public, and an "experimental" one that is reserved for trying new features together.
----
Recap
=====
- **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.
- **working tree**: your files as they are right now in the repository
- **staging area**: a place to add changes to
- **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
- **branch**: a named series of commits, a detour, a parallel timeline
- **merge**: a consolidation of commits from another branch
----
Install Git
===========
@ -318,25 +370,23 @@ Minimum requirement: you can run `git` in a terminal.
----
Commands: the essential set
===========================
Commands: the essentials
========================
- `git status` (always)
- `git init` (initalise a repo)
- `git commit` (store changes in the repo)
- `git add` (add files to the commit)
- `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)
- plus: log, diff
- ``git init`` (initalise a repo)
- ``git status`` (what's happening?)
- ``git add`` (add changes to the commit)
- ``git rm`` (remove a tracked file)
- ``git commit`` (store changes in the repo)
- ``git log`` (see the timeline)
- ``git checkout`` (visit the timeline at a specific checkpoint)
- ``git clone`` (an existing repo)
- ``git push`` (your commits to a remote server)
- ``git pull`` (sync with a repo online and merge)
- ``git branch`` (take a detour)
- ``git merge`` (merge branches)
----
@ -357,19 +407,6 @@ 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.
.. code-block:: bash
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)
@ -390,12 +427,19 @@ Shows:
Command: git add (select files)
===============================
First, create a file
.. code-block:: bash
nano index.html
Stage files for the next commit.
.. code-block:: bash
git add index.html
git add assets/
Stage everything (use carefully):
@ -407,10 +451,26 @@ Stage everything (use carefully):
Staging is curatorial: select what belongs together.
----
Command: git commit
========================================
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.
----
Command: git commit (checkpoint)
================================
.. code-block:: bash
@ -422,6 +482,11 @@ Good commit message pattern:
- Why it changed (reason/intent)
- Scope stays small
.. note::
repeat edit > stage > commit a couple times?
..
----
@ -442,7 +507,7 @@ Good commit message pattern:
----
Command: git log (inventory)
Command: git log (timeline)
============================
.. code-block:: bash
@ -453,47 +518,63 @@ Gives a quick "finding aid" of earlier commits. Press 'q' to exit.
----
Command: git branch and git checkout
====================================
List branches:
Command: git checkout (timetravel)
==================================
.. code-block:: bash
git branch
git checkout your_commit_id
Create a branch:
See your working tree as it would have been at a specific commit on the timeline.
.. 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
============================
Command: git clone
==================
Push your branch to the server:
Cloen (copy) a repository in the current folder. First, `cd` to a logical location in your computer, then:
.. code-block:: bash
git push -u origin people/yourname
git clone https://git.hackersanddesigners.nl/hrk/braids
cd braids
Downloads a repo from the web, complete with the full commit history and all changes.
Make edits here as you wish then stage and commit them.
----
Command: git push
=================
Push your commits to the server:
.. code-block:: bash
git push -u origin main
.. code-block:: bash
git push
.. note::
disabled push rights for now, only for demonstration purposes, will fail
----
Command: git pull
=================
.. note::
before we do this, one of us changes the background colour and pushes
Pull updates from server:
@ -506,19 +587,52 @@ Pull updates from server:
During the exercise you mostly push your branch.
Pull is mainly for getting new changes on main (if needed).
fact: git pull is actually a git fetch && git merge
----
Optional: git rm
================
Command: git branch
===================
Remove a tracked file and stage the removal:
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.
List branches:
.. code-block:: bash
git rm old.html
git commit -m "Remove old page"
git branch
Create a branch:
.. code-block:: bash
git branch people/<your-slug>
Switch to branch:
.. code-block:: bash
git checkout people/<your-slug>
Shortcut (create + switch):
.. code-block:: bash
git checkout -b people/<your-slug>
.. note::
Branches are parallel dossiers: safe space for changes.
----
Command: git merge
===================
?
For this workshop you probably will not need it.
----
@ -529,6 +643,7 @@ Forgejo: what we use today
- Forgejo hosts the central repository (remote)
You will:
- create an account
- clone via HTTPS
- push your branch
@ -554,8 +669,11 @@ Resources:
- live gallery URL: https://braids.hackersanddesigners.nl
- these slides: https://braids.hackersanddesigners.nl/slides
----
Exercise overview
=================
@ -572,17 +690,11 @@ clone -> branch -> edit -> status -> add -> commit -> push -> view -> iterate
----
Exercise: step 1 (clone)
========================
Exercise: step 1 (clone & branch)
=================================
`cd` to a logical location in your computer, then:
.. code-block:: bash
git clone https://git.hackersanddesigners.nl/hrk/braids
cd braids
If everything went well, check the repo with:
If everything went well in your initial clone & branch, check the repo with:
.. code-block:: bash
@ -593,24 +705,7 @@ The first time you checkout from https://git.hackersanddesigners.nl the server w
----
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.
.. code-block:: bash
git checkout -b people/<your-slug>
Confirm:
.. code-block:: bash
git status
----
Exercise: step 3 (edit the page)
Exercise: step 2 (edit the page)
================================
Edit the root `index.html` (and optionally `style.css`, `assets/`).
@ -628,7 +723,7 @@ Then check changes:
----
Exercise: step 4 (stage + commit)
Exercise: step 3 (stage + commit)
=================================
.. code-block:: bash
@ -649,7 +744,7 @@ If you added assets:
----
Exercise: step 5 (push your branch)
Exercise: step 4 (push your branch)
===================================
.. code-block:: bash
@ -662,7 +757,7 @@ If prompted for credentials, use your Forgejo login method.
----
Exercise: step 6 (view live)
Exercise: step 5 (view live)
============================
Open the gallery:
@ -704,16 +799,7 @@ 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)
----
@ -741,6 +827,7 @@ Optional extension (if time remains)
- Compare two branches visually (gallery view)
- Show `git log` to narrate your work as a documented process
- Merge other branches into your own
----