📤 Quick guide to Git

Achtung

Die folgenden Beschreibungen richten sich in erster Linie an die Betreuenden des P1/P2-Praktikums. Normalen Kursteilnehmenden fehlen im Allgemeinen die Berechtigungen zu einigen Vorgängen in diesem Abschnitt.

🌱 Grundlagen

Git ist ein Code-Verwaltungssystem mit dem Sie Code dezentral bearbeiten und immer auf dem neuesten Stand halten können. Der Code wird in sog. Repositories (auf Deutsch Ablagen oder Depots) verwaltet. Die Hauptablage, das main Repository, befindet sich in unserem Fall auf dem SCC Gitlab-Server. Sie können sich beliebig viele lokale Kopien dieser Hauptablage (oder anderer Ablagen) einrichten und bearbeiten. Diese Kopien bezeichnet man auch als Clone.

Wir statten Sie hier mit dem minimalen Rüstzeug aus, dass Sie benötigen, um auf dem bwJupyter Hub die folgenden Vorgänge mit Git durchführen zu können:

Clone von einem nicht-öffentlichen main Repository in Ihre lokale Arbeitsumgebung auf dem bwJupyter Hub einrichten.
Ihren lokalen Clone auf dem bwJupyter Hub verwalten.
Änderungen, die Sie lokal verwaltet haben ins main Repository zurückführen.

Mehr Kenntnisse über Git, als wir sie Ihnen hier vermitteln werden Sie im P1/P2-Praktikum i.a. nicht benötigen.

Sie können Git grundsätzlich leicht und mit wenigen Befehlen aus dem Terminal bedienen. Auf dem bwJupyter Hub gibt es zusätzlich eine gegenüber dem Terminal leicht eingeschränkte graphische Benutzeroberfläche, die Sie verwenden können. Wir werden Ihnen beide Varianten vorstellen.

Einige Beispielbilder wurden für das Masterprotokoll des P2-Versuchs H15 Spezifische Wärmekapazität im WS23/24 erstellt.

📥 Clone aus main

Wie Sie ein main Repository vom SCC Gitlab-Server in Ihre Arbeitsumgebung des bwJupyter Hub clonen können haben wir, am Beispiel des öffentlichen students Repository im Teilabschnitt ➡️ Download aus gitlab beschrieben. Der Download erfolgt in diesem Fall anonym (über den HTTPS-Link) und ist nur lesend. Um einen lokalen Clone für das nicht-öffentliche tutors Repository anlegen zu können müssen Sie sich auf dem SCC Gitlab-Server als leseberechtigt authentifizieren. Dies erreichen Sie am einfachsten indem Sie den Clone für das Repository unter SSH-Verschlüsselung anlegen.

Hinweis

Jede Art von Verschlüsselung basiert auf einem (privaten) "Schlüssel", über den nur Sie verfügen und ein öffentliches "Schloss".

Wir beschreiben Ihnen im Folgenden, wie Sie sich einen SSH Key verschaffen und diesen auf dem SCC Gitlab-Server hinterlegen. Diesen Vorgang müssen Sie nur einmal durchführen, bevor Sie das erste mal einen Clone für das gewünschte Repository anlegen.

Alternativ sollte es immer noch möglich sein einen Clone für ein nicht-öffentliches Repository über den HTTPS-Link zu erstellen. In diesem Fall müssen Sie bereits beim Download und auch für jede spätere Kommunikation mit dem SCC Gitlab-Server Ihren Account und Ihr Passwort eingeben. Die Git-Entwickler haben vor einiger Zeit jedoch angekündigt die Unterstützung für diese Art des Zugangs zu einem nicht-öffentlichen Respository auslaufen zu lassen. Für diese Art einen Clone zu erstellen übernehmen wir also keine Gewähr.

Erzeugen des SSH Schlüssels

Um einen lokalen Clone für das tutors Repository in Ihrer Arbeitsumgebung des SCC Gitlab-Servers anlegen zu können benötigen Sie einen SSH Key, den Sie unter Ihrem Account auf dem SCC Gitlab-Server einmalig zur Authentifizierung hinterlegen müssen.

Falls Sie noch nicht über einen solchen SSH Key verfügen gehen Sie zu dessen Erzeugung auf dem bwJupyter Hub, wie folgt vor:

Öffnen Sie ein Terminal.
Wechseln Sie im Terminal mit cd ins Verzeichnis ~/.ssh/, wie im folgenden gezeigt:

USER@jupyter-USER:~$ cd ~/.ssh/

Falls Sie (noch) kein solches Verzeichnis im Wurzelverzeichnis Ihrer Arbeitsumgebung haben sollten, können Sie es mit Hilfe des Befehls mkdir wie folgt dort anlegen:

USER@jupyter-USER:~/ cd
USER@jupyter-USER:~/ mkdir .ssh
USER@jupyter-USER:/ cd .ssh/

Erzeugen Sie dort einen SSH Key mit Hilfe des Programms ssh-keygen, wie im Folgenden gezeigt:

USER@jupyter-USER:~/.ssh$ ssh-keygen -b 2048 -t rsa

Sie werden nach Ausführung um einige optionale Angaben gebeten, die Sie alle mit der Enter-Taste überspringen können.

Nach diesen Schritten sollte Ihr .ssh-Verzeichnis wie folgt aussehen:

USER@jupyter-USER:~/.ssh$ ls
id_rsa  id_rsa.pub  known_hosts

In der Datei id_rsa.pub befindet sich der SSH Key zu Ihrem Account auf dem bwJupyter Hub.
Sie können den Inhalt der Datei id_rsa.pub z.B. mit dem Befehl less, wie im Folgenden gezeigt, im Terminal des Jupyter-Servers ausgeben lassen und ansehen:

USER@jupyter-USER:~/.ssh$ less id_rsa.pub

Hinterlegen des SSH Schlüssels

Um einen SSH Key auf dem SSC Gitlab-Server zu hinterlegen gehen Sie wie folgt vor:

Öffnen Sie in einem anderen Reiter Ihres Browsers den SCC Gitlab-Server.
Wechseln Sie auf Ihr Profil, z.B. über den Link oben rechts, im linken Teilfenster, wie in Abb. 1 gezeigt. Gehen Sie dazu über den Menüpunkt Edit profile:

Abb. 1: Der Weg zu Ihrem Profil auf dem SCC Gitlab-Server

Ihr Browser-Fenster sollte daraufhin in etwa, wie in Abb. 2 gezeigt, aussehen:

**Abb. 2:** Ihr Profil auf dem SCC Gitlab-Server

An achter Stelle von oben im linken Teilfenster finden Sie den Menüpunkt SSH Keys, den Sie anklicken sollten. Sie sollten damit auf eine Oberfläche, wie in Abb. 3 gezeigt, geführt werden:

**Abb. 3:** Hinterlegen eines *SSH Schlüssels* auf den Gitlab-Server des SCC

Klicken Sie auf die Schaltfläche Add new key (oben rechts in Abb. 3). Sie sollten damit auf eine Oberfläche, wie in Abb. 4 gezeigt, geführt werden:

**Abb. 4:** Hinterlegen eines *SSH Schlüssels* auf den Gitlab-Server des SCC

Fügen Sie per copy & paste den SSH Key aus der Datei id_rsa.pub aus dem .ssh-Verzeichnis Ihrer Arbeitsumgebung auf dem bwJupyter Hub in das Feld Key ein.
Sie können das Ablaufdatum (Expiration-date im Abb. 4) für diesen SSH Key löschen. Löschen Sie es nicht läuft der Key zum eingestellten Datum aus und muss neu angelegt werden.
Klicken Sie zum Abschluss des Vorgangs auf die Schaltfläche Add key (unten halb-links im Bild).

Diesen Vorgang müssen Sie nur einmal durchführen und zwar bevor Sie zum ersten mal einen Clone für ein Repository vom SCC Gitlab-Server mit SSH Key erzeugen wollen.

Clone aus main

Hinweis

Den Clone für das main Repository erzeugen Sie, wie im Teilabschnitt ➡️ Download aus gitlab beschrieben, mit einem entscheidenden Unterschied:

Verwenden Sie statt der Option Clone with HTTPS die Option Clone with SSH.

Alternativ können Sie im Verzeichnis Ihrer Wahl in einem Terminal den Befehl

git clone git@gitlab.kit.edu:kit/etp-lehre/p1-praktikum/tutors.git

verwenden (hier am Beispiel des tutors Repository fürs P1/P2-Praktikum).

💾 Verwaltung des Clones

Die nächsten Schritte dieser Einführung setzen voraus, dass Sie das Repository Ihrer Wahl bereits als lokalen Clone in der Arbeitsumgebung des bwJupyter Hub vorliegen haben.

Alle Dateien, die Sie in Ihre lokale Arbeitsumgebung geladen haben können Sie beliebig bearbeiten. Wenn Sie solche Änderungen in die Verwaltung für Ihren Clone aufnehmen möchten benötigen Sie im Terminal v.a. die folgenden vier Befehle:

git status: Im Terminal lohnt es sich immer, bevor man irgendwelche Änderungen am lokalen Repository vornehmen möchte dessen Status zu überprüfen. Sie tun dies am besten im Verzeichnis, in dem Sie die Änderungen vornehmen wollen mit dem Befehl git status. Es handelt sich um einen rein passiven Befehl, der nichts in Ihrem lokalen Repository verändert. Als Ausgabe im Terminal erhalten Sie u.a. die folgenden wertvollen Informationen:
- Welche Dateien haben Sie in der Zwischenzeit zur Verwaltung in Ihrem Repository angemeldet?
- Welche Dateien haben Sie aus der Verwaltung ausgetragen oder verändert?
- Welche Dateien befinden sich im Verzeichnis, die Sie (noch) nicht in die Verwaltung des Repository aufgenommen haben. Diese werden als untracked bezeichnet.
git add Test.ipynb: Falls Sie eine Datei, wie z.B. Test.ipynb neu erzeugt haben und in die Verwaltung für Ihr lokales Repository aufnehmen möchten, müssen Sie diesen Vorgang dort erst "anmelden". Sie tun dies am besten im Verzeichnis, in dem Sie die Datei zufügen wollen mit dem Befehl git add … gefolgt vom (vollständigen) Namen der Datei. Dateien dürfen sich auch in Unterverzeichnissen befinden, das ist kein Problem.
git rm Test.ipynb: Falls Sie (versehentlich) eine Datei aus Ihrem Verzeichnis entfernt haben, die sich unter der Verwaltung Ihres lokalen Repository befindet, stellt Git dies fest und bietet Ihnen die Möglichkeit diese Datei aus Ihrem lokalen Repository wieder herzustellen. Manchmal möchten Sie eine Datei jedoch bewusst löschen und aus der Verwaltung durch Ihr lokales Repository austragen. Dies tun Sie mit dem Befehl git rm … gefolgt vom vollständigen Namen der zu löschenden Datei. Beachten Sie dabei, dass Sie die Datei mit dem Befehl git rm … aktiv löschen. Mit einer bereits gelöschten Datei ist der Austrag aus dem Repository nicht möglich. In einem solchen Fall müssen Sie die gelöschte Datei erst wieder herstellen, um Sie danach ordnungsgemäß aus dem Repository löschen und gleichzeitig austragen zu können.
git commit -m "Mein erster commit" Test.ipynb: Wenn Sie eine Datei, wie z.B. Test.ipynb verändert haben zeigen Sie diese Veränderung mit dem Befehl git commit … gefolgt vom vollständigen Namen der Datei an. Im obigen Beispiel verwenden wir zusätzlich die Option -m "..." mit der Sie diesen Schritt zusätzlich mit einem beliebigen Kommentar versehen können. Es ist gute Praxis von dieser Option Gebrauch zu machen. Das englische Verb to commit bedeutet im Deutschen sich engagieren oder sich verpflichten. Mit dem Befehl git commit … melden Sie eine Änderung in Ihrem lokalen Repository zur Verwaltung an, die daraufhin "verpflichtend" angenommen wird. Beachten Sie, dass Sie alles was in der Verwaltung für Ihr lokales Repository geschehen soll auf diese Weise nochmal "verpflichtend anmelden" müssen, auch wenn Sie eine Datei mit git add … zugefügt, oder mit git rm … gelöscht haben müssen Sie dies durch den Befehl git commit … nochmals bestätigen und die entsprechende Änderung im Repository auf diese Weise "verpflichtend" anmelden.

Einen typischer Verlauf im Terminal ist in Abb. 5 gezeigt:

Wenn Sie die Git-Benutzeroberfläche des Jupyter-Servers verwenden möchten gehen Sie wie folgt vor:

git add/rm Test.ipynb: Klicken Sie --in der Verzeichnisstruktur(!)-- im linken Teilfenster der Arbeitsumgebung die Datei, die Sie zufügen wollen mit der rechten Maustaste an und wählen Sie den Menüpunkt Git -> + Add aus, wie in Abb. 6 gezeigt. Wenn Sie eine bereits in der Verwaltung befindliche Datei aus der Verwaltung austragen und löschen möchten wählen Sie den Menüpunkt Delete aus.

**Abb. 6:** Zufügen oder Entfernen einer Datei aus der Git-Verwaltung über die graphische Oberfläche des Jupyter-Servers

git commit Test.ipynb: Um eine Änderung jedweder Art "verbindlich" anzumelden wählen Sie in der äußerst linken Leiste der Arbeitsumgebung das git commit-Symbol aus, wie in Abb. 7 gezeigt. (Es handelt sich um das dritte Symbol von unten in Form einer Raute.) Auf diese Weise wechseln Sie von der Dateistruktur zur Git-Benutzeroberfläche:

**Abb. 7:** Wechseln auf die Git-Benutzeroberfläche auf dem Jupyter-Server

Im linken Teilfenster der Arbeitsumgebung werden Ihnen nun alle Unterschiede im Vergleich zu Ihrem lokalen Repository angezeigt. Sie sehen im obigen Bild, dass in diesem Beispiel die Datei Warmekapazitaet_Betreuerprotokoll_Braun_Buchner_final.ipynb mit einem Häkchen versehen ist, d.h. diese Datei ist für eine verbindliche Änderung im Repository angemeldet worden. Die Häkchen können Sie frei setzen. Sie können den commit daraufhin im unteren Teil des Fensters für alle mit einem Häkchen versehenen Dateien durchführen. Ein Ausschnitt mit dem unteren Teilfenster der Git-Benutzeroberfläche des bwJupyter Hub ist in Abb. 8 gezeigt:

**Abb. 8:** Ein *commit* eines oder mehrerer Dateien über die Benutzeroberfläche des Jupyter-Servers

Geben Sie hierzu einen kurzen Kommentar an (der in diesem Fall verbindlich ist) und drücken Sie den blauen COMMIT Knopf.

📤 Upload ins main Repository

Um Ihre lokal verwalteten Änderungen ins main Repository zu überspielen benötigen Sie im Terminal die folgenden zwei Befehle:

git pull: Mit diesem Befehl "ziehen" Sie nochmal alle Neuerungen, die von anderer Stelle ins main Repository eingebracht worden sein könnten in Ihren lokalen Clone. Sie bringen damit Ihren Clone auf den "neuesten Stand". Änderungen von dritter Stelle werden dabei vom System mit Ihren Änderungen zusammengefügt. Diesen Vorgang bezeichnet man auch als merge. Von Ihren lokal verwalteten Änderungen geht nichts verloren! Kommt es bei einem merge zu Konflikten, d.h. haben sowohl Sie, als auch eine dritte Partei verschiedene Änderungen an der gleichen Stelle in einer Datei vorgenommen, müssen Sie diese von Hand auflösen. Dies sollte jedoch, so wie wir Git im P1/P2-Praktikum gebrauchen äußerst selten der Fall sein.
git push: Mit diesem Befehl "schieben" Sie Ihre Änderungen von Ihrem Clone ins main Repository auf dem SCC gitlab-Server. Kurze Zeit später sollten Sie Ihre Änderungen im Webinterface des SCC gitlab-Servers wiederfinden können. Sie sind nun Bestandteil des main Repositories.

Beachten Sie, dass Sie nur dann einen pull- oder push-Befehl erfolgreich ausführen können, wenn sich Ihr Clone in einem wohldefinierten Zustand befindet, d.h. wenn Sie all Ihre beabsichtigten Änderungen mit git commit … verbindlich gemacht haben. Ein typischer Verlauf im Terminal ist in Abb. 9 gezeigt:

**Abb. 9:** Eine typische Sequenz von *pull*- und *push*-Befehlen zum *Upload* von Änderungen des *Clones* ins *main Repository*

Auf der Git-Benutzeroberfläche des bwJupyter Hub drücken Sie auf die mit den Wölkchen markierten Symbole am oberen rechten Rand des entsprechenden Teilfensters. Das linke Wölkchen steht für pull und das rechte für push.

🙄 Probleme?

Bei Problemen mit oder weiteren Fragen zu Git melden Sie sich gerne bei der Praktikumsleitung. Wir helfen Ihnen gern weiter.