Subversion-Anleitung
Dieser Artikel beschreibt den Umgang mit dem Subversion-Kommandozeilenclient.
Voraussetzung
Welche Software brauche ich?
Benötigt wird das Programm subversion für die Kommandozeile:
- Download: http://svn.tigris.org
Alternativ liegen auch komfortable SVN-Clients vor:
- Für Windows: http://www.tortoisesvn.net/
- Für Linux (und Windows?): KDEsvn (siehe Paketmanagment)
Die weiteren Erläuterung beziehen sich auf den Kommandozeilen-Client, können aber sinngemäß auf einen graphischen Client übertragen werden.
Dateien im SVN ändern
Will man auch Dateien im Repostiory ändern, braucht man einen Schreibzugang mit Namen und Passwort. Dazu eine Mail an Ben (bekannt von der Mailingliste) schicken.
Wenn es voraussichtlich bei einer einzigen Änderung bleiben wird, kann alternativ auch auf der Mailingliste Unterstützung für ein einmaliges »Einchecken« erbeten werden.
Terminologie
$REPOSITORY_HOME – Das Verzeichnis in dem das ausgecheckte Repository liegt
Was will ich machen?
Das Repository lokal auf meinem Rechner haben
Angenommen ich möchte Neo in das Verzeichnis $VERZEICHNIS/$NEO runterladen:
cd $VERZEICHNIS svn checkout https://svn.neo-layout.org $NEO
$REPOSITORY_HOME ist dann $VERZEICHNIS/$NEO
Das Repository auf meinem Rechner auf den neuesten Stand bringen
cd $REPOSITORY_HOME svn update
Dateien im Repository ändern
Einfach die Datei ändern und weiter geht’s mit dem Abschnitt Änderungen ins Repository hochladen. Allerdings bitte die Ratschläge für das Editieren von Dateien beachten.
Dem Repository neue Dateien hinzufügen
Nachdem man die Datei in der lokalen Repositorykopie erstellt hat:
svn add $DATEI
Weiter mit dem Abschnitt Änderungen ins Repository hochladen.
Dateien im Repository umbenennen
svn mv $DATEI_ALT $DATEI_NEU
Weiter mit dem Abschnitt Änderungen ins Repository hochladen.
Dateien aus dem Repository löschen
svn rm $DATEI
Weiter mit dem Abschnitt Änderungen ins Repository hochladen.
Änderungen ins Repository hochladen
cd $REPOSITORY_HOME svn commit -m "$ÄNDERUNGSBESCHREIBUNG" --username $USER # $USER muss durch den von Ben zugewiesenen Benutzernamen ersetzt werden
Wenn man das Repository mit seinem Nutzernamen ausgecheckt hat, kann »--username $USER« weggelassen werden. Statt auszuchecken wie im Abschnitt Das Repository lokal auf meinem Rechner haben beschrieben, muss man dann einmalig so auschecken:
cd $VERZEICHNIS_WO_NEO_REIN_SOLL svn checkout https://svn.neo-layout.org neo --username $USER # $USER muss durch den von Ben zugewiesenen Benutzernamen ersetzt werden
Ratschläge / »best practice«
In diesem Abschnitt geht es weniger um technische Fragen, sondern eher darum, wie man sinnvoll/empfohlenerweise mit einem SVN arbeiten sollte. Diese Ratschläge haben sich in der Praxis als sinnvoll erwiesen:
- Bevor man beginnt, die eigene SVN-Kopie zu bearbeiten, sollte immer erst ein Update durchgeführt werden (insbesondere, wenn das letzte Aus-checken schon länger her liegt). Dies vermeidet mögliche Konflikte.
- Es ist vorteilhaft, inhaltlich Zusammengehörendes auch gemeinsam zu committen (hochzuladen), und Dinge, die voneinander unabhängig sind, auch einzeln einzuchecken.
- Die Änderungsbeschreibung sollte immer eingegeben werden und möglichst genau sein.
- Längere Änderungsbeschreibungen sollten mit einer kurzen Zusammenfassung der Form »[Adjektiv] Subjekt Prädikat: …« begonnen werden, etwa »Neues Feature: …«, »Caps-Lock-Fehler behoben: …«, »Dokumentation ergänzt: …«
- Inhaltliche (bzw. »programmiertechnische«) Änderungen (oder Fehlerkorrekturen) sollten unabhängig von ästhetischen Korrekturen (wie Einrückungen oder der Korrektur von Rechtschreibfehlern) eingecheckt werden. Mögliche Änderungsbeschreibungen wären etwa: [Revision 698:] »Doku erweitert: Wie man NEO auf dem C64 installieren kann«, [Revision 699:] »Formatierung korrigiert: Leere Zeilen entfernt, Einrückung angeglichen (r698)«
- Größere Commits können auch aufgeteilt werden, wenn die Intention dazu aus den Änderungsbeschreibungen hervor geht.
- Wenn man Angst um kostbare Änderungen durch einen Headcrash während einer intensiven Change-Session hat, muss man einen Branch für den Zeitraum der Änderungen eröffnen.
- Änderungen an der Referenz sollten unbedingt vorher auf der Mailingliste besprochen bzw. ausdiskutiert werden. Unwesentliche Änderungen sollten zumindestens auf der Liste erwähnt werden.
Subversion-Properties setzen
Jede Datei in SVN sollte den richtigen Mime-Type gesetzt haben. Damit ergeben sich bessere Möglichkeiten beim Auschecken von Dateien oder beim direkten Runterladen aus dem Subversion. In Verbindung mit Trac könnten sich auch Vorteile ergeben, die aber von Trac abhängen: Es könnte z.B. Bilddateien, die sich über den Mime-Type als solche zu erkennen geben, auch als eingebettete Bilder behandeln und nicht wie Binärdateien.
Über den Mime-type hinaus gibt es weitere für Subversion wichtige Properties wie beispielsweise «svn:eol-style» zum korrekten Setzen von CR/LF je nach Client-Plattform und «svn:keywords» zum automatischen Updaten von Revision-Informationen. Darüber hinaus kann man für Verzeichnisse mit «svn:ignore» Dateien angeben, die für Subversion immer als „unsichtbar“ gelten sollen, damit er sich nicht über deren Existenz aufregt, wie beispielsweise temporäre Dateien oder Compile-Output. Und seit Kurzem verwaltet Subversion in Properties auch Informationen über den bisherigen Merge-Ablauf für Merge-Tracking. Weiters gibt es vordefinierte Properties zum Setzen der Dateiattribute, was aber nur unter Linux sinnvoll ist (z.B. das „Ausführbar“-Attribut).
Darüber hinaus kann man beliebige eigene Properties angeben und eintragen, die wie Meta-Informationen an den Dateien „haften“, aber nur für Subversion und die entsprechenden Tools sichtbar sind.
Subversion-Properties mit TortoiseSVN setzen
Da gibt es zwei Möglichkeiten:
- Für ein bestimmtes File eintragen: Datei erstmal hinzufügen (add), geht aber auch für Dateien, die bereits im SVN sind. Dann auf Eigenschaften, dort gibt es einen Reiter für Subversion (mit Schildkrot), dort auf «Properties…», «Add…», svn:mime-type aus der Drop-down-Box auswählen und unten dann „image/png“ eingeben. «OK», «OK», «OK», fertig. Der ganze Ablauf ist auch mit dem Command-Line-Interface von Subversion möglich und lässt sich dort auch ganz gut für mehrere Dateien und Unterverzeichnisse automatisieren, um falsch gesetzte Attribute in Ordnung zu bringen.
- Für alle Dateien mit bestimmter Dateiendung: Man geht im Explorer mit der rechten Maustaste auf «TortoiseSVN», «Settings», «General», „Subversion Configuration File «Edit»“ und ändert das nun geöffnete File folgendermaßen: recht weit unten wird in der Section [miscellany] der Eintrag für die Variable „enable-auto-props = yes“ entkommentiert (also das # vorne wegnehmen). Anschließend kann man in der Section [auto-props] sinnvolle Defaults für neu ge-add-ete Subversion-Files setzen. Hier http://brlcad.org/wiki/Cvs2svn#Automatic_properties gibt es eine recht umfangreiche Liste von sinnvollen Autoprops, die man getrost komplett übernehmen kann. Nach dem Editieren schließt man die Datei. Wenn man jetzt eine Datei added, werden je nach Dateiname und -Endung verschiedene sinnvolle Properties automatisch gesetzt. Hinweis: Das funktioniert nicht zum Setzen fehlender Properties.
Textdateien im SVN
Bei Textdateien (Readme.txt etc.) sind drei Regeln zu beachten, um das SVN-Repository in einem vernünftigen Zustand zu halten:
- Zeilentrenner CR+LF: Unter Unix ist es üblich, dass Textdateien am Zeilenende das Zeichen LF (0x0a) enthalten. Windows dagegen erwartet zwei Zeichen CR LF (0x0d 0x0a). Wenn der Anwender unter Windows eine Datei README.txt doppelklickt und mit dem Standard-Editor öffnet, bekommt er keine vernünftige Zeilenanzeige, falls die Datei mit der Unix-Konvention gespeichert wurde. Im Gegensatz dazu kommen gängige Unix-Editoren mit der DOS-Konvention problemlos zurecht. Daher werden mögliche Schwierigkeiten vermieden, wenn die svn-property svn:eol-style auf native gesetzt wird. Dies sollte Darstellungsprobleme von Textdateien unter Windows aus der Welt schaffen, da die Datei automatisch mit dem für das jeweilige Betriebssystem richtigen Zeilentrenner heruntergeladen wird.
- UTF-8 als Standardkodierung: Soweit technisch möglich, sollte stets UTF-8 als Dateikodierung benutzt werden.
- BOM bei UTF-8-Kodierung: Das hier verwendete Dokumentationssystem TRAC bietet u. a. Funktionen zum Betrachten von Textdateien und Änderungen im WWW-Browser. Wir hatten einmal Probleme, dass solche Dateien im trac nicht richtig angezeigt wurden, das ist jetzt aber behoben. Da BOMs bei Shell-Skripten und den Linux-Treibern dazu führen, dass diese ihren Dienst versagen, ist dafür zu sorgen, dass alle Dateien zwar als UTF-8, aber ohne BOM eingecheckt werden! Dazu eignet sich für Windows z. B. Notepad++ ganz gut (das normale Windows-Notepad ist nicht geeignet, da es immer ein BOM setzt).
Dateinamen im SVN
Linux unterscheidet bei Dateinamen streng zwischen Groß- und Kleinschreibung; unter Windows ist das jedoch nicht der Fall. Deshalb muss es von Linux-Nutzern vermieden werden, in einem SVN-Verzeichnis Dateien einzuchecken, die sich nur in der Groß- und Kleinschreibung unterscheiden (bspw. Neo und neo), da sonst das Repository nicht mehr unter Windows ausgecheckt werden kann.
„SVN post commit hook“ und Makefiles
Einige Dateien werden automatisch auf der Grundlage entsprechender Dateien im SVN erstellt. So werden beispielsweise aus der Quelldatei tastatur_neo_alle_Ebenen.svg im SVN verschiedene Grafiken (mit/ohne Nummernblock, …) in unterschiedlichen Grafikformaten (PDF, PNG, …) erzeugt, die hier heruntergeladen werden können. Wird die SVG-Datei geändert, ändern sich automatisch auch diese »abgeleiteten« Dateien.
Diese »Magie« funktioniert folgendermaßen: Nach jeder Änderung des Repository wird vom neo-layout.org-Server ein Makefile im SVN ausgeführt, welches die Grafiken, das Installationsskript, das portable Neo und vieles mehr erzeugt. Dieses Skript kann insbesondere auch andere Makefiles aufrufen. Diese Dateien liegen dann auf dem Server vor und können hier heruntergeladen werden, befinden sich aber nicht im SVN.
Zudem sind im www-Verzeichnis einige zusätzliche Abkürzungen für wichtige Dateien definiert, die über die Adresse http://neo-layout.org/VERWEISTEXT genutzt werden können (bspw. neo20.exe, neo_de.xmodmap, neo_portable.zip, …).
