: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. ---- 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. 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 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/` ---- 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 ---- Exercise: step 2 (create your branch) ===================================== Choose a slug: lowercase, no spaces. This can be your name or an alias. Example: change `people/` in the command below to `people/alex`. .. code-block:: bash git checkout -b people/ 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 " If you added assets: .. code-block:: bash git add assets/ git commit -m "Add assets for " .. note:: Small commits win. One change = one deposit. ---- Exercise: step 5 (push your branch) =================================== .. code-block:: bash git push -u origin people/ (Again, change !) 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//` Iterate: edit -> status -> add -> commit -> push -> refresh ---- Common problems (fast fixes) ============================ Wrong branch: .. 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/password ---- Concept recap in archiving terms ================================ - commit = deposit (with minimal metadata) - log = inventory / chain of custody - diff = conservation report (what changed) - branch = parallel dossier - push = share publicly / deposit to institutional archive (remote) ---- Suggested “good enough” commit messages ======================================= Bad: - "update" - "stuff" - "changes" Better: - "Add animated gif and profile link" - "Change background and typography" - "Fix broken image path" Rule: message should still make sense in 6 months. ---- Optional extension (if time remains) ==================================== - Compare two branches visually (gallery view) - Add a second commit that intentionally breaks something, then fix it with a third commit - Show `git log` to narrate your work as a documented process ---- Wrap-up ======= You should now be able to: - create a branch safely - record changes as commits - publish to a remote - read history and differences Learn more: - `Learn Git Branching `_ - `Oh My Git `_ .. note:: End: remind participants their branches will be removed after the workshop.