570 lines
9.6 KiB
ReStructuredText
570 lines
9.6 KiB
ReStructuredText
: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. |