:title: Braids - Intro to Git
:author: H&D
:description: 
:css: slides.css

.. header::

  Braids - Intro to Git

----

Braids - Intro to Git
=====================

.. note::

   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:

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

----

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.

.. 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 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)
====================================

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

.. code-block:: bash

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

If everything went well, check the repo with:

.. code-block:: bash

   git status
   git branch

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

----

Exercise: step 2 (create your branch)
=====================================

Choose a slug: lowercase, no spaces. This can be your name or an alias. Example: change `people/<your-slug>` in the command below to `people/alex`.

.. code-block:: bash

   git checkout -b people/<your-slug>

Confirm:

.. code-block:: bash

   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:

.. code-block:: bash

   git diff
   git status

----

Exercise: step 4 (stage + commit)
=================================

.. code-block:: bash

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

If you added assets:

.. code-block:: bash

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

.. note::

   Small commits win. One change = one deposit.

----

Exercise: step 5 (push your branch)
===================================

.. code-block:: bash

   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:

.. code-block:: bash

   git branch
   git checkout people/<your-slug>

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/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 <https://learngitbranching.js.org/>`_ 
- `Oh My Git <https://ohmygit.org/>`_

.. note::

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