🪢 Braids 🪢 Introduction to git 🪢 with H&D 🪢

🪢 Braids: Intro to git 🪢

Goal: introduce Git as an archiving practice, then do a little branch-based website exercise published live.

Planning (90 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 & next steps? (5 min)

Why git?

If you have been working on a file on your computer and the directory starts to look like this:

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!

this file has different chronological versions, features and collaborators, 3 things git is great at.

What is git?

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 is git not?

we will see today that is git is best suited for text-based projects, especially when parsing the text is particularly useful it's not a good choice for recording history on very large files (such as videos) or files where the raw textual data is illegible

Ecosystem

Core concept: Commits

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.

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

This is why Git feels "archival": - you intentionally select what becomes part of the record.

Typical solo local workflow

  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, like 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 passwords.

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 (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 with multiple developers.

Core concept: Branching

In git, a branch is a named series of commits.

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.

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

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.

Core concept: Merging

In git, merging is when you consolidate commits from a separate branch into your own.

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.

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.

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

Install Git

Check first:

git --version

If missing:

Minimum requirement: you can run git in a terminal.

Commands: the essentials

Command: git init

Create a repository in the current folder. Use this when you are creating and working on your own projects.

git init

Creates a .git/ directory containing history + metadata.

For the exercise we will use git clone instead of git init.

Command: git status (your dashboard)

git status

Shows:

Command: git add (select files)

First, create a file

nano index.html

Stage files for the next commit.

git add index.html

Stage everything (use carefully):

git add .

Staging is curatorial: select what belongs together.

Optional: git rm

Remove a tracked file and stage the removal:

git rm old.html
git commit -m "Remove old page"

For this workshop you probably will not need it.

Command: git commit (checkpoint)

git commit -m "Added name to my page"

Good commit message pattern:

repeat edit > stage > commit a couple times?

Command: git log (timeline)

git log --oneline --graph

Gives a quick "finding aid" of earlier commits. Press 'q' to exit.

Command: git checkout (timetravel)

git checkout your_commit_id

See your working tree as it would have been at a specific commit on the timeline.

Forgejo: what we use today

You will:

Share your username with us so we can add you as a collaborator

Rules for today:

Forgejo: account setup

  1. Create account at: git.hackersanddesigners.nl
  2. Confirm you can sign in

Resources:

Exercise overview

You will build a (deliberately) simple page:

Workflow loop:

clone -> branch -> edit -> status -> add -> commit -> push -> view -> iterate

Command: git clone

Clone (copy) a repository in the current folder. First, cd to a logical location in your computer, then:

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

That will checkout the repo into a directory /braids, go into this new directory with:

cd braids

You have now downloaded a repo from the web, complete with the full commit history and all changes.

Command: git branch

Choose a slug: lowercase, no spaces. This can be your name or an alias. Example: change braids/<your-slug> in the command below to braids/alex. From here on out replace <your-slug> with your chosen name!

List branches:

git branch

Create a branch:

git branch braids/<your-slug>

Switch to branch:

git checkout braids/<your-slug>

Shortcut (create + switch):

git checkout -b braids/<your-slug>

If everything went well, check the repo with:

git status
git branch

Branches are parallel dossiers: safe space for changes.

Edit the page

Edit the root index.html (and optionally add style.css, assets/).

Make a visible change first:

Then check changes:

git diff
git status

Stage & commit your changes

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

If you added assets:

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

Small commits win. One change = one deposit.

Push your banch

Push your commits to the server, defining a remote branch to track. This is called setting the upstream.

git push -u origin braids/<your-slug>

(Again, change <your-slug>!)

This pushes your branch to the 'origin' server.

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

From then on, unless the remote/branch is named, git push will go in that direction.

git push

disabled push rights for now, only for demonstration purposes, will fail

View live!

Open the gallery:

Find your card:

Iterate:

edit -> status -> add -> commit -> push -> refresh

Common problems (fast fixes)

Wrong branch:

git branch
git checkout braids/<your-slug>

Nothing staged:

git status
git add index.html

Push rejected (main protected):

Auth issues:

Suggested “good enough” commit messages

Bad:

Better:

Rule: message should still make sense in 6 months.

Optional: git pull

If you want to collaborate with others on the same branch, pull updates from server:

git pull

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 merge

First, go ahead and git fetch --all branches from the remote git repository, so you have them locally.

Then git branch to see the available branches.

Check some of them out with git checkout braids/<branch_name>.

See something you like? Merge with them.

git checkout braids/<your-slug>
git merge braids/<chosen_branch>

Consolidate any merge conflicts manually if you have to. Then, stage, commit and push your changes to your branch.

Optional extension (if time remains)

Wrap-up

Learn more:

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