Versionsverwaltung mit Git

[joergd]

Im Folgenden werde ich versuchen, die Nutzung der Versionsverwaltung der Hive-Software zu erklären. Für diese wird ein Git-Server auf Basis von GitBlit genutzt, welcher unter https://dev.bitquell.de erreichbar ist. Der Wechsel auf einen anderen Server (z.B. GitHub) ist Git-typisch sehr einfach.
Sinnvoll ist die Nutzung in mehreren Fällen, z.B.:

• Zugriff auf die aktuellsten Quellen zum selbst Compilieren, Testen und evtl. Anpassen
• Aktives Mitwirken bei der Software-Entwicklung, z.B. bei der Erstellung von Patches zur Fehlerbehebung und von neuen Funktionen
• Hosten eigener Software-Projekte für den Hive, um damit anderen die Chance zur Mitwirkung zu geben

In den folgenden Beispielen wird der offizielle Git-Client auf der Kommandozeile/Shell genutzt, welcher unter Linux aus dem Paketquellen der jeweiligen Distribution installiert wird. Für Windows gibt es hier das aktuelle Installationspaket. Abgesehen davon gibt es noch jede Menge grafischer Oberflächen (die Windows-Version enthält auch schon einen einfachen), da kann man sich ganz nach eigenem Geschmack etwas aussuchen. Wer die Funktionalität auf der Kommandozeile verstanden hat, sollte dann auch mit den grafischen Oberflächen klarkommen.

Unter Windows sollten bei der Installation alle Vorgabe-Parameter beibehalten werden (außer man weiß genau, was man tut).
Nach der Installation werden noch die wichtigsten Vorgabe-Parameter angepaßt. Unter Windows öffnet man die Git Bash und gibt folgendes ein:

Code: Alles auswählen

$ git config --global user.name "Drohne 360"
$ git config --global user.email drohne360@bitquell.de
$ git config --global core.autocrlf true
$ git config --global core.safecrlf true

Unter Linux sollte nur der core.autocrlf Parameter geändert werden:

Code: Alles auswählen

$ git config --global user.name "Drohne 360"
$ git config --global user.email drohne360@bitquell.de
$ git config --global core.autocrlf input
$ git config --global core.safecrlf true

"Drohne 360" kann dabei natürlich durch Vor- und Zuname ersetzt werden, statt drohne360@bitquell.de muß die eigene Mailadresse eingetragen werden.

Ein wesentlicher punkt muß bei der Nutzung einer Versionsverwaltung beachtet werden (das betrifft nicht nur GIT): Die Zeichencodierung von Textdateien. Da gibt es schon Schwierigkeiten auf Grund der unterschiedlichen Default-Werte der üblichen Betriebssysteme. Beim Hive kommt erschwerend hinzu, daß die Spin-Files häufig als UTF-16 codiert sind. Das wird von den Versionsverwaltungen meist nicht als Text- sondern als Binärdatei erkannt, womit viele nützliche Funktionalitäten (vor allem Diff) verlorengehen. Deswegen sollte darauf geachtet werden, daß alle Quellcodes ASCII- uder UTF8-Codiert sind. Bei BST erreicht man das durch folgende Einstellung:

[joergd]

Um den aktuellen Stand eines Projektes herunterzuladen (um z.B. tolle neue Funktionen zu nutzen, bevor das offizielle Release erscheint), benötigt man keinerlei Anmeldung am Git-Server, sondern lediglich den installierten Git-Client.

Zum Herunterladen muß man die Git-URL des Projektes angeben. Diese erfährt man auf der Webseite des Git-Servers unter https://dev.bitquell.de/project/HIVE. Hier klickt man auf der linken Seite unter "repositories" das gewünschte Projekt an, z.B. HIVE/TriOS. Durch Anklicken der Git-Schaltfläche öffnet sich ein kleines Fenster mit den verfügbaren Git-Kommandos:

Git-URL

Unter Windows öffnet man die Git Bash, unter Linux die bevorzugte Shell und wechselt in das Verzeichnis, in welches das Projekt heruntergeladen werden soll (ein Unterverzeichnis mit dem Projektnamen wird dort automatisch erstellt). Anschließend wird das Git-Clone-Kommando ausgeführt:

Code: Alles auswählen

$ mkdir Hive
$ cd Hive
$ git clone https://dev.bitquell.de/r/HIVE/TriOS.git

Anschließend kann (vorausgesetzt bstc ist im Pfad installiert) sofort compiliert werden (evtl. nach Ändern der Pfade in make.sh):

Code: Alles auswählen

$ cd TriOS
$ ./make.sh

Das funktioniert unter Linux und Windows.

Will man später eine neue Version des Projektes laden, wird einfach wieder ins Projektverzeichnis gewechselt und ein Pull durchgeführt:

Code: Alles auswählen

$ cd Hive/TriOS
$ git pull

[joergd]

Wer einen Fehler in einem der auf dem Git-Server gehosteten Programme gefunden hat, kann diesen natürlich einfach per E-Mail oder hier im Forum dem Autor melden. Wer sogar noch einen Patch erstellt hat, welcher den Fehler behebt, kann diesen gleich mitsenden. Das Gleiche gilt natürlich für Funktionserweiterungen oder sonstige Verbesserungen.

Noch besser, weil z.B. nachvollziehbar, geht das ganze mit der Erstellung eines Tickets über den Git-Server. Dazu benötigt man allerdings einen Account, welchen derzeit nur ich auf Anfrage erstelle (kann später auch mal über eine automatische Registrierung erfolgen). Wer im Forum angemeldet ist, kann dazu einfach unten auf "PN" klicken und mir eine kurze Nachricht schreiben.

Anschließend meldet man sich auf dem Git-Server mit seinen Zugangsdaten an (oben rechts), wählt das entsprechende Projekt/Repository aus und klickt auf "Tickets". Mittels "create your first Ticket" oder "New" wird nun ein neues Ticket erstellt. Hier kann man nun erstmal beschreiben, um was es genau geht und mittels "create" abspeichern.

Wer nun selbst einen Patch für das beschriebene Problem erstellen will, ruft sein Ticket auf dem Server wieder auf und klickt auf "</>commits". Dort erscheint eine Anleitung, wie ein Patch eingespielt wird. Hier die einzelnen Schritte (im Beispiel für ein Repository HIVE/Test als Benutzer "drohne360"):

Code: Alles auswählen

$ git clone ssh://drohne360@dev.bitquell.de:29418/HIVE/Test.git
$ cd Test
$ git checkout -b ticket/1 origin/master

Zuerst wird also das Repository neu geclont. Als Benutzer mit einem Account macht man das am besten wie angegeben über SSH. "ticket/1" ist ein automatisch für das erste Ticket erstellter Branch, bei bereits vorhandenen anderen Tickets ist das eine andere Nummer. Anschließend kann man mittels BST die gewünschten Änderungen am Quelltext vornehmen und testen. Ist man zufrieden, werden die Änderungen als Patch wie folgt hochgeladen:

Code: Alles auswählen

$ git add *
$ git commit -m "<kurze Beschreibung der Anpassungen>"
$ git push --set-upstream origin ticket/1

"git add *" übernimmt alle Änderungen in die lokale Git-Datenbank (da gibts noch etliche Varianten, s. Git-Hilfen), "git commit..." bestätigt die Änderungen (immer noch lokal) und "git push..." schickt sie zum Server.

Wenn das Ticket nun wieder geöffnet wird, sieht man hinter "</>commits" eine "1". Mit Klick auf "</>commits" kann man sich den Patch ansehen. Das können auch alle anderen, die können den Patch herunterladen (auch per Git), testen und bewerten. Ein Benutzer mit dem entsprechenden Recht (Push) kann den Patch dann bestätigen, anschließend kann er automatisch in die offiziellen Sourcen eingebunden (gemerged) werden.

[joergd]

Einen Fork zu erstellen ist u.a. dann sinnvoll, wenn man größere Änderungen an einem Projekt vornehmen möchte. Dann will man wahrscheinlich öfter mal seinen aktuellen Stand wieder auf den Git-Server laden, z.B. damit den auch andere testen könnten. Wenn das jeder im Hauptzweig des Projekets tun würde, gäbe es ein größeres Durcheinander. Vor allem, wenn man nach ein paar Monaten feststellt, daß die neuen Funktionen doch nicht so toll sind. Dann müßte man mühsam alles aus den inzwischen auch von anderen geänderten Source wieder rausbasteln.

Also erstellt man einen Fork. Das kann man erstmal wieder nur mit einem Account auf dem Server (abgesehen von lokalen Forks mit dem eigenen Git-Client). Nach dem Login auf dem Git-Server wird das gewünschte Projekt ausgewählt und und "fork" (rechts oben) gedrückt. Daraufhin wird der Fork mit dem Namen "~<username>/<Projektname>.git" erstellt. Aus "HIVE/Test.git" wird also z.B. "~drohne360/Test.git". Das ist ein ganz normales Git-Repository, welches man nun auf den eigenen Rechner Clonen kann (s. 2. Beitrag):

Code: Alles auswählen

$ cd Hive
$ git clone ssh://drohne360@dev.bitquell.de:29418/~drohne360/Test.git

Nun kann man nach Herzenslust Änderungen vornehmen und diese mehr oder weniger regelmäßig wieder auf den Server hochladen:

Code: Alles auswählen

$ git add *
$ git commit -m "<kurze Beschreibung der Anpassungen>"
$ git push origin master

Diese Änderungen können auch alle anderen sehen, herunterladen und testen. Über "edit" kann auch Anderen Push-Zugriff auf den Fork gegeben werden, so das diese eigene Änderungen vornehmen können. Ohne Push-Zugriff können andere Account-Inhaber zumindest Tickets erstellen und darüber Patches einreichen (s.o.).

Man kann auch Änderungen, die in der Zwischenzeit ins urspüngliche Repository eingeflossen sind, in seinen Fork übernehmen:

Code: Alles auswählen

$ git remote add upstream ssh://drohne360@dev.bitquell.de:29418/HIVE/Test.git
$ git fetch upstream
$ git merge upstream/master

Mit "git add upstream" wird das Repository angegeben, von welchem geforkt wurde. "git fetch upstream" lädt die Änderungen des Upstreams ins lokale Repository. Im Gegensatz zu "git pull" werden die Änderungen aber noch nicht in die lokalen Dateien übernommen. Das geschieht erst mit "git merge".

Ein Eigentümer des ursprünglichen Repositories kann die Änderungen des Forks nach gründlicher Begutachtung auch übernehmen. Dazu lädt er per Pull den Fork in das ursprüngliche Repository:

Code: Alles auswählen

$ cd Test
$ git pull ssh://admin@dev.bitquell.de:29418/~drohne360/Test.git
$ git push origin master

Nach "cd Test" befindet sich der Eigentümer des ursprünglichen Repositories dessen lokalen Verzeichnis. Mit "git pull..." wird der aktuelle Stand des Forks integriert. "git push..." lädt die Änderungen ins ursprüngliche Repository auf den Server. (normalerweise sollte an dieser Stelle noch mit Branches gearbeitet werden)

[joergd]

Benutzer mit Account auf dem Git-Server können auch eigene Repositories anlegen. Dazu loggt man sich auf dem Server ein und klickt oben auf "Repositories", anschließend auf "+ new repository".
Als Name ist schon "~<username>/" (also z.B. "~drohne360/") vorgegeben. Damit wird das ein persönliches Repository, "richtige" Repositories kann auf Wunsch ein Admin (also ich ) anlegen. Hinter den Schrägstrich muß dann der eigentliche Name des Repositories geschrieben werden, z.B. "~drohne360/Test". Hinter "description" wird noch eine kurze Beschreibung des Projektes angegeben, alles andere muß nicht verändert werden:

Neues Repository anlegen

Also hier einfach auf "save" klicken.

Dieses Repository ist nun erstmal leer. Wenn man es auf dem Server aufruft, erscheinen Hinweise, wie man es füllt:

Leeres Repository

Wenn man das auf den Server hochzuladende Projekt bereits auf seinem lokalen Rechner hat, wechselt man in dessen oberstes Verzeichnis, initialiasiert git, fügt alle Dateien dem Repository hinzu und lädt das Ganze hoch:

Code: Alles auswählen

$ git init
$ git remote add origin ssh://drohne360@dev.bitquell.de:29418/~drohne360/Test.git
$ git add *
$ git commit -m "initial commit"
$ git push -u origin master

Anschließend kann man sich sein Projekt auf dem Server ansehen und damit arbeiten.

Am lokalen Repository vorgenommene Änderungen werden wie folgt auf den Server galaden:

Code: Alles auswählen

$ git add *
$ git commit -m "<kurze Beschreibung der Anpassungen>"
$ git push origin master

Dürfen auch andere am Projekt mitarbeiten, trägt man diese auf dem Server mit "edit" unter "access permissions" ein. Dazu unter "user permissions" den Benutzer auswählen und daneben zumindest "RW (push)" auswählen. Alternativ kann man auch andere ganz oben als owner (Eigentümer) eintragen.
Um von anderen vorgenommene Änderungen auf den eigenen Rechner zu übertragen, wird ein Pull durchgeführt:

Code: Alles auswählen

$ git pull

[joergd]

Branches werden benutzt, um verschiedene Funktionen isoliert voneinander zu entwickeln. Der master-Branch ist der "Standard"-Branch, wenn ein neues Repository erstellt wird. Die eigentliche Entwicklung sollte aber in Branches erfolgen, für jede neue Funktion sollte ein neuer Branch angelegt werden.

Ein Branch wird zuerst lokal auf dem Entwicklungs-PC erzeugt:

Code: Alles auswählen

$ git checkout -b webserver
Gewechselt zu einem neuem Branch 'webserver'

Mit diesem Befehl wird der Branch "webserver" erzeugt und gleich in diesen gewechselt.

Existiert der Branch bereits, muß nur zu diesem gewechselt werden:

Code: Alles auswählen

$ git checkout webserver
Gewechselt zu Branch 'webserver'
Ihr Branch ist auf dem selben Stand wie 'origin/webserver'.

Nun kann die neue Funktion (im Beispiel ein Webserver) programmiert werden. Dafür wurde eine neue Datei "websrv.spin" erzeugt, welche mit "git add" dem Repository hinzugefügt wird.

Code: Alles auswählen

$ git status
# Auf Branch webserver
# Unbeobachtete Dateien:
#   (benutzen Sie "git add <Datei>..." um die Änderungen zum Commit vorzumerken)
#
#       system/regnatix/websrv.spin
nichts zum Commit vorgemerkt, aber es gibt unbeobachtete Dateien (benutzen Sie "git add" zum Beobachten)

$ git add *

Bisher ist alles nur auf dem lokalen PC passiert. Um die Änderungen auf den GIT-Server zu übertragen, wird folgenden Kommando genutzt:

Code: Alles auswählen

$ git push origin webserver

"webserver" ist dabei also der Name des Branches.

Wenn die neuen Funktionen fertig implementiert und getestet sind, ist es Zeit, diese in den master-Branch zu übernehmen:

Code: Alles auswählen

$ git checkout master
$ git merge webserver
$ git branch -d webserver
$ git push origin master
$ git push origin --delete webserver

Damit wurde auf den master-Branch gewechselt, der webserver-Branch in diesen integriert, der webserver-Branch gelöscht, der master-Branch auf den GIT-Server übertragen und der webserver-Branch auf dem GIT-Server gelöscht.

[joergd]

Die obigen Ausführungen klingen erstmal recht komplizert. Ist es aber eigentlich nicht. Ich empfehle allen Interessenten, das einfach mal auszuprobieren. Das Herunterladen (Clone) ist ganz einfach. Wer selbst was beitragen möchte, fragt mich nach einem Account und kann dann einfach mal ein eigenes Repository anlegen und damit spielen. Wie gesagt gibts auch viele grafische Clients und Integrationen in IDEs.

Und bei auftretenden Fragen einfach hier fragen...

[Micha]

Die obigen Ausführungen klingen erstmal recht komplizert.

Du bringst es auf den Punkt.
Hab mich durch den Thread bis hierher durchgelesen und immer mehr den roten Faden verloren. Oder um es konkret zu sagen: ich hab das Gefühl hier wird mit Kanonen auf Spatzen geschossen.
Ich hab als Hobbyist wirklich nur die Ambition, ein wenig mit dem Hive zu experimentieren, ein paar AHA-Erlebnisse zu haben. Ob das Thema "Versionsverwaltung" dazu gehören wird steht derzeit in den Sternen, das meine ich ganz ehrlich und direkt. Momentan bin ich mehr abgeschreckt als fasziniert (aus der Perspektive "wofür brauche ich das wirklich für mein Hobby-Projekt") aber schauen wir mal wie sich das entwickelt. Wenn Du die Sachen gut erklären kannst werd ich vielleicht doch noch zum Fan von GIT, schau'n wir mal...

Bis dahin alles Gute!

Micha

[nubok]

@micha

joergd erklärt es in meinen Augen sehr gut - wenn es kompliziert wirkt, ist das eher der Tatsache geschuldet, dass er ein paar Dinge der Verständlichkeit halber etwas länger erklärt hat, als es sonst üblich ist.

Vielleicht ein paar Ergänzungen meinerseits:

1. Das Tutorial auf https://help.github.com/articles/set-up-git ist (wenn auch Github-spezifisch) durchaus für Einsteiger zu empfehlen. Es erklärt ein paar Dinge ein bißchen "pädagogischer" (also sanfter) als es joergd tut. Wenn man hier durch ist, kann man sich nochmal der Anleitung im Thread hier zuwenden.

2. Eine nette Eigenschaft von Git ist es, dass man von keinem zentralen Server abhängig ist - einfach ein Projekt bei Github, Bitbucket, Gitorious (oder welchen Dienst man bevorzugt) eins anlegen, wenn man für private Experimente einen eigenen privaten "Spielplatz" will (oder mit joergds "Dienstleitung" nicht zufrieden ist ). Nachdem man, wie beschrieben, einen Clone erstellt hat

Code: Alles auswählen

$ git clone ssh://drohne360@dev.bitquell.de:29418/HIVE/Test.git

wird das Remote standardmäßig "origin" genannt. Es ist aber kein Problem, ein zweites (beim bevorzugten Anbieter gehostetes) Remote hinzuzufügen:

Code: Alles auswählen

$ git remote add my_origin ADRESSE

und alles dorthin pushen

Code: Alles auswählen

git push -u my_origin --all # pushes up the repo and its refs for the first time
git push -u my_origin --tags # pushes up any tags

Anschließend kann man dann mit

Code: Alles auswählen

$ git push my_origin BRANCHNAME

in sein ganz privat gehostetes Repository pushen (wobei man - wenn man keinen eigenen Branch angelegt hat (ein Anlegen würde ich allerdings durchaus empfehlen) als BRANCHNAME wahrscheinlich "master" (ohne ") verwenden wird wollen).

[nubok]

Ich habe gesehen, dass im TriOS-Repository die Versionen durch Tags gekennzeichnet sind. Ich vermute, dass ist ein Relikt aus der Subversion-Konvertierung, da der Git-typische Weg ist, für Versionen einen Feature Branch zu erzeugen (hierdurch wird - wenn es denn nötig wird - ein Backporten von Patches stark vereinfacht).