diff --git a/html_output/2026-01-14_km.html b/html_output/2026-01-14_km.html index fb73f96..52c1504 100644 --- a/html_output/2026-01-14_km.html +++ b/html_output/2026-01-14_km.html @@ -5,10 +5,7 @@ TeX : { extensions : ['color.js'] } });

Braids - Intro 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: commits & three areas (10 min)
  3. Install Git (10 min)

Enumerated list ends without a blank line; unexpected unindent.

4. Essential commands: (10 min) -2. Core concepts: branching & merging (5 min) -4. Extended commands: (10 min) -4. Forgejo: accounts + clone/push permissions (10 min) +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: commits & working areas (10 min)
  3. Core concepts: branching & merging (10 min)
  4. Terminology overview (5 min)
  5. Install Git (10 min)
  6. Essential commands: (10 min)

Enumerated list ends without a blank line; unexpected unindent.

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

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
@@ -17,23 +14,30 @@ then do a little branch-based website exercise published live.
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!

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

What is git?

is the archive analogy helpful? it feels a bit like comapring something abstract with something else thats abstract

Archiving analogy: +motivation-letter-FINAL-pictures-small.odt

Then git can be helpful!

Workshop outcome

Each participant will:

  • have basic knowledge of git
  • clone a repository
  • create a branch
  • commit changes
  • push branch to our platform

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)
    • collaboration (many authors)
    • experimentation (branches)
    • traceability (who/what/when/why)

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?

  • git ≠ Github!
  • 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

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)
    • Alternatives
      • Codeberg (non-profit, community led)
      • Oxacab (riseup.net for activists, journalists)
      • Forgejo / Gitea (self-hosted)
  • git clients: tools used to work with git on your computer
    • git command line tool (free & open source)
    • tig command line tool (free & open source)
    • sourcetree, Github Desktop, VS Code (operated by Big Tech)
    • many code editors (e.g. sublime, atom) have git extensions
    • many, many more tools and extensions

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: Three Areas

  1. Working tree: your files right now
  2. Staging area: selection for the next deposit
  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, such as 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 a password store.

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

Install Git

Check first:

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.

Commands: the essential set

  • git init (initalise a repo)
  • git clone (an existing 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 push (your commits to a remote server)
  • git pull (sync with a repo online and merge)

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 clone

Cloen (copy) a repository in the current folder.

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)

git status

Shows:

  • current branch
  • staged vs unstaged changes
  • untracked files

Command: git add (select files)

Stage files for the next commit.

git add index.html
-git add assets/

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

git commit -m "Added name to my page"

Good commit message pattern:

  • What changed
  • Why it changed (reason/intent)
  • Scope stays small

Command: git log (inventory)

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.

Command: git push

Push your branch to the server:

git push -u origin people/yourname
git push

Command: git pull

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

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.

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.

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

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 (upload) your commit up to the remote, publishing your branch for others to see / work on.
  6. You pull (re-download) other people's commits from the remote.
  7. Repeat steps 6, 3, 4 and 5
  8. When ready, you switch back to "main" branch and merge "my-feature" branch into it.
  9. You push your new merge commit up to the "main" branch on remote.

Use case: tracking and collaborating on a repository with others such as a website project, where multiple features and parrallel versions of the website exist.

Commands: the extended set

  • git branch (take a detour)
  • git merge (merge branches)

Bullet list ends without a blank line; unexpected unindent.

Command: git branch

List branches:

git branch

Create a branch:

git branch people/yourname

Switch to branch:

git checkout people/yourname

Shortcut (create + switch):

git checkout -b people/yourname

Branches are parallel dossiers: safe space for changes.

Command: git merge

Interlude: 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
  • 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: an incorporation of commits from another branch

Forgejo: what we use today

  • Forgejo is an open-source alternative to Github
  • Forgejo hosts the central repository (remote)

You will: +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: Three Areas

  1. Working tree: your files right now
  2. Staging area: selection for the next deposit
  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, such as 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 a password store.

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

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

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 (upload) your commit up to the remote, publishing your branch for others to see / work on.
  6. You pull (re-download) other people's commits from the remote.
  7. Repeat steps 6, 3, 4 and 5
  8. When ready, you switch back to "main" branch and merge "my-feature" branch into it.
  9. You push your new merge commit up to the "main" branch on remote.

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.

Terminology Overview

Install Git

Check first:

git --version

If missing:

Minimum requirement: you can run git in a terminal.

Commands: the essential set

Bullet list ends without a blank line; unexpected unindent.

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 clone

Cloen (copy) a repository in the current folder.

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)

git status

Shows:

Command: git add (select files)

Stage files for the next commit.

git add index.html
+git add assets/

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

git commit -m "Added name to my page"

Good commit message pattern:

Command: git log (inventory)

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.

Command: git push

Push your branch to the server:

git push -u origin people/yourname
git push

Command: git pull

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

Command: git branch

List branches:

git branch

Create a branch:

git branch people/yourname

Switch to branch:

git checkout people/yourname

Shortcut (create + switch):

git checkout -b people/yourname

Branches are parallel dossiers: safe space for changes.

Command: git merge

Forgejo: what we use today

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:

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

Exercise: step 1 (clone)

cd to a logical location in your computer, then:

git clone https://git.hackersanddesigners.nl/hrk/braids
+- 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/<your-slug>

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

Exercise: step 1 (clone)

cd to a logical location in your computer, then:

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

If everything went well, check the repo with:

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. From here on out replace <your-slug> with your chosen name.

git checkout -b people/<your-slug>

Confirm:

git status

Exercise: step 3 (edit the page)

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

Make a visible change first:

Then check changes:

git diff
-git status

Exercise: step 4 (stage + commit)

git add index.html
+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. From here on out replace <your-slug> with your chosen name.

git checkout -b people/<your-slug>

Confirm:

git status

Exercise: step 3 (edit the page)

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

Make a visible change first:

Then check changes:

git diff
+git status

Exercise: step 4 (stage + commit)

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.

Exercise: step 5 (push your branch)

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:

Find your card:

Iterate:

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

Common problems (fast fixes)

Wrong branch:

git branch
+git commit -m "Add assets for <your-slug>"

Small commits win. One change = one deposit.

Exercise: step 5 (push your branch)

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:

Find your card:

Iterate:

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

Common problems (fast fixes)

Wrong branch:

git branch
 git checkout people/<your-slug>

Nothing staged:

git status
-git add index.html

Push rejected (main protected):

Auth issues:

Concept recap in archiving terms

Suggested “good enough” commit messages

Bad:

Better:

Rule: message should still make sense in 6 months.

Optional extension (if time remains)

Wrap-up

Learn more:

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

\ No newline at end of file +git add index.html

Push rejected (main protected):

Auth issues:

Concept recap in archiving terms

Suggested “good enough” commit messages

Bad:

Better:

Rule: message should still make sense in 6 months.

Optional extension (if time remains)

Wrap-up

Learn more:

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

\ No newline at end of file diff --git a/html_output/index.html b/html_output/index.html index fb73f96..52c1504 100644 --- a/html_output/index.html +++ b/html_output/index.html @@ -5,10 +5,7 @@ TeX : { extensions : ['color.js'] } });

Braids - Intro 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: commits & three areas (10 min)
  3. Install Git (10 min)

Enumerated list ends without a blank line; unexpected unindent.

4. Essential commands: (10 min) -2. Core concepts: branching & merging (5 min) -4. Extended commands: (10 min) -4. Forgejo: accounts + clone/push permissions (10 min) +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: commits & working areas (10 min)
  3. Core concepts: branching & merging (10 min)
  4. Terminology overview (5 min)
  5. Install Git (10 min)
  6. Essential commands: (10 min)

Enumerated list ends without a blank line; unexpected unindent.

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

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
@@ -17,23 +14,30 @@ then do a little branch-based website exercise published live.
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!

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

What is git?

  • git is a distributed version control system
  • git is a hidden sub-folder in a folder
  • git tracks changes over time to files inside a folder
  • git enables:
    • history (time)
    • collaboration (many authors)
    • experimentation (branches)
    • traceability (who/what/when/why)

is the archive analogy helpful? it feels a bit like comapring something abstract with something else thats abstract

Archiving analogy: +motivation-letter-FINAL-pictures-small.odt

Then git can be helpful!

Workshop outcome

Each participant will:

  • have basic knowledge of git
  • clone a repository
  • create a branch
  • commit changes
  • push branch to our platform

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)
    • collaboration (many authors)
    • experimentation (branches)
    • traceability (who/what/when/why)

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?

  • git ≠ Github!
  • 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

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)
    • Alternatives
      • Codeberg (non-profit, community led)
      • Oxacab (riseup.net for activists, journalists)
      • Forgejo / Gitea (self-hosted)
  • git clients: tools used to work with git on your computer
    • git command line tool (free & open source)
    • tig command line tool (free & open source)
    • sourcetree, Github Desktop, VS Code (operated by Big Tech)
    • many code editors (e.g. sublime, atom) have git extensions
    • many, many more tools and extensions

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: Three Areas

  1. Working tree: your files right now
  2. Staging area: selection for the next deposit
  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, such as 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 a password store.

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

Install Git

Check first:

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.

Commands: the essential set

  • git init (initalise a repo)
  • git clone (an existing 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 push (your commits to a remote server)
  • git pull (sync with a repo online and merge)

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 clone

Cloen (copy) a repository in the current folder.

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)

git status

Shows:

  • current branch
  • staged vs unstaged changes
  • untracked files

Command: git add (select files)

Stage files for the next commit.

git add index.html
-git add assets/

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

git commit -m "Added name to my page"

Good commit message pattern:

  • What changed
  • Why it changed (reason/intent)
  • Scope stays small

Command: git log (inventory)

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.

Command: git push

Push your branch to the server:

git push -u origin people/yourname
git push

Command: git pull

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

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.

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.

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

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 (upload) your commit up to the remote, publishing your branch for others to see / work on.
  6. You pull (re-download) other people's commits from the remote.
  7. Repeat steps 6, 3, 4 and 5
  8. When ready, you switch back to "main" branch and merge "my-feature" branch into it.
  9. You push your new merge commit up to the "main" branch on remote.

Use case: tracking and collaborating on a repository with others such as a website project, where multiple features and parrallel versions of the website exist.

Commands: the extended set

  • git branch (take a detour)
  • git merge (merge branches)

Bullet list ends without a blank line; unexpected unindent.

Command: git branch

List branches:

git branch

Create a branch:

git branch people/yourname

Switch to branch:

git checkout people/yourname

Shortcut (create + switch):

git checkout -b people/yourname

Branches are parallel dossiers: safe space for changes.

Command: git merge

Interlude: 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
  • 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: an incorporation of commits from another branch

Forgejo: what we use today

  • Forgejo is an open-source alternative to Github
  • Forgejo hosts the central repository (remote)

You will: +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: Three Areas

  1. Working tree: your files right now
  2. Staging area: selection for the next deposit
  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, such as 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 a password store.

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

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

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 (upload) your commit up to the remote, publishing your branch for others to see / work on.
  6. You pull (re-download) other people's commits from the remote.
  7. Repeat steps 6, 3, 4 and 5
  8. When ready, you switch back to "main" branch and merge "my-feature" branch into it.
  9. You push your new merge commit up to the "main" branch on remote.

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.

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
  • 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: an incorporation of commits from another branch

Install Git

Check first:

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.

Commands: the essential set

  • git init (initalise a repo)
  • git clone (an existing 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 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)

Bullet list ends without a blank line; unexpected unindent.

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 clone

Cloen (copy) a repository in the current folder.

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)

git status

Shows:

  • current branch
  • staged vs unstaged changes
  • untracked files

Command: git add (select files)

Stage files for the next commit.

git add index.html
+git add assets/

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

git commit -m "Added name to my page"

Good commit message pattern:

  • What changed
  • Why it changed (reason/intent)
  • Scope stays small

Command: git log (inventory)

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.

Command: git push

Push your branch to the server:

git push -u origin people/yourname
git push

Command: git pull

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

Command: git branch

List branches:

git branch

Create a branch:

git branch people/yourname

Switch to branch:

git checkout people/yourname

Shortcut (create + switch):

git checkout -b people/yourname

Branches are parallel dossiers: safe space for changes.

Command: git merge

Forgejo: what we use today

  • Forgejo is an open-source alternative to Github
  • 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/<your-slug>

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:

  • "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:

git clone https://git.hackersanddesigners.nl/hrk/braids
+- 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/<your-slug>

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:

  • "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:

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

If everything went well, check the repo with:

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. From here on out replace <your-slug> with your chosen name.

git checkout -b people/<your-slug>

Confirm:

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:

git diff
-git status

Exercise: step 4 (stage + commit)

git add index.html
+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. From here on out replace <your-slug> with your chosen name.

git checkout -b people/<your-slug>

Confirm:

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:

git diff
+git status

Exercise: step 4 (stage + commit)

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.

Exercise: step 5 (push your branch)

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:

git branch
+git commit -m "Add assets for <your-slug>"

Small commits win. One change = one deposit.

Exercise: step 5 (push your branch)

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:

git branch
 git checkout people/<your-slug>

Nothing staged:

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)
  • Show git log to narrate your work as a documented process

Wrap-up

Learn more:

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

\ No newline at end of file +git add index.html

Push rejected (main protected):

Auth issues:

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)
  • Show git log to narrate your work as a documented process

Wrap-up

Learn more:

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

\ No newline at end of file diff --git a/slides.rst b/slides.rst index 4eecece..5d9deb2 100644 --- a/slides.rst +++ b/slides.rst @@ -23,12 +23,12 @@ Planning (90 min) ================= 1. Context: what git is, what it does, who uses it (5 min) -2. Core concepts: commits & three areas (10 min) -3. Install Git (10 min) -4. Essential commands: (10 min) -2. Core concepts: branching & merging (5 min) -4. Extended commands: (10 min) -4. Forgejo: accounts + clone/push permissions (10 min) +2. Core concepts: commits & working areas (10 min) +3. Core concepts: branching & merging (10 min) +4. Terminology overview (5 min) +5. Install Git (10 min) +6. Essential commands: (10 min) +7. 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) @@ -60,13 +60,11 @@ Workshop outcome Each participant will: - - clone a repo + - have basic knowledge of git + - clone a repository - 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 - + - commit changes + - push branch to our platform ---- @@ -74,8 +72,8 @@ What is git? ============ - git is a distributed version control system -- git is a hidden sub-folder in a folder - 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) @@ -148,15 +146,17 @@ Core concept: Commits 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. + .. note:: - The changes possible in a commit are: - - editing a file - - adding a file - - removing a file - - renaming (moving) a file + 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. - Commits do not know about the timeline they are in. They only know of their preceeding commit, otherwise known as their "parent". + 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. @@ -203,7 +203,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. ---- @@ -216,7 +216,7 @@ Typical solo remote workflow 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. ---- @@ -230,13 +230,117 @@ Typical collaborative remote workflow 5. You pull (re-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. +---- + + +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. + + 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: + - 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 + + + .. 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 % ---- +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: 300px + :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 (upload) your commit up to the remote, publishing your branch for others to see / work on. +6. You pull (re-download) other people's commits from the remote. +7. Repeat steps **6**, **3**, **4** and **5** +8. When ready, you switch back to "main" branch and merge "my-feature" branch into it. +9. You push your new merge commit up to the "main" branch on remote. + + +**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. + + +---- + +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 +- **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**: an incorporation of commits from another branch + +---- + + Install Git =========== @@ -271,7 +375,10 @@ Commands: the essential set - `git checkout` (visit the timeline at a specific checkpoint) - `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) +.. - `git diff` (what changed) +.. - `git log` (history) ---- @@ -447,89 +554,6 @@ Pull updates from server: Pull is mainly for getting new changes on main (if needed). - ----- - -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 % - - ----- - -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 (upload) your commit up to the remote, publishing your branch for others to see / work on. -6. You pull (re-download) other people's commits from the remote. -7. Repeat steps **6**, **3**, **4** and **5** -8. When ready, you switch back to "main" branch and merge "my-feature" branch into it. -9. You push your new merge commit up to the "main" branch on remote. - -Use case: tracking and collaborating on a repository with others such as a website project, where multiple features and parrallel versions of the website exist. - - ----- - -Commands: the extended set -========================== -- `git branch` (take a detour) -- `git merge` (merge branches) -.. - `git diff` (what changed) -.. - `git log` (history) - ---- Command: git branch @@ -571,23 +595,6 @@ Command: git merge ----- - -Interlude: 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 -- **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**: an incorporation of commits from another branch ----