Git

Git ist ein Versionsverwaltungssystem. Es wird verwendet um

• Änderungen am Projekt zu protokollieren und dieses zu archivieren.
• Ältere Versionen wiederherzustellen.
• Gemeinsames Arbeiten auf der selben Datenbasis zu ermöglichen.

Wir verwenden Git im Sopra um genau diese Punkte zu ermöglichen. Jede Gruppe erhält ihr eigenes Repository auf Gitea (einer Plattform ähnlich zu GitHub), um ihr Projekt zu verwalten.

Git in einer Nussschale

Um mit Git arbeiten zu können, ist es wichtig die Prinzipielle Arbeitsweise von Git zu verstehen. Hat man die technische Umsetzung im Hinterkopf, werden die Befehle und Arbeitsweisen um git zu bedienen klarer.

Git protokolliert und verwaltet ein Dateiverzeichnis und alle Änderungen die an den verwalteten Dateien gemacht werden. Jede Änderung produziert dabei einen neuen "Schnappschuß" (Commit) - den aktuellen Zustand des Verzeichnisses und der Dateien denen ein HASH (SHA-1) zugeordnet wird. Jeder Schnappschuss kennt seine Vorgänger, so dass mit der Zeit ein großer gerichteter azyklischer Graph entsteht. Git kümmert sich darum, dass dies speichereffizient abläuft und verwendet dazu ein speziellen Verzeichniss das .git heißt und in dem verwalteten Dateiverzeichnis liegt. Dieses die gesammte Historie beinhaltende .git Verzeichnis ist ein Git Repository. Meistens wird aber das verwaltete Verzeichnis synonym als Repository bezeichnet, was wir ab jetzt auch tun. Ein einfaches Repository mit nur einer Datei "README.md" sieht demnach so aus:

.
├── .git
└── README.md

Die gesammte Historie des Repository ist also (meistens) lokal vorhanden. Um mit mehreren Personen an dem Repository zu arbeiten, müssen die Teilnehmer es mit einem "remote" Repository synchronisieren.

Git arbeitet mit 3 Zuständen. Jede versionierte Datei kann in einem der Zustände sein wobei es nicht sein muss, dass zu einem Zeitpunkt alle Dateien den gleichen Zustand haben. Die 3 Zustände sind:

• committed -> Die Datei ist so wie sie ist im repository gespeichert.
• modified -> Die Datei ist zum letzten gespeicherten Zustand verändert.
• staged -> Die Datei (vorher im "Modified" Zustand oder eine neue Datei) wurde von dem git Benutzer markiert, sodass die Änderungen gespeichert werden sollen.

Daneben gibt es auch noch `untracked files` dies sind Dateien, die noch nicht in die Versionskontrolle aufgenommen wurden.

Zentrale Begriffe

Commit

Ein Commit repräsentiert einen Schnappschuss des Reposity - den Zustand aller Dateien - zusammen mit einer Commitnachricht und Informationen über den Author (Name und Email Adresse). Ändert ein Nutzer eine oder mehrere Dateien kann der Nutzer diese Änderungen mit einem neuen Commit festhalten. Jedes mal wenn der git commit Befehl ausgeführt wird, speichert Git den aktuellen Zustand und weist ihm eine eindeutige ID (dem SHA-1 Hash) zu. Eine Serie an Commits erzeugt eine verkettete Liste an Commits wobei ein Commit immer seinen Vorgänger kennt. Benutzt man auch Branches im Repository, entsteht so ein gerichteter Graph.

Branch

Ein Branch ist ein unabhängiger Abzweig des Repository. Ausgehend von einem Commit kann mittels des git branch befehls ein neuer Branch erzeugt werden. Ein branch funktioniert wie ein eigenes Repository mit der Besonderheit, dass der Branch ausgehend von einem Commit (Schnappschuss) des Repository erstellt wurde - technisch ist ein Branch einfach ein Pointer auf einen Commit - und mit anderen Branches des Repository wieder vereinigt werden kann (Merge). Es können praktisch beliebig viele Branches existieren und diese können beliebig stark voneinander abweichen.

Master-Branch

Der Master-Branch ist der erste Branch der standardmäßig von Git erzeugt wird. Lässt man alle Branch Befehle unberührt, spielt sich also jede Änderung am Repository nur auf dem Master-Branch ab.

Merge

Ein Merge ist das einfügen von Änderungen aus einem fremden (Source-) Branch in den Aktuellen (Target-) Branch.

Merge-Konflikt

Ein Merge-Konflikt entsteht wenn im Source- und Target-Branch Änderungen an der selben Datei vorhanden sind, die nicht von git aufgelöst werden können und manuelles beseitigen des Konfliktes erfordern.

Clone

Ein Clone ist eine Kopie eines schon bestehenden Git Repository. Dabei möchte man meistens die Quelle als Remote behalten um Änderungen mit dieser Synchronisieren zu können.

Remote

Remote ist die Bezeichnung für ein Repository, das zur synchronisierung verwendet wird. Meistens ist dies auf einem externen Server und benötigt eine Authentifizierungsmethode um von diesem Änderungen zu holen (fetch) oder Änderungen hochzuladen (push). Im SOPRA verwendet jede Gruppe dazu ein eigenes auf SOPRA Gitea gehostetes repository.

HEAD

HEAD ist ein Zeiger auf einen Commit. Git markiert den aktuellen (letzten) Commit in einem Branch als "HEAD". Der HEAD beschreibt also den aktuellen Zustand des Repository im jeweiligen Branch. Faktisch gibt es also bei mehreren Branches mehrere HEAD Commits. Praktisch zeigt HEAD aber zu jedem Zeitpunkt eindeutig auf einen Commit, da ein Checkout auf einen Branch auch immer eindeutig ist. Wird von "HEAD des dev Branch" gesprochen, meint dies den Commit auf den HEAD zeigt, wenn der dev Branch ausgecheckt wäre. Um die jeweils aktuellen Zustände der Branches zu sehen, kann der git log Befehl mit dem --decorate verwendet werden:

git log --decorate --oneline --graph
*   c311082 (HEAD, master) Merge dev "foo bar"
|\
| * 1c34c42 (develop) Implemented Implement bar
| * 238fb57 (develop) Implemented Implement foo
|/
* 5d992aa (origin/master, origin/develop) Init

In Klammern sieht man jeweils den letzten Zustand des entsprechenden Branches. Ausserdem (HEAD, master) lässt erkennen, dass der aktive Branch "master" ist und der Commit mit der kurz-ID "c311082" in diesem der aktuelle Commit.

Arbeiten mit Git

Wir beschreiben hier kurz und sehr abstrakt die einzelnen Funktionen, die ein Git-Client generell zur Verfügung stellt. Wie die Befehle in einzelnen GUI Programmen implementiert sind ist unterschiedlich.

Name und Email einstellen

Jeder commit wird mit Namen und Email versehen. Diese muss man (entweder per repository oder global) einstellen.

git config --global user.email "jane.doe@example.com"
git config --global user.name "Jane Doe"

Seiten wie GitHub oder auch das SoPra Gitea verwenden die Emailadresse um den Commit einem Benutzer zuzuordnen, die eingestellten Emailadressen sollte also übereinstimmen.

Repository erstellen

Um einen Ordner unter Git Versionskontrolle zu stellen fürht man im entsprechenden Ordner den init Befehl aus:

git init

Git antwortet darauf mit

Initialized empty Git repository in <pfad zum ordner>/.git/

Repository clonen

Um ein bestehendes Repository in einen Ordner zu Clonen benutzt man den clone Befehl:

git clone https://sopragit.informatik.uni-freiburg.de/<semester>/<gruppe>.git

Bzw. für die Authentifizierung mit SSH ist der äquivalente Befehl

git clone gitea@sopragit.informatik.uni-freiburg.de:<gruppe>/<gruppe>.git

Der Befehl clone legt eine exakte Kopie der gesamten Repositorydaten auf der lokalen Maschine ab.

TODO lokaler Branch und remote pointer

Am Repository Arbeiten

Im Folgenden zeigen wir die Grundlegenden Handgriffe, die zur Benutzung von Git notwendig sind. Um tiefer in die Materie einzutauchen empfehlen wir gibt es im Git Pro Book.

Neue Datei

Eine neue Datei ist zunächst untracked. Um die Datei comitten zu können muss sie erst in den Staging Zustand gebracht werden

git add <datei>

Jetzt können die Dateien committet werden:

git commit -m "Added <datei>"

Änderungen an einer Datei

Gibt es Änderungen an einer Datei befindet sich diese im modified Zustand. Dies sieht man mittels git status. Die jeweiligen änderungen können mit git diff <datei> angezeigt werden.

Änderungen an einzlenen Dateien können direkt comitted werden:

git commit <datei_1> <datei_2> -m "Fix gun sound delay."

Um alle Dateien im die sich im Staging Zustand befinden (also solche die mit git add als im Staging Zustand markiert wurden) können auch comitted werden. Dateien die geändert wurden müssen auch mit git add gestaged werden.

git commit -m "My changes regarding that thing."

Remote Änderungen synchronisieren

Änderungen die im remote Repository gemacht wurden könen mit

git fetch

in das lokale Repository geladen werden. Achtung: git fetch mergt die Änderungen der lokalen branches nicht automatisch in die aktualisierten remote Branches. Ein manueller Merge kann nun mit git merge <remote/branch> <branch> ausgeführt werden.

Ist der aktuelle Branch ein einfacher Klon des Remotebranch ohne eigene Spezielle einstellungen, wird automatisch der local Branch den remote branch tracken. Damit kann einfacher der pull Befehl verwendet werden

git pull

der automatisch die Änderungen in den lokalen Branch merged. Siehe auch die Dokumentation dazu. Um unschöne merges zu vermeiden kann dem Befehl auch ein --rebase angehängt werden. Anstatt einen neuen Commit zu erstellen, in dem der lokale und der remote branch gemergt werden, und diesen dann zu Comitten, werden alle Änderungen die am lokalen Branch gemacht wurden an den remote Branch angehängt, als wären sie erst nach dem fetch entstanden.

Änderungen in das remote Repository laden (pushen)

Sind eigene Änderungen (Commits) vorhanden, was mit dem git status Befehl überprüft werden kann. Beispielsweise

$ git status
On branch develop
Your branch is ahead of 'origin/develop' by 1 commit.
  (use "git push" to publish your local commits)

Zeigt an, dass 1 lokaler Commit noch nicht veröffentlicht wurde. Um den Commit in das remote Repository zu laden wird der push befehl verwendet:

git push

Es kann passieren, dass git push mit einer Fehlermeldung abbricht, die bessagt, dass es Änderungen auf dem remote Branch gibt, die es auf der lokalen kopie nocht nicht gibt. In diesem Fall müssen zuerst die Änderungen von remote geladen werden.

To <remote url>
! [rejected]        dev -> dev (fetch first)
error: failed to push some refs to '<remote url>'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.

Änderungen Rückgängig machen

Wichtig ist zu unterscheiden, ob Änderungen gemacht werden sollen an Dingen, die bereits remote vorhanden sind oder nur local (also noch nicht synchronisiert). Im ersten Fall sollte die Änderung immer durch einen Neuen Commit erfolgen. Im letzteren Fall können auch brachialere Methoden angewendet werden, die Commits tatsächlich löschen.

Commit nachricht ändern

Falls noch nicht mit dem remote synchronisiert, kann mit dem Befehl

git commit --amend

Der commit geändert werden.

Dateien löschen

Versionierte Dateien lassen sich durch den rm Befehl entfernen.

git rm <datei>

Dieser Befehl löscht die Datei und fügt die Löschung zur Stage hinzu, so dass sie comittet werden kann.

Dateien Ignorieren

Man kann in Git mittels einer .gitignore Datei andere Dateien ignorieren, d.h. sie explizit nicht unter Versionskontrolle stellen. Das ist insbesondere für temporäre Dateien (die z.B. bei jedem Build neu erzeugt werden) oder Benutzer-spezifische Einstellungen sinnvoll und muss von jedem verwendet werden. Die folgenden Dateien und Verzeichnisse müssen auf jedenfall auf die Ignore-Datei und dürfen nicht mit eingecheckt werden:

	Warum?
bin	Die Dateien in diesem Ordner werden automatisch beim Kompillieren erstellt, sie hochzuladen ist also unnötig. Zudem sind auch binäre Dateien dabei die sich beim kompilieren häufig ändern. Da binäre Dateien nicht gemerged werden können wird das zu häufigen Konflikten mit den Commits anderer Teammitglieder führen.
obj	Siehe bin.
_ReSharper.#PROJEKTNAME#	Dieses Verzeichnis wird vom Resharper automatisch generiert. Automatisch generierte Ordner sollen nicht ins SVN, siehe bin.
*.suo	Die Dateien mit der Endung .suo (Solution User Options) beinhalten eine Reihe von Benutzer-spezifischen Einstellungen für Visual Studio, die niemanden außer den Benutzer selber interessieren. Sie enthalten außerdem eine Reihe von absoluten Pfadangaben, die bei anderen Benutzern massive Probleme auslösen können. Sie sollen auf keinen Fall zum Repository hinzugefügt werden.
*.cachefile	Siehe bin. Auch merkt sich MonoGame hier, welche Dateien es schon in ein ihm genehmes Format konvertiert hat. Wenn ein anderes Teammitglied eine neue Datei hinzufügt und diese Datei im .cachefile als bereits konvertiert markiert ist, kann es passieren daß sich XNA denkt "Hey die Datei hab ich doch schon" und sie nicht neu konvertiert.
*.DotSettings.user	Diese Datei enthält Benutzerspezifische Resharper Einstellungen und soll entsprechend auch nicht eingecheckt werden.
*.thumb	Von Windows generierte Datei, die Vorschaubilder für die Miniaturansicht im Explorer enthält.
thumbs.db	Siehe .thumb
.vs	Von Visual Studio generiertes Verzeichnis für interne Einstellungen.

Mit mehreren Branches arbeiten

Im SOPRA verwenden wir hauptsächlich 2 Branches (siehe Git Workflow im Sopra).

• master => Hier ist der aktuelle Stand des Projekts in Lauffähigem Zustand mit fertig implementierten Tasks. Dieser Branch ist Grundlage für die Bewertung des Spiels und Abgabe von Artifakten und muss zu jeder Zeit ein compilier und lauffähiges Spiel darstellen.
• develop => Hier werden die Tasks entwickelt. Sie müssen nicht zwangsläufig fertig sein, aber der develop Branch soll zu jeder Zeit kompillieren und laufen.
• feature/<task> => Feature branches können als Erweiterung des develop Branches gesehen werden. Hier wird ein einzelner Task implementiert bis er fertig ist und in den develop Branch gemerged wird.

Wichtige branch Befehle

git status                    # Zeigt neben dem aktuellen Zustand des Repos auch auf welchem Branch man gerade ist.
git branch -v                 # Zeigt verfügbare Branches mit aktuellem HEAD.
git checkout <branch_name>    # Wechselt den branch nach <branch_name>.
git branch <branch_name>      # Erstellt einen neuen Branch <branch_name>.
git checkout -b <branch_name> # Erstellt <branch_name> und wechselt in diesen falls er noch nicht existiert.
git branch -d <branch_name>   # Löscht den <branch_name> Branch.

Branch mergen

Möchte man einen feature Branch nach develop mergen, wechselt man zunächst in den develop branch

git checkout develop

Jetzt merged man den feature branch mit

git merge feature/<task>

Je nach Zustand des Repository gibt es nun mehrere Szenarios was passiert:

• Fast-forward Merge Falls man den aktuellen HEAD des develop Branch durch einfaches zurücklaufen in der History des feature/<task> Branch erreichen kann, sind offensichtlich Konflikte ausgeschlossen und Git kann einfach den HEAD von develop auf den HEAD des feautre/<task> Branches zeigen lassen. Effektiv wird also alles was in feature/<brach> seit dem erstellen des feature/<brach> passiert ist auch in develop passieren.
• Recursive merge Falls in der Zwischenzeit der develop Branch weiterentwickelt wurde, ist ein Fast-forward Merge nicht mehr möglich. Falls es aber keine Dateien gibt, die in jetzt unterschiedliche Inhalte haben, wird bei einem recursive merge ein neuer Commit erstellt, der die Vereinigung der Änderungen beider Branches darstellt. Git fordert den Nutzer in diesem Fall auf eine Commit Nachricht anzugeben. In der Regel Sollte diese dann lauten: "Merge feature/<task> Evtl zusätzliche info oder Zusammenfassung für neues feature."
• Merge Konflikt Falls in beiden Branches Änderungen an gleichen Inhalten gemacht wurden, weiß Git nicht wie diese aufzulösen sind. Wie man Merge Konflikte löst ist in Konflikte lösen beschrieben.
• Weitere möglichkeiten zu mergen werden hier beschrieben: https://git-scm.com/docs/merge-strategies

Konflikte lösen

Kann ein merge Befehl wegen einem Konflikt nicht ausgeführt werden meldet sich git so

Automatic merge failed; fix conflicts and then commit the result.

Die betroffenen Dateien kann man sich mit git status anzeigen lassen. Eine Ausgabe kann dan so aussehen:

On branch develop
You have unmerged paths.
  (fix conflicts and run "git commit")

Unmerged paths:
  (use "git add <file>..." to mark resolution)

        both modified:   README.md

In diesem Fall ist die Datei README.md in beiden Branches bearbeitet worden und Git weis nicht wie diese Datei nach dem merge aussehen soll. Öffnet man diese Datei jetzt, kann der Inhalt beispielsweise so Aussehen:

<<<<<<< HEAD
# Setup
=======
# Installation
>>>>>>> feature/foo
1. Turn PC on.

Hier makiert alles zwischen <<<<<<< HEAD und ======= (In diesem Fall also # Setup) den vom Konflikt betroffenen Bereich im aktuellen develop Zustand. Ab ======= bis >>>>>>> feature/foo (In diesem Fall also # Installation) Den vom Konflikt betroffenen Bereich im feature/foo Branch. Alle diese Bereiche (es kann mehrere geben) müssen nun manuell aufgelöst werden. Dabei ist es wichtig auch die Git Markierungen zu entfernen. Eine Lösung könnte also sein:

# Setup
1. Turn PC on.

Hat man die Konflikte einer Datei behoben, gibt man der Dateu den "staged" Zustand (git add <datei>). Ist man mit allen Konflikten fertig, macht man einen Commit, dessen Nachricht in der Regel etwa lautet: "Merge feature/foo Evtl zusätzliche info oder Zusammenfassung für neues feature"

Das rein manuelle lösen von Konflikten kann sehr Zeit intensiv und umständlich sein. Desshalb gibt es eine Reihe von Tools die helfen. Git arbeitet mit einer Reihe davon zusammen und man startet diese mit

git mergetool

Hat man die Konflikte in dem Tool behoben, fügt Git die Dateien automatisch zur Stage hinzu, so dass man nur noch den merge Commit machen muss.

Git Installieren

Es gibt unzählige Git Clients. Empfehlenswert ist vor allem für den Einstieg Der offizielle Git client. Wer gerne ein graphisches Interface hat kann tortoisegit oder einen der zahlreichen Alternativen verwenden.

Git für das SOPRA vorbereiten

Nachdem Sie sich für einen Git-Client entschieden haben müssen Sie sicherstellen:

• Dass ihr Zugang zu Gitea funktioniert.
• Das Repository Ihrer Gruppe auf ihren Rechner clonen.
• Ihren Namen und die Email Adresse Git mitteilen.
• Stellen Sie sicher, dass eine .gitignore Datei mit den Regeln in der unter Dateien Ignorieren gegebenen Tabelle in ihrem Gruppenrepository im master Branch existiert.

Git und Gitea

Gitea kann nicht nur die Commitmessages aus dem Repository anzeigen. In der Commitmessage kann auf ein Ticket verwiesen werden, indem man einfach die nummer des Tickets (links neben dem Ticketttiel in Gitea) mit # davor, angibt. Das sort auch dafür, dass der Commit in den Kommentaren des Tickeets aufgelistet wird. Tickets können per Commitmessage geschlossen werden, indem davor noch closes (oder close, fix, fixes) geschrieben wird.

Beispiele

Dies ist ein einfacher Verweis #33.

Dieser Commit schießt das Ticket mit nummer 33, closes #33.

Kombinationen sind auch möglich close #44 close #42, see #12.

Siehe auch

Links

• Git auf Wikipedia
• Das Pro Git Buch - das große Git-Buch online.
• Einfacher Git Guide
• Ofizielle Webseite
• Git Cheat-Sheet
• Ofizielle Dokumentation