Einführung in das Source-Code-Management System Fossil

Fossil ist ein schlankes Versionsverwaltungssystem mit moderner Architektur. Es ist im Funktionsumfang vergleichbar mit anderen Systemen wie Subversion, Git, Mercurial, etc. wobei die Fossil Entwickler immer darauf achten die Applikation schlank zu halten.

Fossil hat folgende Merkmale:

Man benötigt nur eine (relativ kleine) Exe (fossil bzw. fossil.exe für Windows), die nicht installiert werden muss.
Auch für einen (Web-)Server ist keine zusätzliche Installation notwendig, die Integration in einen laufenden WebServer ist relativ simpel.
Fossil ist ein verteiltes System, d.h. das gleiche Repo kann auf mehreren Servern gleichzeitig gehostet und untereinander synchronisiert werden.
Es ist schnell.
Das komplette Repo befindet sich in einer (Sqlite-)Datei.
Neben dem eigentlichen Repo bietet Fossil noch ein Wiki, mit dem man eine komplette Homepage betreiben kann, und ein Ticket-System.

Ein kleiner Wermutstropfen ist, dass derzeit noch keine brauchbare GUI existiert, weder für Windows, noch für Linux. Dass diese nicht schmerzlich vermisst wird, liegt an der relativ einfachen Bedienung über die Kommandozeile. Man benötigt lediglich eine handvoll Kommandos, um effizient mit dem System arbeiten zu können.

Es folgt eine schrittweise Erläuterung, wie man mit dem System über die Kommandozeile arbeiten kann.

Den kompletten Funktionsumfang kann man auch mit einem lokalen Repository (ohne Verbindung mit einem Server) testen, das man mit dem Befehl:

fossil init repo-filename

anlegt. Damit kann man alle Befehle lokal testen. Nach dem Test dann einfach die Datei repo-filename löschen.

Achtung: Die Syntax der im Folgenden aufgeführten Befehle ist für die Linux/Unix Kommandozeile vorgesehen. Die Befehle an sich sind unter Windows identisch, allerdings sind einige Besonderheiten (wie z.B. Pfade und Umgebungsvariable) zu beachten und anzupassen.

Voraussetzungen

Software

Wie bereits erwähnt, benötigt man für die Nutzung von Fossil Repositories eine einzelne Exe_Datei. Dieses Programm kann für die drei gängigsten Betriebssysteme von folgender Seite herunterladen werden:

Fossil / Download Page

Unter Linux bedient man sich am besten des systemeigenen Paketmanagers. Unter Debian/Ubuntu z.B.:

sudo apt-get install fossil

Das Programm sollte an einen Ort platziert werden, der einen einfachen Aufruf von der Kommandozeile erlaubt. Also z.B. in ein zugängliches Verzeichnis, das bereits im PATH verankert ist.

Netzwerk

Beim Zugriff auf ein Repository, das, wie im Falle des SmartMapping-Repositories, über eine URL aufgerufen wird, ist vorweg dafür zu sorgen, dass der Zugriff gewährleistet ist. Hier gelten für Kommandozeilenprogramme etwas andere Regeln, als beispielsweise für GUI-Applikationen unter Windows, siehe Web-Proxy.

Arbeiten mit einem Repository

Registrieren

Um mit dem Repository sinnvoll zu arbeiten, sollte sich jeder Nutzer zunächst registrieren. Die Rechte lassen sich für jeden Nutzer fein granuliert einstellen. Für Nutzer die mit dem Repo arbeiten (aus-/einchecken, Inhalte verändern etc.) sollen, ist der developer Status vorgesehen.

Registrieren kann man sich hier

Falls nicht ist die Registrierung geschlossen dann bitte an einen Fossil-Admin wenden!

Da unser Repository derzeit nicht offen ist, muss jeder neu registrierte Nutzer zunächst von einem Fossil-Admin Developer-Rechte bekommen, bevor er mit dem Repository arbeiten kann.

Repository clonen

Um mit dem Server-Repo zu arbeiten, muss es zunächst lokal "geclonet" werden:

fossil clone <url> <repo>

<url> ist dabei die Serveradresse nach dem Muster: https://username:password@servername/path/to/repo

<repo> ist ein Pfad zu einer lokalen Repo-Datei, die neu angelegt wird. Es macht Sinn für Repositories ein eigenes Verzeichnis einzurichten, also z.B. $HOME/fossil.

Wenn das Repo nicht frei ist (wie bei SmartMapping derzeit), verlangt der Zugriff die Integration von Username und Passwort. Sonst kann man dies weglassen.

Damit ergibt sich für das clone Kommando ($HOME/fossil muss existieren):

fossil clone https://username:password@dev.adv-smart.de/cgi-bin/repo/smdev $HOME/fossil/smdev.fossil

Proxy-Probleme?

Die Datei (hier smdev.fossil) kann beliebig benannt werden, eine sinnvolle Dateierweiterung (geläufig sind .fossil oder .fsl) empfiehlt sich jedoch aus naheliegenden Gründen.

Nach erfolgreicher Ausführung des Kommandos findet sich das komplette Repository inklusive Historie in der angegebenen Datei.

Die weiteren Vorgänge finden immer auf diesem lokalen Repository statt. Steht die Verarbeitung auf autosync übernimmt fossil bei entsprechender Notwendigkeit die Kommunikation und den Abgleich mit dem Server Repository.

Repository auschecken

Um mit dem (aktuellen) Inhalt des Repositories arbeiten zu können, muss dieser zunächst in ein Arbeitsverzeichnis übertragen werden. Dieser Vorgang nennt sich auschecken.

Hierzu legt man i.d.R. zunächst ein "frisches" Verzeichnis an:

mkdir ~/path/to/work/smdev

wechselt dort hin

cd ~/path/to/work/smdev

und checkt aus (dabei bezieht man sich auf das geclonete Repository):

fossil open $HOME/fossil/smdev.fossil

Nach Abschluss dieses Kommandos befindet sich eine Kopie des aktuellen Zustands (trunk) des Repos im aktuellen Verzeichnis. Diese nennt sich Arbeitskopie.

Hier sei erwähnt:

Es ist durchaus Möglich auf andere Zustände zurückzugreifen und diese auszuchecken.
Es können beliebig viele Arbeitskopien in unterschiedlichen Verzeichnissen angelegt werden, um damit z.B. aufgabenbezogen zu arbeiten.

Mit dem ausgecheckten Repo arbeiten

Um die im Folgenden beschriebenen fossil Kommandos absetzen zu können, sollte man sich mit dem aktuellen Arbeitsverzeichnis der Kommandozeile im ausgecheckten Verzeichnis oder einem Unterverzeichnis desselben befinden.

Zunächst einmal die beiden wichtigsten Kommandos, die nichts kaputt machen, aber einen Überblick über den Arbeitsstand geben:

fossil status

Liefert Informationen zum aktuellen Repo, sowie (ganz wichtig!) eine Liste aller Dateien, die sich im Arbeitsverzeichnis im Vergleich zum lokalen Repo geändert haben.

fossil extra

Liefert eine Liste aller Dateien, die sich im ausgecheckten Verzeichnis (incl. Unterverzeichnisse) befinden, die nicht Teil des Repositories sind. Dies könnten also evtl. neue Dateien sein, die zukünftig Teil des Repos werden sollen.

Wo wir schon dabei sind, neue Dateien fügt man mit

fossil add <pathname>

dem Repository hinzu. Dabei kann <pathname> auch ein Verzeichnis sein, dann werden alle Dateien unterhalb hinzugefügt, die noch nicht unter der Verwaltung des Repos stehen -- also die mit fossil extra <pathname> gelisteten).

Den aktuellen Zustand übernehmen

Den aktuellen Zustand der Arbeitskopie wird in das Repository übernommen durch das Kommando

fossil commit -m "Message"

Damit werden alle Änderungen, die bei fossil status gelistet werden, in das Repo übertragen und die Information Message als Erläuterung hinterlegt. Wurde das lokale Repo ($HOME/fossil/smdev.fossil) aus einer URL geclonet, so wird zunächst ein Abgleich mit dem Server (bei autosync = on) durchgeführt. Falls es zu keinen Konflikten kommt, werden beide Repos auf den neuen Stand gebracht.

Das Kommando kann auch gezielt auf einzelne Dateien oder Verzeichnisse angewandt werden:

    fossil commit -m "Message" <file1> ... <fileN>
    fossil commit -m "Message" <pathname>

Dann sind nur die aufgeführten Dateien, bzw. alle Dateien unter <pathname> Teil des commit.

Ob das Kommando wirklich geklappt hat, sollte man durch Aufrufen der Timeline des Server-Repos überprüfen!

Konflikt lösen

Falls beim commit folgende Meldung (oder ähnlich) erscheint:

Autosync:  https://dev.adv-smart.de/cgi-bin/repo/smdev
Round-trips: 2   Artifacts sent: 0  received: 8
Pull done, sent: 782  received: 5370  ip: 10.213.35.69
would fork.  "update" first or use --allow-fork.

so ist der ausgecheckte Dateibaum nicht mehr auf dem aktuellen Stand. Zwischenzeitlich hat also jemand das Repository bearbeitet und Dateien verändert oder bearbeitet.

Um diesen Konflikt zu beheben, gibt es, wie die Meldung es schon vorschlägt, zwei Möglichkeiten, die im Folgenden aufgeführt sind.

`fossil update`

Ein fossil update im aktuellen Repository bringt es auf den neuesten Stand. Dabei werden die lokal vorgenommenen Änderungen beibehalten. Sollte es zu Konflikten auf Dateiebene kommen, die nicht automatisch aufgelöst werden können, werden diese speziell vermerkt. Sie sind dann händisch zu bereinigen.

`--allow-fork`

Mit der Option --allow-fork weist man fossil an, einen neuen Fork (Aufgabelung) der Quellen anzulegen. Die aktuellen Änderungen werden parallel zum aktuellen Stand eingecheckt und können weiter parallel gepflegt werden. Damit verschiebt man eine evtl. Konfliktbeseitigung auf einen späteren Zeitpunkt. Der Fork sollte möglichst zeitnah durch ein merge wieder beseitigt werden, weil alle Nutzer, die auf dem aktuellen trunk arbeiten, die Änderungen des Fork nicht angezeigt bekommen.

FAQ

Der `clone` Befehl schlägt fehl, weil keine Verbindung zum Web-Server aufgebaut werden kann.

Dies liegt i.d.R. an fehlenden Web-Proxy Einstellungen.

Arbeitet man in größeren Organisationen findet die Verbindung zum Internet meist über einen sog. Web-Proxy (kurz Proxy) statt. Programme, die auf das Internet zugreifen, müssen von diesem Kenntnis erhalten, sonst finden sie keine Inhalte im Internet (sondern nur im Intranet). Beim Web-Browser ist das meist kein Problem, weil die Einstellung vom System-Administrator bereits vorkonfiguriert wurde (in den System-Einstellungen des jeweiligen Betriebssystems).

Leider gibt es, je nach Betriebssystem, unterschiedliche Varianten um die Proxy-Konfiguration vorzunehmen. Während Windows-Systeme hierzu i.d.R. die Registry nutzen, geschieht dies für Unix/Linux Programme über Umgebungsvariable.

Fossil stammt aus der Unix Welt und benötigt für einen Zugriff auf das Internet (auch auf der Windows-Kommandozeile) eine Proxy-Konfiguration über Umgebungsvariable. Hierzu sind folgende Umgebungsvariable zu setzen:

http_proxy
https_proxy

Bei der Nutzung von fossil in einer Windows Cmd-Eingabeaufforderung z.B.:

set http_proxy=http://<proxyServer>:<Port>
set https_proxy=http://<proxyServer>:<Port>

oder konkret z.B.:

set http_proxy=http://ourProxy:8080
set https_proxy=http://ourProxy:8080

Falls die Werte für <proxyServer> und <Port> nicht bekannt sind, sollten sie bei den System-Administratoren zu erfragen sein.

Um diese Zeilen nicht jedes mal aufs Neue eingeben zu müssen, können sie permanent als Umgebungsvariable definiert oder in einem kleinen Skript hinterlegt werden.

Beim ersten `clone` eines Repositories erscheinen Abfragen zu einem Zertifikat.

Das liegt an der genutzten Verschlüsselungstechnologie (SSL) und tritt in Verbindung mit https Adressen auf. Wenn sicher ist, dass es sich um den richtigen Rechner handelt, die Zertifikatfragen zwei mal mit "a" für "always" beantworten. Sollte dieser Befehl dann auf einen Fehler laufen, einfach den selben Befehl noch einmal absenden. Verzögert durch die interaktive Abfrage ist der ursprüngliche Befehl wahrscheinlich auf ein Timeout gelaufen.

Error: login failed

Beim clonen eines Repositories erscheint die Meldung:

...
Error: login failed
...

Das weist meist auf falsche Nutzerdaten hin. Ist man sicher, Nutzernamen und Passwort richtig eingegeben zu haben (z.B. durch Test auf der WebSeite des Repos), kann es an Sonderzeichen liegen, die beim Eingeben über die Kommandozeile fehlinterpretiert werden. So hat unter Linux z.B. ein $ eine spezielle Bedeutung und muss entsprechend entwertet werden.

Um zu überprüfen, ob es an einem fehlinterpretierten Zeichen liegt, kann das Passwort kurzfristig auf eine Zeichenkette ohne Sonderzeichen abgeändert werden.

Externes Programm für Differenz einbinden

Das Kommando:

fossil diff <file>

zeigt den Unterschied der aktuellen Datei im ausgecheckten Bereich zur eingecheckten Variante derselben Datei in einer Form an, die dem des Linux/unix diff Programm ähnelt. Aussagekräftiger ist, vor allem im Windows-Umfeld, das Starten einer Anwendung, welche die Unterschiede visuell ansprechender präsentiert. Mit dem Kommando:

fossil settings gdiff <pathToDiffApp>

Kann man fossil anweisen, beim Aufruf von

fossil gdiff <file>

die unter <pathToDiffApp> abgelegte Applikation aufzurufen. Für Windows eignet sich hierzu z.B. das kostenlose WinMerge. Der Befehl lautet dann beispielsweise:

fossil settings gdiff "C:\Program Files (x86)\WinMerge\WinMergeU.exe"

(Hier ist natürlich der jeweilge "echte" Pfad einzutragen)

Jetzt sollte beim Aufruf von fossil gdiff <file> die WinMerge Applikation starten.

Weiterführende Links

Projekthomepage
https://fossil-scm.org/

Für den schnellen Einstieg
Quick-start Guide

Eine komplette Übersicht aller Kommandos
Projekt-Repo Kommandos

Etwas älter aber immer noch aktuell
Fossil Benutzerhandbuch

Linux Community Artikel zu Fossil
Linux Community Artikel über Fossil

Grafische Oberfläche
Fuel-Scm

Smart Mapping