1 of 52

Git und GitHub im Kontext von DH-Projekten

www.dhcraft.org

Christopher Pollin�Christian Steiner�Digital Humanities Craft OG

2 of 52

Agenda

Einführung

Git und seine Grundprinzipien

Arbeiten mit GitHub

GitHub als Software Engineering Tool

GitHub und Dokumentation

Recap und Wiederholung

3 of 52

Lernziele

Kennenlernen von Git-Grundlagen und grundsätzlicher Git-Workflows (anlegen, einchecken, staging, commit).

Umgang mit der Software GitHub Desktop und Anwendung grundsätzlicher Git-Workflows in GitHub.

Nutzung der Software Engineering-Möglichkeiten von GitHub (issues etc.) und Kennenlernen von Best Practices.

Nutzung der Dokumentationsmöglichkeiten innerhalb von GitHub und das Kennenlernen der Best Practices.

​

[Schwerpunkt nicht auf Programmierer*innen, sondern DH Projekte]

4 of 52

1. Block

4

45 min Git und seine Grundprinzipien

5 of 52

“I’m an egotistical bastard, and I name all my projects after myself. First ‘Linux’, now ‘Git’.”

– Linus Torvalds, https://de.wikipedia.org/wiki/Git [Git ~ Blödmann]

​

Git ist ein freies, verteiltes Versionsverwaltungssystem für Dateien.

6 of 52

Begriffe

Was ist eine Datei?�z.B. Text (.txt), Bild (.jpg), Musik (.mp3), XML/TEI (.xml), JavaScript (.js) …

​

​

<?xml version="1.0" encoding="UTF-8"?>�<memo>� <body>� <p>Yoda says,� “For your support thank I must!”

</p>

</body>

</memo>

<?xml version="1.0" encoding="UTF-8"?>�<memo>� <body>� <p>Yoda says, � <q>For your support thank I must!<q>

</p>

</body>

</memo>

​

Version 1

Version 2

Was ist eine Version?� Eine Version beschreibt den Inhalt einer Datei zu einem bestimmten Zeitpunkt. � Die Änderung einer Datei erzeugt eine neue Version.

7 of 52

Begriffe

Was ist Versionskontrolle?� Ermöglicht die Verwaltung verschiedener Versionen von Dateien.� Erlaubt einen “Blick zurück” durch die Versionen von Dateien.

https://open.hpi.de/courses/git2020

8 of 52

Git ist ein freies, verteiltes Versionsverwaltungssystem für Dateien - Wie funktioniert es genau?

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

Lokaler Rechner

Staging

Working Directory

Commit History

memo.xml

git add memo.xml

git commit

Commit

Commit

Commit

9 of 52

Lokaler Rechner und Remote-Server

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

Staging

Commit

Commit

Commit

git push

git pull

git pull

Lokaler Rechner

Remote-Server

10 of 52

Git Befehle

$ git add�Datei (in ihrem gegenwärtigen Zustand) �zum nächsten Commit hinzufügen (Staging)��$ git commit�Alles was in Staging ist, kommt als Commit in das Repository (Commit History)

$ git push�Wird verwendet, um Inhalte aus einem lokalen Repository in ein Remote-Repository hochzuladen.

$ git clone�Über eine URL ein neues Repository kopieren.

$ git pull�Der pull-Befehl wird verwendet, um Inhalte aus einem Remote-Repository herunterzuladen und unverzüglich das lokale Repository zu aktualisieren, damit die Inhalte übereinstimmen.

​

​

​

​

https://education.github.com/git-cheat-sheet-education.pdf

https://www.atlassian.com/de/git/tutorials/syncing

$ git fetch�Damit werden Commits, Dateien und Verweise aus einem Remote-Repository in das lokale Repository heruntergeladen.

$ git merge�Die heruntergeladenen Dateien etc. werden mit den lokalen zusammengeführt.

​

11 of 52

Grundprinzipien von Git

  1. Snapshots statt Unterschiede
  2. Fast jede Operation ist lokal
  3. Git stellt Integrität sicher
  4. Git fügt im Regelfall nur Daten hinzu
  5. Die drei Zustände (modified, staged, commited)

https://git-scm.com/book/de/v2/Erste-Schritte-Was-ist-Git%3F

12 of 52

2. Block

12

45 min Arbeiten mit GitHub

13 of 52

Command Line vs. GUI Clients

  • GitHub Desktop�Platforms: Mac, Windows�Price: Free
  • Git Extensions�Platforms: Linux, Mac, Windows�Price: Free

https://git-scm.com/downloads/guis

  • TortoiseGit�Platforms: Windows�Price: Free
  • GitKraken�Platforms: Linux, Mac, Windows�Price: Free / $29 / $49

https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html

14 of 52

Gemeinsames Hands-On: “mein memo.xml”

  • Erzeugen Sie einen neuen Ordner mit dem Namen GitHub. �(Z.B.: C:\Users\pollin\Documents\GitHub)
  • Legen Sie innerhalb des Ordners GitHub einen Ordner “PM_DH22” an.
  • Öffnen Sie GitHub Desktop.
  • Clonen Sie das Repository https://github.com/chpollin/PM_DH22
    • das Repository�heißt “PM_DH22”.
    • das entspricht dem Befehl�$ git clone
  • In unserem neuen Ordner befinden sich�jetzt alle Daten - lokal bei uns -�aus dem Repository.

15 of 52

Gemeinsames Hands-On: “mein memo.xml”

​

  • Erstellen Sie eine neue XML bzw. verändern Sie helloworld_template.xml, benennen Sie es um und speichern Sie es - Datei mit folgender Struktur und Ihrem Vornamen.�<?xml version="1.0" encoding="UTF-8"?>�<memo>� <body>� <p>Hello Git from Christopher</p>� </body>�</memo>
  • Legen Sie die Datei mit dem Dateinamen helloworld_VORNAME.xml in Ihrem lokalen Ordner PM_DH22\xml ab.

16 of 52

Wenn die neue Datei angelegt wurde, erscheinen folgende Änderungen in GitHub Desktop auf.

Jeder Commit muss immer eine Nachricht beinhalten. Damit soll ausgedrückt werden, was Sie gerade bearbeitet oder hinzugefügt haben.

​

Die Dateien befinden sich in der Staging Area.

Mit dem Button “Commit to main” wird git commit aktiviert und der Commit kommt in die Commit History.

17 of 52

Jetzt muss das Ganze noch in das Repository (Test-Training-Repo) gepusht werden - git push aktiv.

​

Unsere Dateien sind jetzt auf dem Server.

18 of 52

In der History in GitHub Desktop bzw. auf der Webseite https://github.com/chpollin/PM_DH22/tree/main/xml können wir die Commits einsehen.

​

​

19 of 52

$ git fetch

Gleichen Sie ab: Gibt es was Neues bei uns lokal? Gibt es etwas Neues im Repository am Server?

​

�

Bearbeiten Sie nun das XML-Dokument von Ihrer/Ihrem alphabetisch nächsten Kollegin/Kollegen. Fügen Sie eine Kleinigkeit hinzu, wie z.B. ein zweites <p> mit dem Text “Greetings from Christian”.�

<?xml version="1.0" encoding="UTF-8"?>�<memo>� <body>� <p>Hello Git from Christopher</p>� <p>Greetings from Christian</p>� </body>�</memo>

20 of 52

Es könnte jetzt zu einem Konflikt gekommen sein, weil zwei Personen gleichzeitig dieselbe Datei bearbeitet haben.

“Git can handle most merges on its own with automatic merging features. A conflict arises when two separate branches have made edits to the same line in a file, or when a file has been deleted in one branch but edited in the other. Conflicts will most likely happen when working in a team environment.”

21 of 52

https://github.com/chpollin/PM_DH22

22 of 52

“The Perfect Commit”

Git for Professionals Tutorial - Tools & Concepts for Mastering Version Control with Git, https://www.youtube.com/watch?v=Uszj_k0DGsg

  • Jeder Commit gehört zu einem Thema. Themen sollten nicht in den gleichen Commits gemischt werden.
    • Commit: Annotation der Personen im XML/TEI
    • Überarbeitung des msDesc im teiHeader
    • Das XSLT zur Normalisierung von X

→ nur die Dateien ankreuzen, die zum Thema passen.

→ gemeinsame Regeln definieren, was ein Commit ist. �

  • Commit-Message
    • Kleine Zusammenfassung
    • “Kurz und knackig” & effektiv
    • Ungewöhnliches und Wichtiges explizieren

→ gemeinsame Regeln definieren, wie eine Commit-Message aufgebaut sein muss.

23 of 52

3. Block

23

45 min GitHub als Software Engineering Tool

​

24 of 52

Issues

https://github.com/KlassikStiftungWeimar/Test-Training-Repo/issues/3

25 of 52

Milestones

https://github.com/chpollin/PM_DH22/milestone/1

26 of 52

Beispiele

Consulting Schönberg Edition�https://github.com/chpollin/Schoenberg/issues

Interne Arbeit in DHCraft�https://github.com/DigitalHumanitiesCraft/Projects/issues

Stefan Zweig digital�https://github.com/chpollin/SZD/issues

27 of 52

Projects

https://github.com/KlassikStiftungWeimar/Test-Training-Repo/projects/1

28 of 52

Hands-On: Issue anlegen

  • Legen Sie ein Issue an und assignen Sie jemanden, der/die eine Änderung in einem der vielen helloworld_xxx.xml machen soll.
  • Fügen Sie ein Label und einen Milestone hinzu.
  • Die zugeordnete Person führt den Issue aus, committet die Änderung und referenziert mit #ISSUE ID auf das zugehörige Issue.
  • Pushen Sie die Änderung.
  • Fügen Sie ein Comment hinzu und schließen Sie das Issue.

​

​

29 of 52

“The best Issue”

Simpel, prägnant und beschreibend

Einheitliche Formatierung

Bearbeitbar / Durchführbar

Relevant

Kontext

Problem oder Idee

Lösung und nächste Schritte

How We Write Github Issues, https://wiredcraft.com/blog/how-we-write-our-github-issues/

30 of 52

31 of 52

4. Block

31

45 min GitHub und Dokumentation

​

32 of 52

Markdown

33 of 52

Überschriften, Text, ungeordnete Liste, Code Block

34 of 52

Absätze, geordnete Liste, Schriftauszeichnung (kursiv & fett)

35 of 52

Blockzitate, Links, Bilder, Tabellen, Inhaltsverzeichnis

https://github.com/KlassikStiftungWeimar/Test-Training-Repo/blob/main/documents/cheatsheet.md

36 of 52

README.md zur Dokumentation

https://github.com/chpollin/PM_DH22

​

About READMEs, https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes

37 of 52

Wiki: Beispiel Kodierungsregeln

https://github.com/chpollin/Schoenberg/wiki/Kodierungsregeln �About wikis, https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis

38 of 52

Hands-On: Markdown

Erstellen Sie eine neue Wiki Page (mit ihrem Namen). Probieren Sie Markdown aus → Überschrift, Liste und eine Code Snippet (memo.xml).

39 of 52

5. Block

39

45 min Recap, Wiederholung, Anhang

​

​

​

40 of 52

Zusammenfassung

​

​

​

​

​

​

​

​

​

​

​

​

​

​

​

Lokaler Rechner

Staging

Working Directory

Commit History

memo.xml

git add memo.xml

git commit

Commit

Commit

Commit

git push

git pull

git pull

Remote-Server

git clone

mit einer Message

41 of 52

Branches

Commit�Update cheatsheet.md

Commit�adding xml_snippet.xml

Commit�Update cheatsheet.md

Commit�add schoenberg edition example

00dd9f48fe57728084791bb636962837f64009b6

b77361c6662a88f3d9ffb6c9932a5a114eb15300

35433b1736f1050b086a243a85f1890d5e57a1ed

34301044aeabc74273e367cfb71ed57e6fff9ad1

main

42 of 52

Branches

https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell

43 of 52

Branches und Pull request

  • 3 <bibl> in einer Datei im teiHeader branch hinzugefügt
  • 1 fehlendes <p> im teiBody branch
  • merge pull request 1 → 3 <bibl> aus teiHeader branch nach main
  • merge pull request 2 → 1 <p> aus teiBody branch nach main

​

https://github.com/KlassikStiftungWeimar/Test-Training-Repo/pulls

44 of 52

Hands-On: eigener Branch

Erzeugen Sie einen neuen Branch mit Ihrem Namen (z.B.: “christopher”).

Nehmen Sie eine Änderung im XML/TEI vor: https://github.com/KlassikStiftungWeimar/Test-Training-Repo/tree/main/digital_edition_schoenberg_example/sample_letter

Committen Sie “lustig drauflos”, damit jede/r einen Konflikt bekommt, den wir dann bereinigen (oder auch nicht) bereinigen können.

45 of 52

Merge Conflicts

46 of 52

Merge Conflicts

47 of 52

“Branching Strategies”

Mainline Development

  • Immer integrierend sein → achten Sie darauf, dass Sie Ihre Inhalte gut, zügig und ordentlich mit der Arbeit Ihrer Kolleginnen/Kollegen zusammenführen.
  • Wenig Branches
  • Kleine Commits

State, Releases, and Feature Branches

​

Git for Professionals Tutorial - Tools & Concepts for Mastering Version Control with Git, https://www.youtube.com/watch?v=Uszj_k0DGsg

48 of 52

Kritik an Git

​

Blogpost:

https://hadihariri.com/2020/10/14/a-few-words-on-git/

​

49 of 52

Dinge, die wir nicht besprochen haben…

  • $ git init�Um einen lokalen Ordner zu einem Git Repository zu machen.�
  • Fork a repo�Eine eigene Kopie eines existierenden Repos, um es selbst weiter zu bearbeiten. �
  • GitHub Actions�
  • weitere Tools (z.B. GitKraken)

​

50 of 52

Git bzw. GitHub installieren

Distribution Ubuntu � Paketverwaltungstool: apt � $ apt-get install git��macOS� Xcode Kommandozeilen-Tools � $ git --version

Windows� Binärer Installationsassistent, https://git-scm.com/download/win��Oder GitHub Desktop https://desktop.github.com/ ���

51 of 52

51

www.dhcraft.org

Christopher Pollin

Geschichte, EuroMACHS, Doktorat DH

​

​

​

52 of 52

52

Christian Steiner

Translation (EN/BKS), EuroMACHS, Doktorat DH

Christopher Pollin

Geschichte, EuroMACHS, Doktorat DH