Diese Dokumentation wurde zur Beschreibung der Serie 1.6.x von Subversion erstellt. Falls Sie eine unterschiedliche Version von Subversion einsetzen, sei Ihnen dringend angeraten, bei http://www.svnbook.com/ vorbeizuschauen und stattdessen die zu Ihrer Version von Subversion passende Version dieser Dokumentation heranzzuiehen.

Peg- und operative Revisionen

Dateien und Verzeichnisse werden auf unseren Rechnern ständig kopiert, verschoben, umbenannt und vollständig ersetzt. Ihr Versionskontrollsystem sollte nicht im Weg stehen, wenn Sie diese Dinge auch mit Dateien und Verzeichnissen unter Versionskontrolle machen. Die Dateiverwaltungsunterstützung von Subversion ist sehr befreiend, indem sie beinahe die gleiche Flexibilität bei versionierten Dateien erlaubt, die Sie bei der Handhabung unversionierter Dateien erwarten. Diese Flexibilität bedeutet aber, dass während der Lebenszeit Ihres Projektarchivs ein gegebenes versioniertes Objekt viele Pfade haben kann, und ein gegebener Pfad verschiedene vollständig unterschiedliche versionierte Objekte repräsentieren kann. Das fügt Ihrer Arbeit mit diesen Pfaden und Objekten einen gewissen Grad an Komplexität hinzu.

Subversion ist ziemlich schlau, wenn es darum geht, festzustellen, wann die Versionsgeschichte eines Objektes eine solche Adressänderung beinhaltet. Wenn Sie beispielsweise das Protokoll der Versionsgeschichte einer bestimmten Datei abfragen, die letzte Woche umbenannt wurde, wird Subversion erfreulicherweise all diese Protokolleinträge liefern – die Revision, in der die Umbenennung vorgenommen wurde und die wichtigen Einträge aus der Zeit vor und nach der Umbenennung. Meistens brauchen Sie sich also nicht um solche Dinge zu kümmern. Doch ist Subversion gelegentlich auf Ihre Hilfe angewiesen, um Unklarheiten aufzuklären.

Das einfachste Beispiel hierfür tritt auf, falls ein Verzeichnis oder eine Datei aus der Versionskontrolle gelöscht und dann ein neues Verzeichnis oder eine neue Datei gleichen Namens erzeugt und unter Versionskontrolle gestellt wird. Bei dem Ding, das Sie gelöscht haben und dem, das Sie später hinzugefügt haben handelt es sich nicht um das selbe Ding. Sie haben lediglich den gleichen Pfad gehabt, beispielsweise /trunk/object. Was bedeutet es dann, Subversion nach der Geschichte von /trunk/object zu fragen? Fragen Sie nach dem Ding, das sich momentan an diesem Ort befindet oder dem alten Ding, das Sie von dort gelöscht haben? Fragen Sie nach den Arbeiten, die an allen Objekten stattgefunden haben, die sich jemals unter diesem Pfad befunden haben? Subversion benötigt einen Hinweis darauf, was Sie wirklich möchten.

Durch Verschiebungen kann die Versionsgeschichte sogar weitaus komplizierter werden. Sie haben beispielsweise ein Verzeichnis namens concept, das ein im Werden begriffenes Software-Projekt beinhaltet, mit dem Sie herumgespielt haben. Schließlich reift das Projekt soweit heran, dass die Idee Flügel bekommen zu haben scheint, was Sie das Undenkbare machen lässt: dem Projekt einen Namen geben. [10] Nehmen wir an, Sie haben Ihre Software Frabnaggilywort genannt. Zu diesem Zeitpunkt erscheint es sinnvoll, das Verzeichnis umzubenennen, um den neuen Namen des Projektes widerzuspiegeln, also wird concept umbenannt in frabnaggilywort. Das Leben geht weiter, und von Frabnaggilywort wird eine Version 1.0 veröffentlicht, die von Massen an Menschen, die ihr Leben zu verbessern trachten, heruntergeladen und täglich benutzt werden.

Dies ist eine wirklich schöne Geschichte, die hier aber nicht endet. Als echter Unternehmer gehen Sie bereits mit der nächsten Idee schwanger. Also erstellen Sie ein neues Verzeichnis concept, und der Zyklus beginnt erneut. Tatsächlich startet dieser Zyklus sehr oft neu über die Jahre, jedes Mal mit dem alten Verzeichnis concept, das manchmal umbenannt wird, falls die Idee reift, manchmal jedoch gelöscht wird, wenn die Idee verworfen wird. Oder, um es auf die Spitze zu treiben, Sie benennen concept für eine Weile in etwas anderes um, aber aus irgend einem Grund taufen Sie es später wieder concept.

In Szenarios wie diesem, verhält sich der Versuch, Subversion aufzufordern, mit diesen wiederverwendeten Pfaden zu arbeiten, ähnlich, wie einem Autofahrer in den westlichen Vororten Chicagos zu erklären, die Roosevelt Road ostwärts zu fahren und links in die Main Street abzubiegen. In nur zwanzig Minuten können Sie die Main Street in Wheaton, Glen Ellyn und Lombard kreuzen. Aber das ist keineswegs die selbe Straße. Unser Autofahrer – und Subversion – benötigen etwas mehr Details, um das Richtige machen zu können.

Glücklicherweise erlaubt es Subversion Ihnen, zu sagen, welche Main Street Sie genau meinten. Der verwendete Mechanismus wird Peg-Revision genannt und Sie geben ihn Subversion alleinig zu dem Zweck mit, eindeutige Linien in der Historie zu identifizieren. Da zu einer gegebenen Zeit höchstens ein versioniertes Objekt einen Pfad belegen kann – oder, genauer, in irgend einer Revision – wird zum Referenzieren einer bestimmten Linie in der Historie lediglich die Kombination aus Pfad und Peg-Revision benötigt. Peg-Revisionen werden dem Subversion-Kommandozeilen-Client in At-Syntax mitgegeben, die so genannt wird, da diese Syntax das Anhängen eines At-Zeichens (@) und die Peg-Revision an das Ende des mit der Revision verbundenen Pfades vorsieht.

Doch was ist mit der Option --revision (-r), von der wir in diesem Buch so oft gesprochen haben? Diese Revision (oder Menge von Revisionen) wird operative Revision (oder operativer Revisionsbereich) genannt. Sobald durch den Pfad und die Peg-Revision eine bestimmte Linie in der Historie identifiziert ist, führt Subversion die verlangte Operation mit der/dem operativen Revision/Revisionsbereich aus. Auf die Analogie mit den Chicagoer Straßen angewendet, bedeutet das, wenn wir aufgefordert werden, zu 606 N. Main Street in Wheaton [11] zu gehen, können wir uns Main Street als unseren Pfad vorstellen und Wheaton als unsere Peg-Revision. Diese beiden Teile an Informationen identifizieren einen eindeutigen Pfad, der begangen werden kann (nördlich oder südlich auf der Main Street), und es hält uns davon ab, auf der Suche nach unserem Ziel, die falsche Main Street herauf oder herunter zu laufen. Nun fügen wir noch 606 N. quasi als operative Revision hinzu, und wir wissen genau, wo wir hin müssen.

Angenommen, dass unser Projektarchiv vor langer Zeit angelegt wurde, und wir in Revision 1 das erste Verzeichnis concept anlegten, darin eine Datei IDEA, die das Konzept beschreibt. Nach einigen Revisionen, in denen echter Quellcode hinzugefügt und verändert wurde, benannten wir in Revision 20 dieses Verzeichnis in frabnaggilywort um. Bis Revision 27 hatten wir ein neues Konzept, ein neues concept-Verzeichnis dafür und eine neue Datei IDEA zur Beschreibung. Dann zogen fünf Jahre und tausende Revisionen ins Land wie es auch in jeder guten Liebesgeschichte passiert.

Nun, Jahre später, fragen wir uns, wie die Datei IDEA damals in Revision 1 aussah. Subversion muss jedoch wissen, ob wir nach der aktuellen Datei in Revision 1 fragen oder nach dem Inhalt irgendeiner Datei, die in Revision 1 an der Stelle concepts/IDEA zu finden war. Sicherlich haben diese Fragen unterschiedliche Antworten, und Dank der Peg-Revisionen können Sie danach fragen. Um zu sehen, wie die aktuelle Datei IDEA in dieser alten Revision aussah, tippen Sie:

$ svn cat -r 1 concept/IDEA 
svn: Kann »concept/IDEA« in Revision 1 nicht im Projektarchiv finden

In diesem Beispiel gab es die aktuelle Datei IDEA natürlich noch nicht in Revision 1, so dass Subversion einen Fehler ausgibt. Der letzte Befehl ist eine Kurzform der längeren Form, die explizit eine Peg-Revision aufführt. Die ausführliche Notation lautet:

$ svn cat -r 1 concept/IDEA@BASE
svn: Kann »concept/IDEA« in Revision 1 nicht im Projektarchiv finden

Beim Ausführen kommt es dann zum erwarteten Ergebnis.

Der scharfsinnige Leser fragt sich an dieser Stelle wahrscheinlich, ob die Syntax der Peg-Revisionen problematisch für Pfade in Arbeitskopien oder URLs sein kann, die At-Zeichen beinhalten. Woher weiß svn letztendlich, ob news@11 der Name eines Verzeichnisses in meinem Baum ist oder nur die Syntax für Revision 11 von news? Während svn stets letzteres annimmt, gibt es glücklicherweise eine Abhilfe. Sie brauchen lediglich ein At-Zeichen am Ende des Pfades anfügen, etwa news@11@. svn schert sich nur um das letzte At-Zeichen im Argument, und es ist nicht verboten, nach dem At-Zeichen die Angabe der Peg-Revision auszulassen. Diese Abhilfe gilt sogar für Pfade, die auf ein At-Zeichen enden – Sie würden filename@@ verwenden, um sich auf eine Datei namens filename@ zu beziehen..

Stellen wir nun die andere Frage. Was war der Inhalt der Datei, die sich zum Zeitpunkt von Revision 1 am Ort von concepts/IDEA befand? Um das herauszufinden, verwenden wir eine explizite Peg-Revision.

$ svn cat concept/IDEA@1
The idea behind this project is to come up with a piece of software
that can frab a naggily wort.  Frabbing naggily worts is tricky
business, and doing it incorrectly can have serious ramifications, so
we need to employ over-the-top input validation and data verification
mechanisms.

Beachten Sie, dass wir dieses Mal keine operative Revision angegeben haben. Wenn nämlich keine operative Revision angegeben wird, nimmt Subversion standardmäßig an, dass die operative Revision die selbe wie die Peg-Revision ist.

Wie Sie sehen, scheint die Ausgabe unserer Operation korrekt zu sein. Der Text erwähnt sogar frabbing naggily worts, so dass es höchstwahrscheinlich die Datei ist, die die Software beschreibt, die nun Frabnaggilywort heißt. Wir können das tatsächlich überprüfen, indem wir die Kombination aus expliziter Peg-Revision und expliziter operativer Revision verwenden. Wir wissen, dass in HEAD das Projekt Frabnaggilywort im Verzeichnis frabnaggilywort liegt. Also geben wir an, dass wir sehen möchten, wie sich die Historie in Revision 1 identifizierte, die in HEAD als frabnaggilywort/IDEA bekannt ist.

$ svn cat -r 1 frabnaggilywort/IDEA@HEAD
The idea behind this project is to come up with a piece of software
that can frab a naggily wort.  Frabbing naggily worts is tricky
business, and doing it incorrectly can have serious ramifications, so
we need to employ over-the-top input validation and data verification
mechanisms.

Auch brauchen Peg und operative Revisionen nicht so trivial zu sein. Sagen wir beispielsweise, das Verzeichnis frabnaggilywort sei aus HEAD gelöscht, wir wissen aber, dass es in Revision 20 existierte, und wir wollen die Unterschiede der Datei IDEA zwischen den Revisionen 4 und 10 sehen. Wir können Peg-Revision 20 in Verbindung mit dem URL, verwenden, der sich auf Frabnaggilyworts Datei IDEA in Revision 20 bezog, und dann 4 und 10 als operativen Revisionsbereich verwenden.

$ svn diff -r 4:10 http://svn.red-bean.com/projects/frabnaggilywort/IDEA@20
Index: frabnaggilywort/IDEA
===================================================================
--- frabnaggilywort/IDEA	(revision 4)
+++ frabnaggilywort/IDEA	(revision 10)
@@ -1,5 +1,5 @@
-The idea behind this project is to come up with a piece of software
-that can frab a naggily wort.  Frabbing naggily worts is tricky
-business, and doing it incorrectly can have serious ramifications, so
-we need to employ over-the-top input validation and data verification
-mechanisms.
+The idea behind this project is to come up with a piece of
+client-server software that can remotely frab a naggily wort.
+Frabbing naggily worts is tricky business, and doing it incorrectly
+can have serious ramifications, so we need to employ over-the-top
+input validation and data verification mechanisms.

Glücklicherweise sind die meisten Leute nicht von solch komplizierten Situationen betroffen. Sollte das für Sie aber zutreffen, denken Sie daran, dass es sich bei Peg-Revisionen um diesen extra Hinweis handelt, den Subversion benötigt, um Mehrdeutigkeiten zu beseitigen.



[10] Sie sollten es nicht mit einem Namen versehen. Sobald Sie es mit einem Namen versehen, beginnen Sie, sich mit ihm verbunden zu fühlen. – Mike Wazowski

[11] 606 N. Main Street, Wheaton, Illinois, ist die Heimat des Wheaton Geschichts-Zentrums. Es erschien angebracht….