Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008 Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato
Dieses Werk steht unter der Lizenz der Creative Commons Attribution License. Um eine Kopie dieser Lizenz einzusehen, gehen Sie zu http://creativecommons.org/licenses/by/2.0/ oder schreiben Sie an Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
(TBA)
Inhaltsverzeichnis
Abbildungsverzeichnis
Tabellenverzeichnis
Beispiele
Eine schlechte FAQ (Frequently Asked Questions) ist eine, die nicht aus den Fragen besteht, die wirklich gefragt wurden, sondern aus denen, die der Autor sich von den Fragenden gewünscht hätte. Vielleicht haben Sie solche schon gesehen:
F: Wie kann ich Glorbosoft XYZ einsetzen, um die Team-Produktivität zu maximieren?
A: Viele unserer Kunden wollen wissen, wie sie Ihre Produktivität mit unseren patentierten Office Groupware Innovationen maximieren können. Die Antwort ist einfach: zuerst klicken Sie auf das Menü „
Datei
“, fahren hinunter zum Eintrag „Erhöhe Produktivität
“, und dann …
Das Problem mit solchen FAQs ist, dass sie keine FAQs im eigentlichen Sinne sind. Niemand fragt den technischen Support: „Wie können wir unsere Produktivität steigern?“ Üblicherweise fragen Leute sehr spezifische Fragen, wie: „Wie können wir das Kalendersystem so ändern, dass es die Erinnerungen zwei Tage statt einen Tag im Voraus aussendet?“ und so weiter. Aber es ist viel leichter, häufig gestellte Fragen zu erfinden, als die richtigen Fragen zu entdecken. Eine sinnvolle FAQ-Sammlung zusammenzustellen, erfordert eine ausdauernde, planvolle Anstrengung: über die Lebensdauer einer Software müssen hereinkommende Anfragen ausgewertet und Rückmeldungen evaluiert werden und zu einem konsistenten und benutzerfreundlichen Ganzen zusammengeführt werden, das die gesammelte Erfahrung der Anwendenden wiedergibt. Es erfordert die geduldige, aufmerksame Einstellung eines Naturforschers. Nicht großartige Hypothesen und visionäre Vorhersagen, sondern hauptsächlich offene Augen und genaue Aufzeichnungen sind gefragt.
Was ich an diesem Buch liebe, ist, dass es genau aus einem solchen Prozess gewachsen ist und dies auf jeder Seite sichtbar ist. Es ist das direkte Ergebnis der Begegnungen der Autoren mit Benutzern. Es begann mit Ben Collins-Sussmans Beobachtung, dass Leute immer wieder die gleichen grundlegenden Fragen auf der Subversion-Mailingliste stellten: Was sind die Standard-Arbeitsabläufe mit Subversion? Funktionieren Branches und Tags genau so wie in anderen Versionskontrollsystemen? Wie finde ich heraus, wer eine bestimmte Änderung durchgeführt hat?
Frustriert davon, Tag für Tag immer wieder die gleichen Fragen zu sehen, arbeitete Ben im Sommer 2002 über einen Monat intensiv daran, The Subversion Handbook zu schreiben, eine 60-seitige Anleitung, die die Grundlagen der Benutzung von Subversion beschrieb. Die Anleitung erhob keinen Anspruch auf Vollständigkeit, aber sie wurde mit Subversion verteilt und half vielen über die ersten Buckel der Lernkurve. Als O'Reilly and Associates sich entschieden, ein vollständiges Buch über Subversion herauszugeben, war der Weg des geringsten Widerstandes offensichtlich: The Subversion Handbook muss erweitert werden.
Die drei Co-Autoren des neuen Buches erhielten somit eine seltene Gelegenheit. Eigentlich war es ihre Aufgabe, ein Buch beginnend mit dem Inhaltsverzeichnis und einem Rohkonzept zu schreiben; jedoch hatten sie auch Zugang zu einem ständigen Strom – ja einem unkontrollierbaren Geysir – aus Quellmaterial. Subversion wurde bereits von tausenden experimentierfreudigen Menschen benutzt, und diese gaben Unmengen an Rückmeldungen – nicht nur über Subversion, sondern auch über die bestehende Dokumentation.
Während der gesamten Zeit, in der sie dieses Buch schrieben, durchstöberten Ben, Mike und Brian unablässig die Subversion-Mailinglisten und Chaträume und notierten die Probleme, die Benutzer im echten Leben hatten. Die Beobachtung derartiger Rückmeldungen war ohnehin ein Teil ihrer Arbeit bei CollabNet, was ihnen einen Riesenvorteil verschaffte, als sie sich entschlossen, Subversion zu dokumentieren. Das Buch, das sie schrieben, gründet auf dem festen Fels der Erfahrung und nicht auf dem Treibsand des Wunschdenkens. Es vereint die Vorteile von Bedienungsanleitung und FAQ. Diese Zweigleisigkeit ist vielleicht nicht gleich zu erkennen. Von vorne nach hinten gelesen ist das Buch einfach eine Beschreibung einer Software. Es gibt die Übersicht, den obligatorischen Rundgang, das Kapitel über Administration, einige fortgeschrittene Themen und natürlich eine Funktionsübersicht sowie eine Anleitung zur Problemlösung. Erst wenn Sie es später wieder zur Hand nehmen, um die Lösung für ein bestimmtes Problem zu suchen, wird die Zuverlässigkeit des Buches offenbar: in den beschriebenen Details,die nur aus der Erfahrung mit dem Unerwarteten erwachsen konnten, in den Beispielen, die aus dem tatsächlichem Einsatz gebildet wurden, und am meisten durch das Gefühl für die Bedürfnisse und den Blickwinkel der Benutzer.
Natürlich kann niemand versprechen, dass dieses Buch alle
Fragen beantwortet, die Sie über Subversion haben. Manchmal wird
die Genauigkeit, mit der es Ihre Fragen erwartet, unheimlich und
telepathisch erscheinen; gelegentlich werden Sie jedoch in ein
Loch im Wissen der Gemeinschaft stolpern und mit leeren Händen
dastehen. Wenn das passiert schreiben Sie am besten eine E-Mail
an <users@subversion.tigris.org>
und schildern Ihr
Problem. Die Autoren sind nach wie vor dort und beobachten. Und
das betrifft nicht nur die drei, die auf dem Umschlag erscheinen
sind, sondern viele andere, die Korrekturen und neues Material
beigesteuert haben. Aus der Sicht der Gemeinschaft ist die Lösung
Ihres Problems lediglich ein erfreulicher Nebeneffekt eines viel
größeren Projektes – nämlich das Buch und schlussendlich
auch Subversion selbst immer näher an die Art und Weise
anzupassen, in der es tatsächlich benutzt wird. Diese Personen
sind begierig darauf, von Ihnen zu hören, nicht nur weil sie Ihnen
helfen können, sondern auch weil ihnen selbst damit geholfen ist.
Für Subversion – so wie für alle aktiven freien
Software-Projekte – gilt: Sie sind nicht
allein.
Lassen Sie dieses Buch Ihren ersten Begleiter sein.
Inhaltsverzeichnis
„Es ist wichtig, die Vollkommenheit nicht zum Feind des Guten werden zu lassen, selbst dann, wenn darüber Einigkeit besteht, was Vollkommenheit ist. Erst recht, wenn man sich nicht darüber einig ist. So unangenehm es ist, durch vergangene Fehler gefangen zu sein, kann man während des Entwurfs keinen Fortschritt erzielen, wenn man Angst vor dem eigenen Schatten hat.“ | ||
--Greg Hudson, Subversion-Entwickler |
In der Welt der Open-Source-Software war das Concurrent Versions System (CVS) für viele Jahre das Werkzeug der Wahl für Versionskontrolle. Und das zu Recht. CVS war selbst Open-Source-Software und seine nicht-einschränkende Vorgehensweise und Unterstützung für netzbasierten Einsatz erlaubte dutzenden geografisch verteilten Programmierern, ihre Arbeit zu teilen. Es passte sehr gut zur kollaborativen Natur der Open-Source-Welt. CVS und sein halb chaotisches Entwicklungsmodell sind seitdem zu Eckpfeilern der Open-Source-Kultur geworden.
Jedoch war CVS nicht makellos, und diese Makel einfach zu beseitigen, versprach einen enormen Aufwand. Bühne frei für Subversion. Subversion wurde als Nachfolger für CVS entworfen, und seine Schöpfer zogen los, um auf zwei Wegen die Herzen der CVS-Benutzer zu gewinnen – indem ein Open-Source-System erschaffen wurde, dessen Design (und „look and feel“) ähnlich wie CVS war, und indem versucht wurde, die auffälligsten Makel von CVS zu vermeiden. Obwohl das Ergebnis nicht notwendigerweise den nächsten Evolutionsschritt in Sachen Versionskontrolle darstellt, ist Subversion sehr mächtig, sehr brauchbar und sehr flexibel. Und größtenteils wählen nun fast alle neuen Open-Source-Projekte Subversion statt CVS.
Dieses Buch ist geschrieben worden, um die Serie 1.5 des Subversion Versionskontrollsystems zu dokumentieren. Wir haben stets versucht, die Themen gründlich zu behandeln. Jedoch hat Subversion eine florierende und tatkräftige Entwicklergemeinde, so dass bereits eine Menge an Features und Verbesserungen für künftige Versionen von Subversion geplant sind, die Änderungen mancher Kommandos und bestimmter Anmerkungen in diesem Buch bewirken könnten.
Dieses Buch ist für computerkundige Leute geschrieben, die mit Subversion ihre Daten verwalten wollen. Obwohl Subversion unter verschiedenen Betriebssystemen läuft, ist die primäre Benutzerschnittstelle kommandozeilenbasiert. Dieses Kommandozeilenwerkzeug (svn) und einige Hilfsprogramme stehen im Mittelpunkt dieses Buches.
Aus Gründen der Vereinheitlichung gehen die Beispiele in
diesem Buch davon aus, dass der Leser ein unixähnliches
Betriebssystem benutzt und mit Unix und
Kommandozeilenschnittstellen verhältnismäßig gut zurechtkommt.
Nichtsdestotrotz läuft svn auch
unter anderen Betriebssystemen als Unix, etwa Microsoft Windows. Bis
auf ein paar Ausnahmen, wie z.B. die Verwendung umgekehrter
Schrägstriche (\
) statt Schrägstrichen
(/
) als Pfadtrenner, sind die Ein- und Ausgaben
dieses Werkzeugs unter Windows identisch zur Unix-Version.
Die meisten Leser sind wahrscheinlich Programmierer oder Systemadministratoren, die Änderungen an Quellcode verfolgen müssen. Das ist der am meisten verbreitete Einsatzzweck von Subversion, so dass alle Beispiele in diesem Buch auf diesem Szenario beruhen. Doch Subversion kann gleichwohl dazu benutzt werden, Änderungen an allerlei Arten von Informationen zu verwalten – Bilder, Musik, Datenbanken, Dokumentation usw. Für Subversion sind alle Daten einfach Daten.
Obwohl dieses Buch unter der Annahme geschrieben worden ist, dass der Leser noch nie ein Versionskontrollsystem benutzt hat, haben wir auch versucht, für Anwender von CVS (und anderen Systemen) den Sprung zu Subversion so schmerzlos wie möglich zu machen. Ab und zu werden in Randnotizen andere Versionskontrollsysteme erwähnt, und ein besonderer Anhang fasst viele der Unterschiede zwischen CVS und Subversion zusammen.
Es sei angemerkt, dass es sich bei den Quelltexten in diesem Buch nur um Beispiele handelt. Obwohl sie sich mit den passenden Compiler-Aufrufen übersetzen ließen, sollen sie lediglich ein besonderes Szenario illustrieren und nicht als Vorlage für guten Programmierstil oder gute Programmierpraxis dienen.
Technische Bücher stehen immer vor einem bestimmten Dilemma: ob sie von-oben oder von-unten Lernenden entgegenkommen sollen. Ein von-oben Lernender bevorzugt es, Dokumentation zu lesen oder zu überfliegen und dabei einen groben Überblick über das Funktionieren des Systems zu erhalten, bevor er beginnt, die Software zu verwenden. Ein von-unten Lernender ist eine Person, für die „Lernen durch Ausprobieren“ gilt, jemand, der in die Software eintauchen möchte, um beim Ausprobieren herauszufinden, wie sie funktioniert, und wenn nötig Abschnitte im Buch nachschlägt. Die meisten Bücher werden für die eine oder andere Art dieser Personen geschrieben, wobei dieses Buch zweifellos den von-oben Lernenden entgegenkommt. (Und wenn Sie gerade diesen Abschnitt lesen, sind Sie wahrscheinlich selber ein von-oben Lernender!) Verzweifeln Sie jedoch nicht, falls Sie ein von-unten Lerner sind. Während dieses Buch als eine breite Betrachtung der Themen rund um Subversion gestaltet ist, beinhaltet jeder Abschnitt eine reichhaltige Auswahl an Beispielen, die sie ausprobieren können. Die Ungeduldigen, die einfach weitermachen wollen, können sofort zu Anhang A, Subversion Quick-Start Guide springen.
Ungeachtet Ihrer Lernmethode zielt dieses Buch darauf ab, für Menschen unterschiedlicher Herkunft nützlich zu sein – von Menschen ohne vorherige Erfahrung mit Versionskontrolle bis hin zu erfahrenen Systemadministratoren. Je nach Ihrer Herkunft können bestimmte Kapitel mehr oder weniger wichtig für Sie sein. Was nun folgt, kann als „Leseempfehlung“ für verschiedene Typen von Lesern betrachtet werden:
Die Annahme ist, dass Sie wahrscheinlich bereits Versionskontrolle verwendet haben und darauf brennen, möglichst schnell einen Subversion-Server zum Laufen zu bekommen. Kapitel 5, Verwaltung des Repositorys und Kapitel 6, Die Administration eines Subversion-Servers zeigen, wie Sie Ihr erstes Repository erzeugen und es über das Netz verfügbar machen können. Danach sind Kapitel 2, Grundlegende Benutzung und Anhang B, Subversion for CVS Users die schnellsten Wege zum Lernen des Subversion-Clients.
Wahrscheinlich hat Ihr Administrator Subversion bereits aufgesetzt, und Sie möchten nun lernen, wie man den Client benutzt. Falls Sie noch nie ein Versionskontrollsystem benutzt haben, ist Kapitel 1, Grundlegende Konzepte eine unbedingt notwendige Einführung in die Konzepte der Versionskontrolle. Kapitel 2, Grundlegende Benutzung ist eine Führung durch den Subversion-Client.
Ob Sie ein Benutzer oder ein Administrator sind, letztendlich wird Ihr Projekt anwachsen. Sie werden lernen wollen, wie man fortgeschrittene Dinge mit Subversion machen kann, etwa Branches verwenden und Merges durchführen (Kapitel 4, Verzweigen und Zusammenführen), wie Subversions Property-Unterstützung (Kapitel 3, Advanced Topics) zu benutzen ist, wie Laufzeitoptionen konfiguriert werden können (Kapitel 7, Customizing Your Subversion Experience) und vieles mehr. Diese Kapitel sind zunächst nicht kritisch, jedoch sollten Sie sie lesen, sobald Sie mit den Grundlagen vertraut sind.
Unter der Annahme, dass Sie bereits mit Subversion vertraut sind und es nun entweder erweitern oder neue Software basierend auf einem seiner zahlreichen APIs erstellen möchten, ist Kapitel 8, Embedding Subversion genau das, was sie suchen.
Das Buch schließt mit einer Referenz – Kapitel 9, Subversion Complete Reference ist ein Referenzhandbuch für alle Befehle von Subversion, und die Anhänge behandeln eine Anzahl nützlicher Themen. Dies sind die Kapitel, zu denen Sie sehr wahrscheinlich zurückkehren werden, wenn Sie dieses Buch beendet haben.
Die folgenden typografischen Konventionen werden in diesem Buch verwendet:
Festbreitenschrift
Verwendet für Benutzereingaben, Befehlsausgaben und Kommandozeilenoptionen
Kursiv
Verwendet für Programm- und Subversion-Unterbefehlsnamen, Datei- und Verzeichnisnamen und für neue Begriffe
Kursive Festbreitenschrift
Verwendet für zu ersetzende Objekte in Code und Text
Des Weiteren haben wir besonders hilfreiche oder wichtige Informationshäppchen, wegen der besseren Auffindbarkeit optisch hervorgehoben, über das gesamte Buch verteilt (dort, wo es für den Zusammenhang bedeutsam ist). Achten Sie beim Lesen auf die folgenden Bilder:
Dieses Bild markiert einen besonders wichtigen Punkt.
Dieses Bild markiert einen nützlichen Tipp oder eine empfohlene Vorgehensweise.
Dieses Bild markiert eine Warnung. Beachten Sie diese besonders, um Probleme zu vermeiden!
Hier sind die folgenden Kapitel und ihr Inhalt aufgeführt:
Erklärt die Grundlagen von Versionskontrolle und unterschiedliche Versionierungsmodelle sowie das Repository von Subversion, Arbeitskopien und Revisionen.
Ein Spaziergang durch den Tag eines Subversion-Anwenders. Es zeigt, wie ein Subversion-Client verwendet wird, um Daten zu bekommen, zu verändern und abzuliefern.
Behandelt komplexere Eigenschaften, denen Benutzer letztendlich begegnen werden, wie etwa versionierte Metadaten, Dateisperren und Peg-Revisionen.
Behandelt Branches, Merges und Tagging inklusive empfohlener Vorgehensweisen beim Branchen und Mergen, übliche Szenarien, wie Änderungen wieder rückgängig gemacht werden können und wie einfach von einem Branch zum nächsten gewechselt werden kann.
Beschreibt die Grundlagen des Subversion-Repositorys, wie man ein Repository anlegt, konfiguriert und wartet sowie die Tools, die man hierfür benutzen kann
Erklärt, wie man einen Subversion-Server
konfiguriert und unterschiedliche Arten auf ein
Repository zuzugreifen: HTTP
, das
svn
-Protokoll und über die lokale
Festplatte. Behandelt werden hier auch die
Authentifizierung, die Autorisierung und der anonyme
Zugriff.
Untersucht die Subversion-Client-Konfigurationsdateien, die Handhabung internationalisierter Texte und wie man externe Tools zur Zusammenarbeit mit Subversion bringt.
Beschreibt die Interna von Subversion, das Subversion-Dateisystem und die Verwaltungsbereiche der Arbeitskopie aus der Sicht eines Programmierers. Hier wird auch gezeigt, wie die veröffentlichten APIs in einem Programm verwendet werden, das Subversion benutzt.
Erklärt detailreich jeden Unterbefehl von svn, svnadmin und svnlook mit vielen Beispielen für die ganze Familie.
Für die Ungeduldigen eine Anleitung im Schnelldurchlauf für die Installation und die sofortige Benutzung. Seien Sie gewarnt!
Behandelt die Ähnlichkeiten und Unterschiede zwischen Subversion und CVS mit etlichen Vorschlägen, wie man sich all die schlechten Angewohnheiten aus jahrelangem CVS-Gebrauch wieder abgewöhnen kann. Dies beinhaltet Subversion-Revisionsnummern, versionierte Verzeichnisse, Offline-Tätigkeiten, update und status, Branches, Tags, Metadaten, Konfliktauflösung und Authentifizierung.
Beschreibt die Details zu WebDAV und DeltaV und wie man sein Subversion-Repository konfiguriert, damit es als freigegebenes DAV-Laufwerk schreibbar in das Dateisystem eingehängt werden kann.
Eine Kopie der Creative Commons Attribution License, unter der dieses Buch lizenziert ist.
Dieses Buch startete aus Dokumentationsschnipseln von Entwicklern des Subversion-Projektes, die in einem Werk gebündelt und umgeschrieben wurden. Insofern war es immer schon unter einer freien Lizenz (siehe Anhang D, Copyright). Tatsächlich wurde das Buch unter den Augen der Öffentlichkeit geschrieben, ursprünglich als Teil des Subversion Projektes selbst. Das bedeutet zweierlei:
Sie werden stets die neueste Version dieses Buchs im eigenen Subversion-Repository finden.
Sie können an diesem Buch Änderungen vornehmen und es wie auch immer weiterverteilen – es unterliegt einer freien Lizenz. Ihre einzige Verpflichtung besteht darin, den Hinweis auf die ursprünglichen Autoren beizubehalten. Natürlich würden wir es bevorzugen, wenn Sie Rückmeldungen und Verbesserungen der Subversion-Entwicklergemeinde zukommen ließen, anstatt Ihre Privatversion zu verteilen.
Die Homepage der Entwicklungs- und Übersetzungsaktivitäten
auf freiwilliger Basis ist
http://svnbook.red-bean.com. Dort finden Sie
Links auf die neuesten Releases und mit Tags versehene Versionen des Buchs
in verschiedenen Formaten ebenso wie eine Anleitung, auf das
Subversion-Repository des Buchs zuzugreifen (dort lebt sein
Quellcode im DocBook-XML-Format). Rückmeldungen sind
willkommen – ja sogar erwünscht. Bitte senden Sie alle
Kommentare, Beschwerden und Patches für die Sourcen des Buchs an
<svnbook-dev@red-bean.com>
.
Dieses Buch wäre nicht möglich (und auch nicht sehr nützlich) wenn es Subversion nicht gäbe. Dafür möchten die Autoren Brian Behrendorf danken sowie CollabNet für die Vision, solch ein riskantes und ehrgeiziges Open-Source-Projekt zu finanzieren; Jim Blandy für den ursprünglichen Namen von Subversion und sein Design – wir lieben Dich, Jim; Karl Fogel, dafür, dass er so ein guter Freund und Leiter der Gemeinde ist, in dieser Reihenfolge. [1]
Dank an O'Reilly und unsere verschiedenen Redakteure: Chuck Toporek, Linda Mui, Tatiana Apandi, Mary Brady und Mary Treseler. Ihre Geduld und Unterstützung waren enorm.
Schließlich danken wir den zahllosen Menschen, die zu diesem Buch durch informelle Rezensionen, Vorschläge, und Fehlerbehebungen beigetragen haben. Obwohl diese Liste zweifellos nicht vollständig ist, wäre dieses Buch unfertig und fehlerhaft ohne die Hilfe von: Bhuvaneswaran A, David Alber, C. Scott Ananian, David Anderson, Ariel Arjona, Seth Arnold, Jani Averbach, Charles Bailey, Ryan Barrett, Francois Beausoleil, Brian R. Becker, Yves Bergeron, Karl Berry, Jennifer Bevan, Matt Blais, Jim Blandy, Phil Bordelon, Sietse Brouwer, Tom Brown, Zack Brown, Martin Buchholz, Paul Burba, Sean Callan-Hinsvark, Branko Cibej, Archie Cobbs, Jason Cohen, Ryan Cresawn, John R. Daily, Peter Davis, Olivier Davy, Robert P. J. Day, Mo DeJong, Brian Denny, Joe Drew, Markus Dreyer, Nick Duffek, Boris Dusek, Ben Elliston, Justin Erenkrantz, Jens M. Felderhoff, Kyle Ferrio, Shlomi Fish, Julian Foad, Chris Foote, Martin Furter, Vlad Georgescu, Peter Gervai, Dave Gilbert, Eric Gillespie, David Glasser, Marcel Gosselin, Lieven Govaerts, Steve Greenland, Matthew Gregan, Tom Gregory, Maverick Grey, Art Haas, Mark E. Hamilton, Eric Hanchrow, Liam Healy, Malte Helmert, Michael Henderson, Øyvind A. Holm, Greg Hudson, Alexis Huxley, Auke Jilderda, Toby Johnson, Jens B. Jorgensen, Tez Kamihira, David Kimdon, Mark Benedetto King, Robert Kleemann, Erik Kline, Josh Knowles, Andreas J. Koenig, Axel Kollmorgen, Nuutti Kotivuori, Kalin Kozhuharov, Matt Kraai, Regis Kuckaertz, Stefan Kueng, Steve Kunkee, Scott Lamb, Wesley J. Landaker, Benjamin Landsteiner, Vincent Lefevre, Morten Ludvigsen, Dennis Lundberg, Paul Lussier, Bruce A. Mah, Jonathon Mah, Karl Heinz Marbaise, Philip Martin, Feliciano Matias, Neil Mayhew, Patrick Mayweg, Gareth McCaughan, Craig McElroy, Simon McKenna, Christophe Meresse, Jonathan Metillon, Jean-Francois Michaud, Jon Middleton, Robert Moerland, Marcel Molina Jr., Tim Moloney, Alexander Mueller, Tabish Mustufa, Christopher Ness, Roman Neuhauser, Mats Nilsson, Greg Noel, Joe Orton, Eric Paire, Dimitri Papadopoulos-Orfanos, Jerry Peek, Chris Pepper, Amy Lyn Pilato, Kevin Pilch-Bisson, Hans Polak, Dmitriy Popkov, Michael Price, Mark Proctor, Steffen Prohaska, Daniel Rall, Srinivasa Ramanujan, Jack Repenning, Tobias Ringstrom, Jason Robbins, Garrett Rooney, Joel Rosdahl, Christian Sauer, Ryan Schmidt, Jochem Schulenklopper, Jens Seidel, Daniel Shahaf, Larry Shatzer, Danil Shopyrin, Erik Sjoelund, Joey Smith, W. Snyder, Stefan Sperling, Robert Spier, M. S. Sriram, Russell Steicke, David Steinbrunner, Sander Striker, David Summers, Johan Sundstroem, Ed Swierk, John Szakmeister, Arfrever Frehtes Taifersar Arahesis, Robert Tasarz, Michael W. Thelen, Mason Thomas, Erik van der Kolk, Joshua Varner, Eric Wadsworth, Chris Wagner, Colin Watson, Alex Waugh, Chad Whitacre, Andy Whitcroft, Josef Wolf, Luke Worth, Hyrum Wright, Blair Zajac, Florian Zumbiehl, und die gesamte Subversion Gemeinde.
Dank meiner Frau Frances, die sich viele Monate lang „Aber, Schatz, ich arbeite noch am Buch“ anhören musste, statt des üblichen „Aber, Schatz ich bearbeite noch E-Mail“. Ich weiß nicht, woher sie all die Geduld nimmt. Sie ist der perfekte Ausgleich für mich.
Dank meiner Verwandtschaft und meinen Freunden für ihre aufrichtige Ermutigung, obwohl sie kein tatsächliches Interesse an der Materie hatten. (Sie wissen schon, diejenigen, die sagen „Oh, du hast ein Buch geschrieben?“, und wenn man ihnen erzählt, es sei ein Computerbuch, die Nase rümpfen.
Vielen Dank an meine engen Freunde, die aus mir einen sehr reichen Mann machen. Schaut mich nicht so an – Ihr wisst, wer Ihr seid.
Dank an meine Eltern für die perfekte Grundformatierung und dafür, dass sie unglaubliche Leitbilder sind. Dank an meine Kinder, für die Gelegenheit, dieses weiterzugeben.
Einen riesigen Dank an meine Frau Marie dafür, dass sie so unglaublich verständnisvoll, unterstützend und vor allem so geduldig ist. Dank an meinen Bruder Eric, der mich vor langer Zeit als erster an die Programmierung unter UNIX herangeführt hat. Dank an meine Mutter und Großmutter für ihre Unterstützung; ganz zu schweigen davon, dass sie ein Weihnachtsfest ertragen mussten, an dem ich nach Hause kam und sofort meinen Kopf hinter dem Laptop versteckte, um am Buch zu arbeiten.
An Mike und Ben: Es war ein Vergnügen, mit Euch am Buch zu arbeiten. Verdammt, es ist eine Freude mit Euch auf der Arbeit zusammenzuarbeiten.
Dank an alle in der Subversion-Gemeinde und der Apache Software Foundation, dafür, dass ihr mich in euren Bann gezogen habt. Kein Tag vergeht, ohne dass ich irgendetwas von mindestens einem von Euch lerne.
Schließlich Dank an meinen Großvater, der mir immer sagte „Freiheit bedeutet Verantwortung“. Ich muss dem voll und ganz zustimmen.
Besonderen Dank an Amy, meiner besten Freundin und Ehefrau seit mehr als zehn unglaublichen Jahren, für ihre Liebe und geduldige Unterstützung, dafür, dass sie sich mit den langen Nächten abfand und gnädig die Versionskontrollprozesse ertrug, die ich ihr aufbürdete. Keine Sorge, Liebling – binnen kurzer Zeit wirst du eine TortoiseSVN-Expertin sein.
Gavin, du kannst jetzt die Hälfte der Worte in diesem Buch selber lesen; leider liefert die andere Hälfte die Schlüsselkonzepte. Tut mir Leid, Aidan – ich habe keine Möglichkeit gefunden, Disney/Pixar-Figuren in diesen Text einzuarbeiten. Aber Daddy liebt Euch beide und kann kaum erwarten, Euch das Programmieren beizubringen.
Mutter und Vater, Dank für Eure stetige Unterstützung und Begeisterung. Schwiegereltern, Dank für dasselbe plus Eure sagenhafte Tochter.
Hut ab vor Shep Kendall, der mir als erster die Welt der
Computer eröffnete; Ben Collins-Sussman, mein Reiseführer
durch die Open-Source-Welt; Karl Fogel – Du
bist mein .emacs
; Greg
Stein, für überquellendes praktisches Programmierwissen; und Brian
Fitzpatrick – dafür, dass Du diese Schreiberfahrung mit
mir teilst. Vor all den vielen Leuten, von denen ich ständig
etwas neues aufnehme – lasst weiter etwas fallen!
Schließlich, vor demjenigen, der perfekt kreative Exzellenz demonstriert – Dank an Dich.
Subversion ist ein freies/Open-Source Versionskontrollsystem. Das bedeutet, Subversion verwaltet Dateien und Verzeichnisse und die Änderungen an ihnen im Lauf der Zeit. Das erlaubt Ihnen, alte Versionen Ihrer Daten wiederherzustellen oder die Geschichte der Änderungen zu verfolgen. Unter diesem Blickwinkel denken viele Leute bei einem Versionskontrollsystem an eine Art „Zeitmaschine“.
Subversion kann netzwerkübergreifend arbeiten, was die Benutzung durch Menschen an verschiedenen Computern ermöglicht. Auf einer bestimmten Ebene fördert die Fähigkeit unterschiedlicher Personen dieselbe Menge an Daten bearbeiten und verwalten zu können die Zusammenarbeit. Ohne auf einen einzigen Kanal, über den alle Änderungen abgewickelt werden müssen, beschränkt zu sein, kann das Vorankommen beschleunigt werden. Und weil die Arbeit versioniert ist, braucht nicht befürchtet zu werden, dass die Qualität bei Verlust dieses Kanals geopfert wird – falls irgendeine falsche Änderung an den Daten gemacht wird, kann man sie einfach zurücknehmen.
Manche Versionskontrollsysteme sind auch Software-Konfigurationsmanagement-Systeme. Diese Systeme sind maßgeschneidert, um ganze Verzeichnisbäume mit Quellcode zu verwalten und verfügen über viele Merkmale, die spezifisch für Software-Entwicklung sind – etwa das Verstehen von Programmiersprachen oder das Bereitstellen von Werkzeugen zum Bauen von Software. Jedoch gehört Subversion nicht zu diesen Systemen. Es ist ein allgemeines System, das verwendet werden kann, um alle möglichen Sammlungen von Dateien zu verwalten. Für Sie mag es sich dabei um Quellcode handeln – für andere mag es dabei um alles von Einkaufslisten bis zu digitalen Videomischungen und weit darüber hinaus gehen.
Falls Sie ein Anwender oder Systemadministrator sind und den Einsatz von Subversion erwägen, sollte die erste Frage, die Sie sich stellen, sein: "Ist es das richtige Werkzeug für die Aufgabe?" Subversion ist ein fantastischer Hammer, achten Sie jedoch darauf, dass Sie nicht jedes Problem als einen Nagel sehen.
Falls Sie alte Datei- und Verzeichnisversionen aufbewahren, sie eventuell wiedererwecken müssen, oder Protokolle darüber auswerten möchten, wie sie sich im Lauf der Zeit geändert haben, ist Subversion das genau passende Werkzeug für Sie. Subversion ist auch geeignet, wenn Sie mit mehreren Leuten gemeinsam (üblicherweise über das Netz) an Dokumenten arbeiten und verfolgen müssen, wer welche Änderung gemacht hat. Deshalb wird Subversion so oft in Softwareentwicklungsumgebungen eingesetzt – die Arbeit in einem Entwicklerteam ist von Natur aus eine soziale Tätigkeit und Subversion vereinfacht die Zusammenarbeit mit anderen Programmierern. Natürlich ist die Benutzung von Subversion nicht umsonst zu bekommen: es kostet administrativen Aufwand. Sie müssen ein Daten-Repository verwalten, das die Informationen und ihre gesamte Geschichte speichert, und Sie müssen sich gewissenhaft um Sicherheitskopien kümmern. Wenn Sie täglich mit den Daten arbeiten, werden Sie sie nicht auf die gleiche Art kopieren, verschieben, umbenennen oder löschen können wie gewohnt. Stattdessen müssen Sie dafür Subversion verwenden.
Unter der Annahme, dass Ihnen die zusätzlichen Arbeitsabläufe nichts ausmachen, sollten Sie trotzdem sicher sein, dass Sie Subversion nicht für die Lösung eines Problems verwenden, das andere Werkzeuge besser lösen könnten. Zum Beispiel wird Subversion, weil es die Daten an alle Beteiligten verteilt, als generisches Verteilsystem missbraucht. Manchmal wird Subversion zum Verteilen von umfangreichen Bildersammlungen, digitaler Musik oder Softwarepaketen verwendet. Das Problem damit ist, dass sich diese Art Daten für gewöhnlich überhaupt nicht verändert. Die Sammlung selber wächst stetig, jedoch werden die einzelnen Dateien der Sammlung nicht verändert. In diesem Fall ist die Benutzung von Subversion zu viel des Guten.[2] Es gibt einfachere Werkzeuge, die hervorragend Daten replizieren, ohne dabei Änderungen mitzuverfolgen, etwa rsync oder unison.
Anfang 2000 begann CollabNet, Inc. (http://www.collab.net) Entwickler zu suchen, die einen Ersatz für CVS schreiben sollten. CollabNet bietet eine Software-Suite namens CollabNet Enterprise Edition (CEE) für die Zusammenarbeit an, die auch eine Komponente für Versionskontrolle beinhaltet. Obwohl CEE ursprünglich CVS als Versionskontrollsystem verwendete, waren die Einschränkungen von CVS von Anfang an offensichtlich, und CollabNet war sich bewusst, dass letztendlich etwas Besseres gefunden werden musste. Unglücklicherweise war CVS der de-facto Standard in der Open-Source-Welt geworden, hauptsächlich deshalb, weil es nichts Besseres gab, zumindest nicht unter einer freien Lizenz. Also beschloss CollabNet, ein vollständig neues Versionskontrollsystem zu schreiben, welches die grundlegenden Ideen von CVS beibehalten, jedoch die Fehler und Fehlentwicklungen vermeiden sollte.
Im Februar 2000 nahmen sie Verbindung mit Karl Fogel auf, dem Autor von Open Source Development with CVS (Coriolis, 1999), und fragten ihn, ob er an diesem neuen Projekt mitarbeiten wolle. Zufälligerweise besprach Karl bereits einen Entwurf für ein neues Versionskontrollsystem mit seinem Freund Jim Blandy. Im Jahr 1995 gründeten die beiden Cyclic Software, eine CVS-Beratungsfirma, und sie benutzten, obwohl sie die Firma später verkauften, bei ihrer täglichen Arbeit immer noch CVS. Ihre Enttäuschung über CVS veranlasste Jim, sorgfältig über bessere Möglichkeiten zur Verwaltung versionierter Daten nachzudenken. Er hatte sich nicht nur bereits den Namen „Subversion“ ausgedacht, sondern auch den grundsätzlichen Entwurf der Subversion-Datenablage. Als CollabNet rief, stimmte Karl sofort der Mitarbeit am Projekt zu, und Karl gelang es, dass sein Arbeitgeber Red Hat Software ihn praktisch auf unbestimmte Zeit dem Projekt spendete. CollabNet stellte Karl und Ben Collins-Sussman ein und der detaillierte Entwurfsprozess begann im Mai. Dank einiger Stupser von Brian Behrendorf und Jason Robbins von CollabNet sowie Greg Stein (zu dieser Zeit als unabhängiger Entwickler aktiv im der WebDAV/DeltaV Spezifikationsprozess), zog Subversion schnell eine Gemeinde aktiver Entwickler an. Es stellte sich heraus, dass viele Leute dieselben enttäuschenden Erfahrungen mit CVS gemacht hatten und nun die Gelegenheit begrüßten, etwas daran zu ändern.
Das ursprüngliche Designteam einigte sich auf einige einfache Ziele. Sie wollten kein Neuland in Versionskontrollmethodik betreten, sondern einfach CVS reparieren. Sie beschlossen, dass Subversion dieselben Merkmale und dasselbe Entwicklungsmodell wie CVS haben solle, wobei die Fehler von CVS aber nicht noch einmal gemacht werden sollten. Und obwohl es nicht als ein hundertprozentiger Ersatz für CVS gedacht war, sollte es dennoch ähnlich genug sein, so dass ein leichter Wechsel für einen CVS-Anwender möglich wäre.
Nach vierzehn Monaten Programmierung wurde Subversion am 31. August 2001 „selbstbewirtend“, d.h., die Subversion-Entwickler hörten auf, CVS für den Quellcode von Subversion zu verwenden und benutzten stattdessen Subversion.
Obwohl CollabNet das Projekt startete und immer noch einen großen Batzen der Arbeit finanziert (sie zahlen die Gehälter einiger Vollzeit-Subversion-Entwickler), läuft Subversion wie die meisten Open-Source-Projekte, geführt von einer Anzahl lockerer, transparenter Regeln, die die Meritokratie fördern. Die Urheberrechtslizenzen von CollabNet sind einvernehmlich mit den Debian Free Software Guidelines. Mit anderen Worten: Jeder darf Subversion nach Belieben herunterladen, ändern und weitergeben; es bedarf hierzu keinerlei Zustimmung durch CollabNet oder sonst jemanden.
Abbildung 1, „Die Architektur von Subversion“ illustriert einen „kilometerhohen“ Blick auf das Design von Subversion.
An einem Ende ist das Repository von Subversion, das die gesamten versionierten Daten enthält. Am anderen Ende ist das Subversion-Client-Programm, das die lokale Spiegelung von Teilen dieser versionierten Daten verwaltet („Arbeitskopien“ genannt). Zwischen den entgegengesetzten Enden befinden sich mehrere Wege über verschiedene Repository-Zugriffsschichten. Einige dieser Pfade gehen über Computernetzwerke und über Netzwerkserver, die dann auf das Repository zugreifen. Andere lassen das Netz links liegen und greifen direkt auf das Repository zu.
Sobald es installiert ist, hat Subversion eine Anzahl verschiedener Teile. Was folgt, ist ein schneller Überblick was Sie bekommen. Lassen Sie sich nicht beunruhigen, falls die kurzen Beschreibungen Sie dazu veranlassen, sich am Kopf zu kratzen – es gibt in diesem Buch jede Menge weiterer Seiten, die dem Ziel gewidmet sind, diese Verwirrung zu lindern.
Das Kommandozeilenprogramm
Ein Programm, das den Zustand einer Arbeitskopie (durch Revisionen der vorliegenden Objekte) berichtet
Ein Werkzeug zur direkten Untersuchung eines Subversion-Repositorys
Ein Werkzeug zum Erstellen, Verändern oder Reparieren eines Repositorys
Ein Plug-In-Modul für den Apache-HTTP-Server, wird benötigt, um das Repository über ein Netzwerk verfügbar zu machen
Ein spezielles Server-Programm, dass als Hintergrundprozess laufen oder von SSH aufgerufen werden kann; eine weitere Möglichkeit, das Repository über ein Netzwerk verfügbar zu machen.
Ein Programm zum Filtern von Subversion-Repository-Dump-Streams
Ein Programm zum inkrementellen Spiegeln eines Repositorys über ein Netzwerk
Die erste Auflage dieses Buchs wurde 2004 herausgegeben, kurz nachdem Subversion die 1.0 erreicht hatte. Innerhalb der nächsten vier Jahre wurden fünf neue größere Versionen von Subversion freigegeben, die Fehler beseitigten und neue Features einführten. Während wir es schafften, die Online-Version dieses Buches aktuell zu halten, sind wir begeistert davon, dass die zweite Auflage von O'Reilly nun Subversion bis Release 1.5 behandelt, ein großer Meilenstein für das Projekt. Hier ist eine schnelle Zusammenfassung der größeren Änderungen seit Subversion 1.0. Beachten Sie, dass es keine komplette Liste ist; um alle Details zu sehen, besuchen Sie die Subversion-Website bei http://subversion.tigris.org.
Release 1.1 führte FSFS ein, eine Repository-Speicheroption, die auf Dateien basiert. Obwohl das Berkeley-DB-Backend immer noch weitverbreitet ist und unterstützt wird, ist FSFS mittlerweile wegen der niedrigen Einstiegshürde und des minimalen Wartungsbedarfs die Standard-Auswahl für neu erzeugte Repositorys. Ebenfalls kam mit diesem Release die Möglichkeit, symbolische Links unter Versionskontrolle zu stellen, das automatische Maskieren von URLs und eine sprachabhängige Benutzerschnittstelle.
Mit Release 1.2 konnten serverseitige Sperren auf Dateien erzeugt und somit der Commit-Zugriff für bestimmte Ressourcen serialisiert werden. Während Subversion immer noch grundsätzlich ein gleichzeitiges Versionskontrollsystem ist, können bestimmte Arten binärer Dateien (z.B. Kunstobjekte) nicht zusammengeführt werden. Die Sperrmöglichkeit stillt den Bedarf, solche Ressourcen zu versionieren und zu schützen. Zusammen mit dem Sperren kam auch eine vollständige WebDAV-Auto-Versionierungs-Implementierung, die es erlaubt, Subversion-Repositorys als Netzwerkverzeichnisse einzuhängen. Schließlich begann Subversion 1.2 einen neuen, schnelleren binären Differenzalgorithmus zu verwenden, um alte Versionen von Dateien zu komprimieren und hervorzuholen.
Release 1.3 brachte pfadbasierte Autorisierungskontrolle für den svnserve-Server, was einem Merkmal entsprach, das vorher nur im Apache-Server vorzufinden war. Der Apache-Server wiederum bekam einige neue eigene Logging-Features, und die Subversion-API-Bindings für andere Sprachen machten auch große Sprünge vorwärts.
Release 1.4 führte ein völlig neues Werkzeug – svnsync – ein, um eine Einbahn-Replizierung von Repositorys über das Netz vornehmen zu können. Größere Teile der Arbeitskopie-Metadaten wurden überarbeitet, so dass nicht mehr XML benutzt wurde (was sich in erhöhter Geschwindigkeit auf Client-Seite niederschlug), während das Berkeley-DB-Repository-Backend die Fähigkeit erhielt, sich nach einem Server-Crash automatisch wiederherzustellen.
Release 1.5 brauchte viel länger als vorige Releases, doch das Hauptfeature war gigantisch: Halbautomatische Verfolgung des Verzweigens und Zusammenführens. Dies war eine riesige Wohltat für Anwender und schob Subversion weit jenseits der Fähigkeiten von CVS und in die Reihen kommerzieller Mitbewerber wie Perforce und Clearcase. Subversion 1.5 führte auch eine große Anzahl anderer, benutzerorientierter Features ein, wie die interaktive Auflösung von Dateikonflikten, partielle Checkouts, client-seitige Verwaltung von Änderungslisten, eine starke neue Syntax für External-Definitionen und SASL-Authentifizierungsunterstützung für den svnserve-Server.
Inhaltsverzeichnis
Das Kapitel ist eine kurze, lockere Einführung in Subversion. Wenn Sie noch nicht mit Versionskontrolle zu tun hatten, dann ist dieses Kapitel genau für Sie. Wir besprechen die grundlegenden Konzepte von Versionskontrolle und arbeiten uns in die Richtung von Subversion und dessen spezifischen Ideen und zeigen einfache Beispiele zur Anwendung.
Obwohl die Beispiele in diesem Kapitel Leute zeigen, die gemeinsam an Quellcode arbeiten, sei daran erinnert, dass Subversion alle möglichen Arten von Datensammlungen verwalten kann – es beschränkt sich nicht darauf, Entwicklern zu helfen.
Subversion ist ein zentralisiertes System zur gemeinsamen Nutzung von Informationen. In seinem Kern ist ein Repository ein zentraler Speicher von Daten. Das Repository speichert Informationen in Form eines Dateisystembaumes, typischerweise eine Hierarchie von Dateien und Verzeichnissen. Eine beliebige Anzahl von Clients verbinden sich mit dem Repository und lesen oder schreiben diese Dateien. Durch den Schreibvorgang, macht ein Client Informationen für andere verfügbar. Durch den Lesevorgang bekommt der Client Informationen von anderen zur Verfügung gestellt. Abbildung 1.1, „Ein typisches Client/Server System“ verdeutlicht das.
So, warum ist das interessant? Bis zu diesem Punkt hört sich das wie die Definition eines typischen File-Servers an. Und tatsächlich, das Repository ist eine Art von File-Server, aber nicht von der Art, die Sie kennen. Was das Subversion-Repository so speziell macht ist, dass es sich jede Änderung merkt, die jemals hineingeschrieben wurde. Jede Änderung an jeder Datei und auch Änderungen am Verzeichnisbaum selbst, wie z.B. das Hinzufügen, Löschen und Umstrukturieren von Dateien und Verzeichnissen.
Wenn ein Client Daten vom Repository liest, bekommt der Client üblicherweise nur die letzte Version des Dateisystem-Baumes zu sehen. Der Client hat aber auch die Möglichkeit, vorherige Zustände des Dateibaumes anzuschauen. Zum Beispiel kann ein Client somit die Frage stellen: „Was beinhaltete das Verzeichnis am letzten Mittwoch?“ und „Wer war die Person, die als letztes die Datei geändert hat und welche Änderungen hat sie gemacht?“. Diese Art von Fragen sind die Grundlage eines Versionskontrollsystems, Systeme, die dazu entwickelt wurden, um die Änderungen an Daten über die Zeit hin aufzuzeichnen.
Die zentrale Aufgabe eines Versionskontrollsystems ist es, die Zusammenarbeit beim Editieren gemeinsam benutzter Daten zu ermöglichen. Jedoch verwenden unterschiedliche Systeme auch unterschiedliche Strategien, um dies zu ermöglichen. Aus einer Reihe von Gründen ist es wichtig, diese Unterschiede zu verstehen. Erstmal hilft es dabei, bestehende Versionskontrollsysteme zu vergleichen und gegenüberzustellen, falls Ihnen andere Systeme begegnen, die Subversion ähneln. Darüber hinaus wird es Ihnen helfen, Subversion effektiver zu benutzen, da Subversion selbst eine Reihe unterschiedlicher Arbeitsweisen unterstützt.
Alle Versionskontrollsysteme haben alle die gleichen fundamentalen Probleme zu lösen: Wie soll es Anwendern erlaubt werden Informationen zu teilen aber Sie davor bewahren, sich gegenseitig auf die Fße zu treten? Es ist allzu einfach die Änderungen eines anderen im Repository zu überschreiben?
Stellen Sie sich einmal folgendes Abbildung 1.2, „The problem to avoid“Szenario vor: Zwei Kollegen, Harry und Sally, haben sich entschieden, die gleiche Datei zur gleichen Zeit zu bearbeiten. Harry speichert seine Änderungen zuerst im Repository, es ist aber möglich, dass Sally nur einige Augenblicke später mit ihrer Datei seine überschreibt. Harrys Änderungen der Datei sind zwar nicht für immer verloren (da das System jede Änderung aufzeichnet), aber alle seine Änderungen sind in Sallys später gespeicherter Version der Datei nicht vorhanden, da Sally diese Änderungen noch gar nicht kannte. Das heißt, dass Harrys Arbeit doch verloren ist, zumindest in der neuesten Version der Datei und das nur durch einen Zufall. Eine solche Situation wollen wir auf alle Fälle vermeiden.
Viele Versionskontrollsysteme verwenden ein Sperren - Ändern - Entsperren-Modell um zu verhindern, dass verschiedene Autoren sich gegenseitig die Änderungen löschen. Bei diesem Modell erlaubt das Repository nur jeweils einem Programmierer den Zugriff auf eine Datei. Harry müsste also die Datei sperren, ehe er anfängt, seine Änderungen einzugeben. Wenn Harry die Datei gesperrt hat, kann Sally sie nicht ebenfalls sperren und daher auch nichts ändern. Sie kann die Datei in der Zeit nur lesen und darauf warten, dass Harry mit seiner Arbeit fertig ist und die Datei entsperrt. Abbildung 1.3, „Die Sperren - Ändern - Entsperren - Lösung veranschaulicht diese einfache Möglichkeit“
Abbildung 1.3. Die Sperren - Ändern - Entsperren - Lösung veranschaulicht diese einfache Möglichkeit
Das Problem bei einem Sperren - Ändern - Entsperren - Modell liegt in seinen Beschränkungen, die oft zu schier unüberwindlichen Hindernissen führen können.
Das Sperren kann zu administrativen Problemen führen. Vielleicht sperrt Harry eine Datei und vergisst dann, sie zu entsperren. In der Zwischenzeit sind Sally, die ebenfalls Änderungen an dieser Datei durchführen will, die Hände gebunden. Und dann geht Harry in Urlaub. Nun muss Sally sich an einen Administrator wenden, um die Datei entsperrt zu bekommen. Das Ergebnis sind unnötige Verzögerungen und vergeudete Zeit.
Das Sperren kann zu einer unnötigen Serialisierung führen. Was ist, wenn Harry z. B. den Anfang einer Textdatei bearbeiten will, während Sally einfach nur das Ende ändern möchte? Diese Änderungen würden sich überhaupt nicht gegenseitig beeinflussen und könnten problemlos gleichzeitig durchgeführt werden, vorausgesetzt, sie würden anschließend vernünftig zusammengefasst. Es gibt in dieser Situation keinen Grund, der Reihe nach zu arbeiten.
Das Sperren kann zu einem falschen Gefühl von Sicherheit führen. Angenommen Harry sperrt und bearbeitet Datei A, während Sally gleichzeitig Änderungen an Datei B durchführt. Was ist, wenn A und B voneinander abhängig sind und die jeweiligen Änderungen nicht kompatibel sind? Plötzlich funktioniert das Zusammenspiel zwischen A und B nicht mehr. Das System des Sperrens hat dieses Problem nicht verhindert, doch hat es fälschlicherweise zu einem Gefühl der Sicherheit geführt. Es ist leicht, sich vorzustellen, dass Harry und Sally der Meinung waren, dass jeder von ihnen eine eigenständige, voneinander unabhängige Änderung durchgeführt hat und dass das Sperren dazu geführt hat, dass sie ihre inkompatiblen Änderungen nicht vorher miteinander besprochen haben. Sperren ist oft ein Ersatz für echte Kommunikation.
Subversion, CVS und viele andere Versionskontrollsysteme benutzen eine „Kopieren – Ändern – Zusammenfassen“ — Version als Alternative zum Sperren. In diesem Modell erschafft jeder User sich eine eigene Arbeitskopie der im Repository vorhandenen Dateien und Verzeichnisse. Dann können die User gleichzeitig und unabhängig voneinander ihre jeweiligen Änderungen eingeben und speichern. Am Ende werden dann alle Einzelkopien zu einer neuen, aktuellen Version zusammengefasst. Das Versionskontrollsystem hilft oft bei dieser Zusammenfassung, aber letztlich ist der Mensch dafür verantwortlich, das es korrekt abläuft.
Hier ist ein Beispiel: Harry und Sally haben sich jeweils eine eigene Arbeitskopie des im Repository vorhandenen Projektes geschaffen. Beide arbeiten nun am selben File A innerhalb ihrer jeweiligen Kopien. Sally speichert ihre Version zuerst im Repository ab. Wenn Harry später ebenfalls versucht, seine Änderungen zu speichern, informiert ihn das Repository, das sein File A nicht mehr aktuell ist. Das bedeutet, dass seitdem er sich seine Kopie erschaffen hat, sind irgendwelche Änderungen aufgetreten. Also bittet Harry seinen Client darum, diese neuen Änderungen in seine Arbeitskopie des File A einzuarbeiten. Die Möglichkeit besteht, dass Sallys Änderungen mit seinen nicht überlappen, wenn er also alle Änderungen eingearbeitet hat, kann er seine Arbeitskopie zurück in das Repository speichern. Die Abbildungen Abbildung 1.4, „„Kopieren – Ändern – Zusammenfassen“ - Lösung“ und Abbildung 1.5, „„Kopieren – Ändern – Zusammenfassen“ - Lösung (Fortsetzung)“ zeigen diesen Proczess.
Was aber passiert, wenn Sallys Änderungen mit Harrys kollidieren? Diese Situation wird Konflikt genannt und ist normalerweise kein allzugroßes Problem. Wenn Harry Sallys Änderungen in seine Datei einpflegen lassen will, werden in seiner Datei die miteinander in Konflikt stehenden Änderungen gekennzeichnet, er kann sämtliche Änderungen sehen und manuell zwischen ihnen wählen. Das Programm löst solche Konfliktsituationen nicht automatisch, nur Menschen sind in der Lage, die Probleme zu erkennnen und die nötigen intelligenten Änderungen durchzuführen. Wenn Harry die Konfliktsituationen — vielleicht nach einer kurzen Diskussion mit Sally — gelöst hat, kann er seine Datei problemlos ins Repository speichern.
Dieses Kopieren – Ändern – Zusammenfassen - Modell (engl. copy-modify-merge model) klingt vielleicht ein wenig chaotisch, in der Praxis aber läuft es völlig glatt. Die einzelnen User können parallel arbeiten, ohne einander in die Quere zu kommen oder unnötig warten zu müsssen. Wenn sie an den selben Dateien arbeiten, zeigt es sich meistens, dass ihre jeweiligen Änderungen einander überhaupt nicht stören, wirkliche Konflikte sind selten. Und die Zeit, die es beansprucht, eine solche Konfliktsituation zu lösen, ist meist wesentlich kürzer als der Zeitverlust, der durch das Sperren auftritt.
Am Ende läuft alles auf einen kritischen Faktor hinaus. Die Kommunikation zwischen den Usern. Wenn diese Kommunikation eher spärlich abläuft, häufen sich sowohl semantische als auch syntaktische Konflikte. Kein System kann User dazu zwingen, vernünftig miteinander zu kommnunizieren und kein System kann semantische Konflikte erkennen. Also hat es auch keinen Sinn, sich in dem falschen Gefühl von Sicherheit zu wiegen, dass das Sperren Konflikte irgendwie vermeiden könnte. In der Praxis verringert das System des Sperrens mehr als andere die Produktivität.
Es ist an der Zeit, sich vom Abstrakten zum Konkreten zu bewegen. In diesem Abschnitt werden wir echte Beispiele zur Benutzung von Subversion zeigen.
Das ganze Buch hindurch verwendet Subversion URLs, um Dateien und Verzeichnisse in Subversion-Repositorys zu identifizieren. Meistens benutzen diese URLs die Standardsyntax, die es erlaubt, Servernamen und Portnummern als Teil des URL zu spezifizieren:
$ svn checkout http://svn.example.com:9834/repos …
Allerdings gibt es einige bemerkenswerte Feinheiten, wie
Subversion mit URLs umgeht. Beispielsweise dürfen URLs, die
die file://
-Zugriffsmethode enthalten (für
lokale Repositorys verwendet), gemäß Konvention entweder
den Servernamen localhost
oder gar keinen
Servernamen enthalten:
$ svn checkout file:///var/svn/repos … $ svn checkout file://localhost/var/svn/repos …
Darüber hinaus müssen Benutzer des
file://
Schemas auf Windows-Plattformen
eine inoffizielle „Standard“-Syntax verwenden
falls auf Repositorys auf derselben Maschine aber auf einem
anderen Laufwerk zugegriffen werden soll. Beide der
folgenden URL-Pfad-Syntaxen funktionieren, wobei
X
das Laufwerk ist, wo das Repository
liegt:
C:\> svn checkout file:///X:/var/svn/repos … C:\> svn checkout "file:///X|/var/svn/repos" …
Bei der zweiten Syntax muss der URL in Anführungsstriche eingeschlossen werden, damit der senkrechte Strich nicht als Pipe-Symbol interpretiert wird. Beachten Sie auch, dass in einem URL Schrägstriche verwendet werden, obwohl es unter Windows üblich ist, für Pfade umgekehrte Schrägstriche zu verwenden.
Sie können die file://
URLs von Subversion
nicht in einem normalen Web-Browser auf die Art und
Weise verwenden wie andere file://
URLs. Falls Sie versuchen, einen file://
URL in einem gewöhnlichen Web-Browser anzusehen, wird der
Inhalt der Datei von der angegebenen Stelle direkt aus dem
Dateisystem gelesen und angezeigt. Allerdings befinden sich
die Daten von Subversion in einem virtuellen Dateisystem
(siehe „Repository Layer“), und
der Browser wird nicht mit diesem Dateisystem umzugehen
wissen.
Zuletzt sei noch angemerkt, dass der Subversion-Client, wie ein Web-Browser, nötigenfalls automatisch URLs umwandelt. Falls zum Beispiel in einem URL Leerzeichen oder Großbuchstaben vorkommen wie hier:
$ svn checkout "http://host/path with space/project/españa"
wird Subversion die unsicheren Zeichen umwandeln, als ob Sie
$ svn checkout http://host/path%20with%20space/project/espa%C3%B1a
geschrieben hätten.
Falls ein URL Leerzeichen beinhalten sollte, stellen Sie sicher, das der URL in Anführungszeichen gesetzt wird, damit die Shell alles als ein Argument für das svn Programm behandelt.
Sie haben schon über Arbeitskopien gelesen; nun werden wir zeigen, wie der Subversion-Client sie erzeugt und benutzt.
Eine Subversion-Arbeitskopie ist ein gewöhnlicher Verzeichnisbaum auf Ihrem lokalen System, der eine Ansammlung von Dateien enthält. Sie können diese Dateien nach belieben bearbeiten, und wenn es sich um Quelltexte handelt, können Sie hieraus Ihr Programm auf die übliche Weise compilieren. Ihre Arbeitskopie ist Ihr privater Arbeitsbereich: nie wird Subversion weder die Änderungen von anderen einpflegen, noch Ihre eigenen Änderungen anderen zur Verfügung stellen, bis Sie es ausdrücklich dazu auffordern. Sie können sogar mehrere Arbeitskopien desselben Projektes haben.
Nachdem Sie einige Änderungen an den Dateien Ihrer Arbeitskopie gemacht und sichergestellt haben, dass sie funktionieren, stellt Ihnen Subversion Befehle zur Verfügung, um Ihre Änderungen den anderen, die an Ihrem Projekt mitarbeiten, „publik“ zu machen (indem es ins Repository schreibt). Wenn die anderen ihre Änderungen veröffentlichen, stellt Ihnen Subversion Befehle zur Verfügung, um diese Änderungen in Ihr Arbeitsverzeichnis einzupflegen (indem es aus dem Repository liest).
Eine Arbeitskopie verfügt darüber hinaus über einige
zusätzliche Dateien, die von Subversion erzeugt und gepflegt
werden, um es bei diesen Befehlen zu unterstützen.
Insbesondere enthält jedes Verzeichnis Ihrer Arbeitskopie ein
Unterverzeichnis namens .svn
, auch
bekannt als das Verwaltungsverzeichnis
der Arbeitskopie. Die Dateien in jedem Verwaltungsverzeichnis
helfen Subversion dabei, zu erkennen, welche Dateien
unveröffentlichte Änderungen enthalten und welche Dateien
hinsichtlich der Arbeit anderer veraltet sind.
Oft enthält ein typisches Subversion-Repository die Dateien (oder den Quelltext) für verschiedene Projekte; für gewöhnlich ist jedes Projekt ein Unterverzeichnis im Dateisystembaum des Repositorys. Bei dieser Anordnung entspricht die Arbeitskopie eines Benutzers gewöhnlich einem bestimmten Unterverzeichnis des Repositorys.
Nehmen wir zum Beispiel an, Sie haben ein Repository, das
zwei Software-Projekte beinhaltet, paint
und
calc
. Jedes Projekt ist in einem eigenen
Hauptverzeichnis abgelegt, wie in Abbildung 1.6, „Das Dateisystem des Repositorys“ dargestellt.
Um eine Arbeitskopie zu erhalten, muss zunächst irgendein
Teilbaum des Repositorys ausgecheckt
werden(check out). (Der Begriff check
out hört sich an, als habe es etwas mit dem
Sperren oder Reservieren von Ressourcen zu tun, hat es aber
nicht; es erzeugt lediglich eine private Kopie des Projektes
für Sie.) Wenn Sie zum Beispiel /calc
auschecken, bekommen Sie eine Arbeitskopie wie diese:
$ svn checkout http://svn.example.com/repos/calc A calc/Makefile A calc/integer.c A calc/button.c Ausgecheckt, Revision 56. $ ls -A calc Makefile button.c integer.c .svn/
Die Liste der A
s am linken Rand zeigt
an, dass Subversion Ihrer Arbeitskopie eine Anzahl von
Objekten hinzufügt (Add). Sie haben nun eine persönliche
Kopie des Verzeichnisses /calc
im
Repository, mit einem zusätzlichen
Eintrag – .svn
– das, wie bereits
erwähnt, die besonderen Informationen enthält, die Subversion
benötigt.
Angenommen, Sie nehmen Änderungen an
button.c
vor. Da sich das Verzeichnis
.svn
den ursprünglichen
Änderungszeitpunkt und den Inhalt der Datei merkt, kann
Subversion erkennen, dass Sie die Datei verändert haben.
Trotzdem veröffentlicht Subversion Ihre Änderungen solange
nicht, bis Sie es ausdrücklich hierzu auffordern. Der Vorgang
des Veröffentlichens von Änderungen über das Repository ist
gemeinhin bekannter als commit (oder
check in).
Um Ihre Änderungen anderen gegenüber zu veröffentlichen, können Sie den Subversion-Befehl svn commit verwenden:
$ svn commit button.c -m "Tippfehler in button.c korrigiert" Sende button.c Übertrage Daten . Revision 6 übertragen.
Nun sind Ihre Änderungen an button.c
dem
Repository überstellt, mitsamt einer Notiz, die Ihre Änderung
beschreibt (nämlich, dass Sie einen Tippfehler beseitigt
haben). Wenn eine andere Benutzerin eine Arbeitskopie von
/calc
auscheckt, wird sie Ihre
Änderungen in der letzten Version der Datei sehen
können.
angenommen, Sie haben eine Mitarbeiterin, Sally, die eine
Arbeitskopie von /calc
gleichzeitig mit
Ihnen ausgecheckt hat. Wenn Sie Ihre Änderung an
button.c
committen, bleibt Sallys
Arbeitskopie unverändert; Subversion ändert Arbeitskopien nur
auf Wunsch des Benutzers.
Um ihr Projekt auf den neuesten Stand zu bringen, kann Sally Subversion dazu auffordern, ihre Arbeitskopie zu aktualisieren, indem sie den Befehl svn update verwendet. Das bringt sowohl Ihre als auch alle anderen Änderungen die committet wurden seit sie ausgecheckt hatte in ihre Arbeitskopie.
$ pwd /home/sally/calc $ ls -A Makefile button.c integer.c .svn/ $ svn update U button.c Aktualisiert zu Revision 57.
Die Ausgabe des svn update Befehls
zeigt, dass Subversion den Inhalt von
button.c
aktualisiert hat (Update).
Beachten Sie, dass Sally nicht angeben musste, welche Dateien
zu aktualisieren sind; Subversion benutzt die Informationen
aus dem .svn
Verzeichnis und
darüber hinaus weitere Informationen im Repository, um zu
entscheiden, welche Dateien auf den neuesten Stand gebracht
werden müssen.
Ein svn commit veröffentlicht Änderungen an einer beliebigen Anzahl von Dateien und Verzeichnissen als eine einzige atomare Transaktion. In Ihrer Arbeitskopie können Sie Dateiinhalte ändern, Dateien und Verzeichnisse erzeugen, löschen, umbenennen und kopieren und dann den gesamten Umfang der Änderungen als atomare Transaktion durch ein svn commit in das Repository einbringen.
Eine atomare Transaktion bedeutet: entweder es gehen alle Änderungen in das Repository oder keine. Angesichts von Programmabstürzen, Systemabstürzen, Netzproblemen oder anderer Benutzeraktionen hält Subversion an dieser Atomizität fest.
Jedes Mal wenn das Repository ein Commit annimmt, wird ein neuer Zustand des Dateisystem-Baums erzeugt, der Revision genannt wird. Jeder Revision wird eine einmalige natürliche Zahl zugewiesen, die um eins größer ist als die Vorgänger-Revision. Die anfängliche Revision eines frisch erzeugten Repositorys bekommt die Nummer 0 und besteht lediglich aus einem leeren Wurzelverzeichnis.
Abbildung 1.7, „Das Repository“ zeigt, wie man sich das Repository vorstellen kann. Stellen Sie sich eine Reihe von Revisionsnummern vor, die bei 0 startet und von links nach rechts wächst. Jede Revisionsnummer hat einen Dateisystem-Baum unter sich hängen, der ein „Schnappschuss“ des Repositorys nach einem Commit ist.
Es ist wichtig zu beachten, dass eine Arbeitskopie nicht immer genau einer Revision im Repository zugeordnet werden kann; sie kann Dateien aus verschiedenen Revisionen beinhalten. Nehmen wir z.B. an, Sie checken sich eine Arbeitskopie einer Datei aus einem Repository aus, deren neueste Revision 4 ist:
calc/Makefile:4 integer.c:4 button.c:4
In diesem Augenblick entspricht Ihre Arbeitskopie exakt
der Revision im Repository. Sie machen jetzt allerdings eine
Änderung an button.c
und bringen diese
Änderung mit einem Commit ins Repository. Angenommen, dass
keine weiteren Commits vorgenommen wurden, wird Ihr Commit die
Revision 5 im Repository erzeugen, und Ihre Arbeitskopie sieht
so aus:
calc/Makefile:4 integer.c:4 button.c:5
Angenommen, zu diesem Zeitpunkt macht Sally einen Commit
für eine Änderung an integer.c
und
erzeugt Revision 6. Wenn Sie svn update
verwenden, um Ihre Arbeitskopie zu aktualisieren, sieht sie so
aus:
calc/Makefile:6 integer.c:6 button.c:6
Sallys Änderung an integer.c
erscheint in Ihrer Arbeitskopie, und Ihre Änderung ist immer
noch in button.c
. In diesem Beispiel ist
der Text von Makefile
in den Revisionen
4, 5 und 6 identisch, jedoch markiert Subversion die
Arbeitskopie von Makefile
mit Revision 6,
um zu zeigen, dass es noch aktuell ist. Wenn Sie also ein
sauberes Update von der Wurzel Ihrer Arbeitskopie her machen,
sollte sie im Allgemeinen genau einer Revision im Repository
entsprechen.
Für jede Datei eines Arbeitsverzeichnis merkt sich
Subversion zwei essentielle Informationen im
.svn/
-Verwaltungsbereich:
Auf welcher Revision Ihre Arbeitsdatei aufbaut (das wird die Arbeitsrevision der Datei genannt)
Ein Zeitstempel, der festhält, wann die lokale Kopie das letzte Mal vom Repository aktualisiert wurde.
Mit diesen Informationen kann Subversion durch Kommunikation mit dem Repository feststellen, in welchem der folgenden Zustände sich eine Arbeitsdatei befindet:
Die Datei im Arbeitsverzeichnis ist unverändert, und keinerlei Änderungen an der Datei sind seit der Arbeitsrevision an das Repository übergeben worden. Ein svn commit der Datei würde nichts machen, und ein svn update der Datei auch nicht.
Die Datei wurde im Arbeitsverzeichnis geändert, und keinerlei Änderungen an der Datei sind seit der letzten Aktualisierung an das Repository übergeben worden. Es gibt lokale Änderungen, die noch nicht an das Repository übergeben worden sind, so dass ein svn commit der Datei Ihre Änderungen erfolgreich veröffentlichen würde, und ein svn update der Datei nichts tun würde.
Die Datei wurde im Arbeitsverzeichnis nicht geändert, jedoch im Repository. Die Datei sollte aktualisiert werden, damit sie bezüglich der letzten öffentlichen Revision aktuell ist. Ein svn commit der Datei würde nichts machen, und ein svn update der Datei würde die letzten Änderungen in Ihre Arbeitskopie einbringen.
Die Datei wurde sowohl im Arbeitsverzeichnis als auch im Repository geändert. Ein svn commit der Datei würde mit einem „out-of-date“ Fehler abbrechen. Die Datei sollte erst aktualisiert werden; ein svn update Befehl würde versuchen, die öffentlichen mit den lokalen Änderungen zusammenzuführen. Wenn Subversion diese Zusammenführung nicht plausibel automatisch durchführen kann, wird die Auflösung des Konflikts dem Benutzer überlassen.
Das hört sich an, als müsse man jede Menge mitverfolgen, aber der svn status Befehl zeigt Ihnen den Zustand jedes Objektes in Ihrer Arbeitskopie. Weitergehende Informationen zu diesem Befehl finden Sie unter „Verschaffen Sie sich einen Überblick über Ihre Änderungen“.
Als allgemeingültiges Prinzip versucht Subversion, so flexibel wie möglich zu sein. Eine besondere Ausprägung der Flexibilität ist die Fähigkeit, eine Arbeitskopie bestehend aus Dateien und Verzeichnissen mit einer Mischung unterschiedlicher Revisionsnummern zu haben. Unglücklicherweise neigt diese Flexibilität dazu, eine Anzahl neuer Benutzer zu verwirren. Wenn Sie das vorangegangene Beispiel, das gemischte Revisionen vorgestellt hat, verwirrte, zeigen wir hier eine Einführung warum es diese Möglichkeit gibt und wie sie verwendet wird.
Eine der grundlegenden Regeln von Subversion ist, dass eine Aktion, die in das Repository schreibt keine Aktion zur Folge hat, die aus dem Repository liest und umgekehrt. Wenn Sie bereit sind, neue Änderungen an das Repository zu übergeben, heißt das noch lange nicht, dass Sie auch die Änderungen anderer haben möchten. Und wenn Sie noch an Änderungen arbeiten, sollte svn update elegant die Änderungen aus dem Repository mit Ihren Änderungen zusammenführen anstatt Sie dazu zu zwingen, Ihre Änderungen zu veröffentlichen.
Der hauptsächliche Nebeneffekt dieser Regel ist, dass eine Arbeitskopie zusätzlich buchhalten muss, um sowohl gemischte Revisionen zu verfolgen als auch diese Mischung vertragen zu können. Die Tatsache, dass auch Verzeichnisse selbst versioniert sind, verkompliziert die Sache nur.
Nehmen wir zum Beispiel an, Ihre Arbeitskopie besteht
komplett aus Revision 10. Sie bearbeiten die Datei
foo.html
und führen ein svn
commit aus, das die Revision 15 im Repository
erzeugt. Nach dem erfolgreichen Commit würden viele neue
Benutzer erwarten, dass die gesamte Arbeitskopie auf
Revision 15 stehe, was aber nicht der Fall ist! Alle
möglichen Änderungen können sich zwischen Revision 10 und 15
im Repository zugetragen haben. Der Client weiß nichts über
diese Änderungen im Repository, da Sie noch nicht
svn update aufgerufen haben, und
svn commit zieht keine Änderungen herein.
Wenn andererseits svn commit automatisch
Änderungen hereinziehen würde, könnte die gesamte
Arbeitskopie auf Revision 15 gebracht werden – doch dann
wäre die grundlegende Regel verletzt, dass Lesen und
Schreiben getrennte Aktionen sind. Deshalb ist das einzig
Sichere, das der Subversion-Client tun kann, die eine
Datei – foo.html
– als zur
Revision 15 gehörig zu kennzeichnen. Der Rest der
Arbeitskopie verbleibt bei Revision 10. Nur durch
svn update können die neuesten Änderungen
hereingezogen und die gesamte Arbeitskopie als
Revision 15 gekennzeichnet werden.
Tatsache ist, dass jedes Mal wenn
Sie svn commit aufgerufen haben, die
Arbeitskopie aus irgendeiner Mischung von Revisionen
besteht. Die Sachen, die Sie eben ins Repository gebracht
haben, werden mit höheren Revisionsnummern gekennzeichnet
als alles andere. Nach einigen Commits (ohne
zwischenzeitliche Updates) ist Ihre Arbeitskopie eine
Riesenmischung von Revisionen. Selbst wenn Sie die einzige
Person sind, die das Repository benutzt, werden sie dieses
Phänomen bemerken. Um Ihre Mischung aus Arbeitsrevisionen
untersuchen zu können, verwenden Sie den Befehl svn
status mit der --verbose
-Option
(siehe „Verschaffen Sie sich einen Überblick über Ihre
Änderungen“ für
weitergehende Informationen).
Oft ist neuen Benutzern überhaupt nicht bewusst, das ihre Arbeitskopie gemischte Revisionen beinhaltet. Das kann zur Verwirrung führen, weil viele Client-Programme empfindlich auf die Revision des Objektes reagieren, das sie untersuchen. Beispielsweise wird der svn log-Befehl verwendet, um die Historie der Änderungen einer Datei oder eines Verzeichnisses darzustellen (siehe „Erzeugung einer Liste der Änderungsgeschichte“). Wenn der Benutzer diesen Befehl auf ein Objekt in der Arbeitskopie anwendet, erwartet er, die gesamte Historie des Objektes zu sehen. Wenn jedoch die Arbeitsrevision des Objektes ziemlich alt ist (oftmals weil lange Zeit kein svn update aufgerufen wurde), wird die Historie der älteren Version des Objekts angezeigt.
Wenn Ihr Projekt hinreichend komplex ist, werden Sie entdecken, dass es manchmal ganz nett sein kann, Teile Ihrer Arbeitskopie zurückzudatieren (oder auf eine ältere Version als die vorliegende zu aktualisieren); wie das gemacht wird, wird in Kapitel 2, Grundlegende Benutzung gezeigt. Vielleicht möchten Sie eine ältere Version eines Teilmoduls in einem Unterverzeichnis testen, oder Sie möchten herausbekommen, wann ein Fehler das erste Mal in einer Datei auftauchte. Dies ist der „Zeitmaschinen“-Aspekt eines Versionskontrollsystems – die Eigenschaft, die es ermöglicht, irgendeinen Teil Ihrer Arbeitskopie zeitlich nach vorne oder nach hinten zu verschieben.
Wie auch immer Sie gemischte Revisionen in Ihrer Arbeitskopie verwenden, diese Flexibilität hat ihre Grenzen.
Erstens kann die Löschung einer Datei oder eines Verzeichnisses nicht an das Repository übergeben werden, wenn die Datei oder das Verzeichnis nicht ganz aktuell ist. Falls eine neuere Version im Repository existiert, wird Ihr Löschversuch abgelehnt, um zu vermeiden, dass Sie versehentlich Änderungen löschen, die Sie noch nicht gesehen haben.
Zweitens können Sie keine Änderungen an Metadaten eines Verzeichnisses an das Repository übergeben, wenn das Verzeichnis nicht ganz aktuell ist. In Kapitel 3, Advanced Topics werden Sie lernen, wie man „Propertys“ an Objekte hängt. Die Arbeitskopie eines Verzeichnisses definiert eine bestimmte Menge von Einträgen und Propertys, so dass eine Property-Änderung an einem veralteten Verzeichnis Propertys zerstören kann, die Sie noch nicht gesehen haben.
In diesem Kapitel haben wir eine Anzahl fundamentaler Konzepte von Subversion behandelt:
Wir haben die Begriffe zentrales Repository, Arbeitskopie und Reihe von Revisionsbäumen des Repositorys eingeführt.
Wir haben einige einfache Beispiele gesehen, wie zwei Mitarbeiter Subversion verwenden können, um gegenseitig Änderungen auszutauschen, indem das „kopieren-verändern-zusammenführen“-Modell benutzt wird.
Wir haben ein wenig darüber geredet, wie Subversion Informationen in einer Arbeitskopie verfolgt und verwaltet.
An dieser Stelle sollten Sie eine gute Vorstellung haben, wie Subversion ganz allgemein arbeitet. Mit diesem Kenntnisstand sollten Sie in der Lage sein, das nächste Kapitel anzugehen, das ein detaillierter Rundgang durch die Befehle und Eigenschaften von Subversion ist.
Inhaltsverzeichnis
Nun kommen wir zu den Details der Benutzung von Subversion. Bis Sie das Ende dieses Kapitels erreicht haben, werden Sie in der Lage sein, alle Aufgaben zu erledigen, die sich bei der normalen täglichen Arbeit mit Subversion stellen. Sie werden damit beginnen, Ihre Dateien in Subversion einzupflegen, gefolgt von einem initialen Checkout Ihres Codes. Dann werden wir bei unserem Rundgang zeigen, wie Änderungen gemacht und diese Änderungen untersucht werden. Sie werden auch sehen, wie Sie die Änderungen anderer in Ihre Arbeitskopie bringen, untersuchen, und sich durch eventuell auftretende Konflikte arbeiten können.
Beachten Sie jedoch, dass dieses Kapitel nicht als erschöpfende Liste aller Befehle von Subversion gedacht ist – es ist eher eine Einführung in die gebräuchlichsten Aufgaben von Subversion, denen Sie begegnen werden. Dieses Kapitel setzt voraus, dass Sie Kapitel 1, Grundlegende Konzepte gelesen und verstanden haben und dass Sie mit dem allgemeinen Subversion-Modell vertraut sind. Für eine vollständige Referenz aller Befehle, siehe Kapitel 9, Subversion Complete Reference.
Bevor Sie weiter lesen: hier ist der wichtigste Befehl den
Sie benötigen, wenn Sie Subversion verwenden: svn
help. Der Subversion-Kommandozeilen-Client ist
selbst-dokumentierend – jederzeit erklärt Ihnen ein schnelles
svn help
die Syntax,
die Optionen und das Verhalten des Unterbefehls.Unterbefehl
$ svn help import import: Überträgt eine nicht versionierte Datei oder einen Dateibaum in das Projektarchiv. Aufruf: import [PFAD] URL Überträgt rekursiv eine Kopie des PFADes zur URL. Ohne Angabe von PFAD wird ».« angenommen. Übergeordnete Verzeichnisse werden soweit erforderlich im Projektarchiv angelegt. Falls PFAD ein Verzeichnis ist, wird dessen Inhalt direkt unterhalb der URL hinzugefügt. Nichtversionierbare Elemente wie Gerätedateien und Pipes werden ignoriert, falls --force angegeben wird. Gültige Optionen: -q [--quiet] : nichts oder nur Zusammenfassungen ausgeben -N [--non-recursive] : veraltet; versuchen Sie --depth=files oder --depth=immediates --depth PAR : begrenzt Operation durch Tiefe PAR (»empty«, »files«, »immediates« oder »infinity«) …
Sie können neue Dateien auf zweierlei Weisen in das Subversion-Repository bekommen: svn import und svn add. Wir werden svn import jetzt und svn add später in diesem Kapitel besprechen, wenn wir einen typischen Tag mit Subversion durchnehmen.
Mit dem svn import-Befehl kann ein unversionierter Verzeichnisbaum schnell in ein Repository kopiert werden, wobei benötigte Zwischenverzeichnisse nach Bedarf angelegt werden. svn import erfordert keine Arbeitskopie und pflegt Ihre Dateien sofort in das Repository ein. Typischerweise verwenden Sie diesen Befehl, wenn bereits ein Verzeichnisbaum besteht, den Sie aber in einem Subversion-Repository pflegen möchten. Zum Beispiel:
$ svnadmin create /var/svn/newrepos $ svn import mytree file:///var/svn/newrepos/some/project \ -m "Erstimport" Hinzufügen mytree/foo.c Hinzufügen mytree/bar.c Hinzufügen mytree/subdir Hinzufügen mytree/subdir/quux.h Revision 1 übertragen.
Im vorstehenden Beispiel wurde der Inhalt des
Verzeichnisses mytree
unter dem
Verzeichnis some/project
im Repository
abgelegt:
$ svn list file:///var/svn/newrepos/some/project bar.c foo.c subdir/
Beachten Sie, dass nach dem Import der Originalbaum nicht in eine Arbeitskopie umgewandelt wird. Vor Beginn der Arbeit müssen Sie noch svn checkout ausführen, um eine frische Arbeitskopie des Baums zu erhalten.
Obwohl die Flexibilität von Subversion es Ihnen erlaubt,
Ihr Repository nach Belieben aufzuteilen, empfehlen wir, ein
Verzeichnis trunk
für die
„Hauptlinie“ der Entwicklung, ein
Verzeichnis branches
für Branch-Kopien und
ein Verzeichnis tags
für
Tag-Kopien. Zum Beispiel:
$ svn list file:///var/svn/repos /trunk /branches /tags
In Kapitel 4, Verzweigen und Zusammenführen werden Sie mehr über Branches und Tags erfahren. Details über das Aufsetzen mehrerer Projekte finden Sie in „Aufbau des Repositorys“, und in „Planung der Organisation Ihres Repositorys“ lesen Sie mehr über Wurzelverzeichnisse von Projekten.
In den meisten Fällen werden Sie ein Subversion-Repository
zu nutzen beginnen, indem Sie einen
Checkout Ihres Projektes vornehmen. Das
Auschecken eines Repositorys erzeugt eine
„Arbeitskopie“ desselben auf Ihrem lokalen Rechner.
Diese Arbeitskopie umfasst die Revision HEAD
(die letzte Revision) des auf der Kommandozeile angegebenen
Subversion-Repositorys:
$ svn checkout http://svn.collab.net/repos/svn/trunk A trunk/Makefile.in A trunk/ac-helpers A trunk/ac-helpers/install.sh A trunk/ac-helpers/install-sh A trunk/build.conf … Ausgecheckt, Revision 8810.
Obwohl im vorangehenden Beispiel das Verzeichnis trunk
ausgecheckt
wird, können Sie genauso leicht irgendein tiefliegendes
Unterverzeichnis aus einem Repository auschecken, indem Sie das
Unterverzeichnis im URL beim Checkout angeben:
$ svn checkout \ http://svn.collab.net/repos/svn/trunk/subversion/tests/cmdline/ A cmdline/revert_tests.py A cmdline/diff_tests.py A cmdline/autoprop_tests.py A cmdline/xmltests A cmdline/xmltests/svn-test.sh … Ausgecheckt, Revision 8810.
Da Subversion ein copy-modify-merge-Modell (kopieren-ändern-zusammenführen) statt eines lock-modify-unlock-Modells (sperren-ändern-freigeben) verwendet (siehe „Versionierungsmodelle“), können Sie sofort damit beginnen, Änderungen an den Dateien und Verzeichnissen Ihrer Arbeitskopie vorzunehmen. Ihre Arbeitskopie ist wie jede beliebige andere Ansammlung aus Dateien und Verzeichnissen auf Ihrem System. Sie können sie bearbeiten, ändern, verschieben und sie sogar löschen und vergessen.
Obwohl sich Ihre Arbeitskopie „wie jede beliebige andere Ansammlung aus Dateien und Verzeichnissen auf Ihrem System“ verhält, können Sie zwar beliebig Dateien editieren, doch Sie müssen Subversion über alles andere was Sie tun in Kenntnis setzen. Wenn Sie z.B. ein Objekt in der Arbeitskopie kopieren oder verschieben möchten, sollten Sie svn copy oder svn move verwenden statt der Kopier- oder Verschiebebefehle Ihres Betriebssystems. Wir werden darauf später im Kapitel näher eingehen.
Sofern Sie nicht bereit sind, das Hinzufügen einer neuen Datei oder eines neuen Verzeichnisses oder Änderungen an bestehenden Objekten an das Repository zu übergeben, besteht keine Notwendigkeit, dem Subversion-Server mitzuteilen, dass Sie irgendetwas gemacht haben.
Obwohl Sie sicherlich eine Arbeitskopie mit dem Repository-URL als einziges Argument auschecken können, haben sie auch die Möglichkeit, ein Verzeichnis hinter dem Repository-URL anzugeben. Das erstellt Ihre Arbeitskopie in dem angegebenen Verzeichnis. Zum Beispiel:
$ svn checkout http://svn.collab.net/repos/svn/trunk subv A subv/Makefile.in A subv/ac-helpers A subv/ac-helpers/install.sh A subv/ac-helpers/install-sh A subv/build.conf … Ausgecheckt, Revision 8810.
Das legt Ihre Arbeitskopie in einem Verzeichnis namens
subv
ab anstatt in trunk
so wie wir es früher schon einmal gemacht haben. Das Verzeichnis
subv
wird angelegt, sofern es nicht bereits
vorhanden ist.
Wenn Sie eine Subversion-Operation ausführen, für die Sie sich authentifizieren müssen, speichert Subversion Ihre Zugangsdaten standardmäßig auf der Platte. Das geschieht zu Ihrer Annehmlichkeit, damit Sie bei künftigen Operationen nicht ständig Ihr Passwort eingeben müssen. Falls Sie wegen der Speicherung besorgt sein sollten, [3] können Sie das Zwischenspeichern entweder dauerhaft oder von Fall zu Fall abstellen.
Um das Passwort-Caching für einen bestimmten einmaligen
Befehl zu unterbinden, übergeben Sie die
--no-auth-cache
-Option auf der Kommandozeile.
Um das Caching dauerhaft abzustellen, können Sie der
Subversion-Konfigurationsdatei Ihres lokalen Rechners die Zeile
store-passwords = no
hinzufügen. Für
Details siehe „Client Credentials Caching“.
Da Subversion standardmäßig Zugangsdaten speichert
(sowohl den Benutzernamen als auch das Passwort), erinnert es
sich bequemerweise, wer Sie das letzte Mal waren, als Sie Ihre
Arbeitskopie modifizierten. Doch manchmal ist das nicht
hilfreich – besonders, wenn Sie in einer gemeinsam
benutzten Arbeitskopie arbeiten wie in einem
Konfigurationsverzeichnis oder im Dokumenten-Wurzelverzeichnis
eines Webservers. In diesem Fall brauchen Sie nur die
--username
-Option auf der Kommandozeile zu
übergeben und Subversion versucht, sich als dieser Benutzer zu
authentifizieren und wird Sie, wenn nötig, zur Eingabe eines
Passworts auffordern.
Subversion hat zahlreiche Features, Optionen und noch jede Menge Schnickschnack, aber für die tägliche Arbeit ist die Wahrscheinlichkeit groß, nur wenig davon zu benutzen. In diesem Abschnitt gehen wir durch die gebräuchlichsten Dinge, die Sie während des Tagesgeschäftes mit Subversion machen werden.
Der typische Arbeitszyklus sieht so aus:
Aktualisieren Sie Ihre Arbeitskopie.
svn update
Nehmen Sie Änderungen vor.
svn add
svn delete
svn copy
svn move
Untersuchen Sie Ihre Änderungen.
svn status
svn diff
Nehmen Sie eventuell einige Änderungen zurück.
svn revert
Lösen Sie Konflikte auf (arbeiten Sie die Änderungen anderer ein).
svn update
svn resolve
Bringen Sie Ihre Änderungen ins Repository.
svn commit
Wenn Sie in einem Projekt im Team zusammenarbeiten, sollten Sie Ihre Arbeitskopie aktualisieren, um die Änderungen zu bekommen, die die anderen Entwickler im Projekt seit Ihrer letzten Aktualisierung vorgenommen haben. Benutzen Sie svn update um Ihre Arbeitskopie synchron mit der letzten Revision im Repository zu bekommen:
$ svn update U foo.c U bar.c Aktualisiert zu Revision 2.
In diesem Fall sieht es so aus, dass jemand Änderungen
sowohl an foo.c
als auch an
bar.c
eingecheckt hat, seit Sie das letzte
Mal aktualisiert haben, und Subversion hat Ihre Arbeitskopie
aktualisiert, damit sie beide Änderungen enthält.
Wenn der Server über svn update
Änderungen an Ihre Arbeitskopie schickt, wird ein
Buchstabencode neben jedem Objekt angezeigt, um Ihnen
anzuzeigen, was Subversion gemacht hat, um die Arbeitskopie
auf den neuesten Stand zu bringen. Zur Bedeutung der
Buchstaben, rufen Sie svn help update
auf.
Nun können Sie loslegen und Änderungen an Ihrer Arbeitskopie vornehmen. Normalerweise ist es am einfachsten, sich für eine bestimmte Änderung (oder eine Menge von Änderungen) zu entscheiden, etwa ein neues Feature zu implementieren oder einen Fehler zu beseitigen usw. Die Subversion-Befehle, die Sie hierfür verwenden werden sind svn add, svn delete, svn copy, svn move und svn mkdir. Falls Sie jedoch größtenteils Dateien editieren, die bereits mit Subversion verwaltet werden, brauchen Sie keinen dieser Befehle, bis Sie die Änderungen committen.
Sie können zwei Arten von Änderungen an Ihrer Arbeitskopie vornehmen: Dateiänderungen und Verzeichnisbaumänderungen. Sie brauchen Subversion nicht mitzuteilen, dass Sie beabsichtigen, eine Datei zu ändern; nehmen Sie einfach die Änderungen mit Ihrem Texteditor, Textverarbeitungsprogramm, Grafikprogramm oder sonstigen Programm vor, wie Sie es gewohnt sind. Subversion stellt automatisch fest, welche Dateien sich geändert haben und behandelt dabei Binärdateien genauso einfach wie Textdateien – und genauso effizient. Für Änderungen am Verzeichnisbaum können Sie Subversion mitteilen, Dateien und Verzeichnisse zum geplanten Entfernen, Hinzufügen, Kopieren oder Verschieben „vorzumerken“. Diese Änderungen finden sofort in Ihrer Arbeitskopie statt, doch nichts wird dem Repository hinzugefügt oder daraus entfernt, bevor Sie die Änderungen committen.
Hier ist ein Überblick der fünf Subversion-Unterbefehle, die Sie am häufigsten benutzen werden, um Änderungen am Verzeichnisbaum vorzunehmen:
svn add foo
Die Datei, das Verzeichnis oder den symbolischen
Link foo
zum Hinzufügen in das
Repository vormerken. Wenn Sie das nächste Mal committen,
wird foo
ein Kind seines
Elternverzeichnisses. Beachten Sie, dass alles unterhalb
von foo
zum Hinzufügen vorgemerkt
wird, falls foo
ein Verzeichnis
ist. Falls Sie nur foo
selber
hinzufügen möchten, geben Sie die --depth
empty
-Option an.
svn delete foo
Die Datei, das Verzeichnis oder den symbolischen
Link foo
zum Löschen aus dem
Repository vormerken. foo
wird
sofort aus der Arbeitskopie entfernt, falls es eine
Datei oder ein Link ist. Falls foo
ein Verzeichnis ist, wird es nicht gelöscht, sondern zum
Löschen vorgemerkt. Wenn Sie Ihre Änderungen committen,
wird das gesamte Verzeichnis foo
aus der Arbeitskopie und dem Repository entfernt.
[4]
svn copy foo bar
Erzeuge ein neues Objekt bar
als Duplikat von foo
und merke
bar
automatisch zum Hinzufügen vor.
Wird beim nächsten Commit bar
dem
Repository hinzugefügt, wird die Historie der Kopie
mitaufgezeichnet (so wie sie ursprünglich in
foo
war). svn
copy erzeugt keine Zwischenverzeichnisse,
sofern nicht die Option --parents
angegeben wird..
svn move foo bar
Dieser Befehl macht genau das gleiche wie
svn copy foo bar; svn delete foo
.
D.h., bar
wird zum Hinzufügen als
Kopie von foo
und
foo
selbst zum Löschen vorgemerkt.
svn move erzeugt keine
Zwischenverzeichnisse, sofern nicht die Option
--parents
angegeben wird.
svn mkdir blort
Dieser Befehl macht genau das gleiche wie
mkdir blort; svn add blort
. D.h., ein
neues Verzeichnis namens blort
wird
angelegt und zum Hinzufügen vorgemerkt.
Sobald Sie mit Ihren Änderungen fertig sind, müssen Sie sie ins Repository bringen; bevor Sie das jedoch machen, ist es normalerweise eine gute Idee, sich die Änderungen noch einmal anzusehen. Dadurch, dass Sie die Änderungen noch einmal begutachten, können Sie eine genauere Log-Nachricht schreiben. Sie könnten auch feststellen, dass Sie versehentlich eine Datei geändert haben, und hier haben Sie die Möglichkeit, vor dem Commit die Änderung rückgängig zu machen. Zusätzlich bietet sich hierbei eine gute Gelegenheit, die Änderungen vor der Veröffentlichung noch einmal genau durchzugehen. Sie können sich mit svn status einen Überblick über Ihre Änderungen verschaffen und mit svn diff die Änderungen im Detail anzeigen lassen.
Subversion ist optimiert worden, um Ihnen bei dieser
Aufgabe zu helfen, und es ist in der Lage, viele Dinge zu tun,
ohne mit dem Repository kommunizieren zu müssen. Im Besonderen
enthält Ihre Arbeitskopie eine versteckte
„unveränderte“ Kopie jeder versionskontrollierten
Datei innerhalb des .svn
-Bereichs.
Deswegen kann Ihnen Subversion schnell zeigen, wie sich Ihre
bearbeiteten Dateien geändert haben, und es erlaubt Ihnen
sogar, Ihre Änderungen zurückzunehmen, ohne Verbindung mit dem
Repository aufnehmen zu müssen.
Um einen Überblick über Ihre Änderungen zu bekommen, werden Sie den svn status-Befehl verwenden. Wahrscheinlich werden Sie den Befehl svn status häufiger benutzen als alle anderen Subversion-Befehle.
Wenn Sie svn status ganz oben in
Ihrer Arbeitskopie aufrufen, werden alle Datei- und
Verzeichnisbaumänderungen erfasst, die Sie gemacht haben.
Hier sind einige Beispiele der häufigsten Statuscodes, die
svn status zurückgeben kann. (Beachten
Sie, dass der Text, der #
folgt, nicht
von svn status ausgegeben wird.)
? scratch.c # Datei ist nicht versionskontrolliert A stuff/loot/bloo.h # Datei ist zum Hinzufügen vorgemerkt C stuff/loot/lump.c # Datei hat Konflikte durch einen Update D stuff/fish.c # Datei ist zum Löschen vorgemerkt M bar.c # Der Inhalt von bar.c hat lokale Änderungen
In diesem Ausgabeformat zeigt svn status sechs Spalten mit Zeichen, gefolgt von mehreren Leerzeichen, gefolgt von einem Datei- oder Verzeichnisnamen an. Die erste Spalte gibt Aufschluss über den Zustand einer Datei oder eines Verzeichnisses und/oder des entsprechenden Inhalts.
A item
Die Datei, das Verzeichnis oder der symbolische
Link item
ist zum Hinzufügen in
das Repository vorgemerkt.
C item
Die Datei item
befindet sich
in einem Konfliktzustand. D.h., Änderungen, die vom
Server bei einer Aktualisierung empfangen wurden,
überlappen sich mit lokalen Änderungen, die Sie in
Ihrer Arbeitskopie haben (und konnten beim
Aktualisieren nicht automatisch aufgelöst werden). Sie
müssen den Konflikt auflösen, bevor Sie Ihre
Änderungen in das Repository committen können.
D item
Die Datei, das Verzeichnis oder der symbolische
Link item
ist zum Löschen im
Repository vorgemerkt.
M item
Der Inhalt der Datei item
ist geändert worden.
Wenn Sie einen speziellen Pfad an svn status übergeben, bekommen Sie nur Informationen über das Objekt alleine:
$ svn status stuff/fish.c D stuff/fish.c
svn status hat auch eine
--verbose
-Option (-v
),
die Ihnen den Zustand jedes Objektes in
der Arbeitskopie anzeigt, selbst wenn es sich nicht geändert
hat:
$ svn status -v M 44 23 sally README 44 30 sally INSTALL M 44 20 harry bar.c 44 18 ira stuff 44 35 harry stuff/trout.c D 44 19 ira stuff/fish.c 44 21 sally stuff/things A 0 ? ? stuff/things/bloo.h 44 36 harry stuff/things/gloo.c
Dies ist das „lange Format“ der Ausgabe von svn status. Die Buchstaben in der ersten Spalte bedeuten dasselbe wie vorher, jedoch zeigt die zweite Spalte die Arbeitsrevision des Objektes an. Die dritte und vierte Spalte zeigen die Revision der letzten Änderung an und wer es geändert hat.
Keiner der vorangegangenen Aufrufe von svn
status stellt eine Verbindung zum Repository
her – stattdessen werden die Metadaten im
Verzeichnis .svn
mit der Arbeitskopie
verglichen. Schließlich gibt es die
--show-updates
-Option (-u
),
die eine Verbindung zum Repository herstellt, und
Informationen darüber bereitstellt, was nicht mehr aktuell
ist:
$ svn status -u -v M * 44 23 sally README M 44 20 harry bar.c * 44 35 harry stuff/trout.c D 44 19 ira stuff/fish.c A 0 ? ? stuff/things/bloo.h Status bezogen auf Revision: 46
Beachten Sie die zwei Sternchen: Wenn Sie an dieser
Stelle svn update
aufrufen würden,
erhielten Sie Änderungen an README
und
trout.c
. Das gibt Ihnen einige sehr
wichtige Informationen – Sie müssen aktualisieren, um
die Änderungen auf dem Server an README
mitzubekommen, bevor Sie committen, oder das Repository wird
Ihren Commit ablehnen, da er nicht aktuell ist (mehr dazu
später).
svn status kann viel mehr Informationen über Dateien und Verzeichnisse in Ihrer Arbeitskopie anzeigen als wir hier gezeigt haben – für eine erschöpfende Beschreibung von svn status und dessen Ausgabe, siehe svn status.
Eine andere Möglichkeit, Ihre Änderungen zu untersuchen,
ist, den svn diff-Befehl zu verwenden.
Sie können genau herausfinden, wie sie
etwas geändert haben, indem Sie svn
diff
ohne Argumente aufrufen, das Ihnen
Dateiänderungen im unified-diff-Format
anzeigt:
$ svn diff Index: bar.c =================================================================== --- bar.c (revision 3) +++ bar.c (working copy) @@ -1,7 +1,12 @@ +#include <sys/types.h> +#include <sys/stat.h> +#include <unistd.h> + +#include <stdio.h> int main(void) { - printf("Sixty-four slices of American Cheese...\n"); + printf("Sixty-five slices of American Cheese...\n"); return 0; } Index: README =================================================================== --- README (revision 3) +++ README (working copy) @@ -193,3 +193,4 @@ +Note to self: pick up laundry. Index: stuff/fish.c =================================================================== --- stuff/fish.c (revision 1) +++ stuff/fish.c (working copy) -Welcome to the file known as 'fish'. -Information on fish will be here soon. Index: stuff/things/bloo.h =================================================================== --- stuff/things/bloo.h (revision 8) +++ stuff/things/bloo.h (working copy) +Here is a new file to describe +things about bloo.
Der svn diff-Befehl erzeugt diese
Ausgabe, indem er Ihre Arbeitsdateien mit den
„unveränderten“ Kopien im Cache innerhalb des
.svn
-Bereichs vergleicht. Dateien, die
zum Hinzufügen vorgemerkt sind, werden vollständig als
hinzugefügter Text dargestellt, und Dateien, die zum Löschen
vorgemerkt sind, werden vollständig als gelöschter Text
dargestellt.
Die Ausgabe wird im unified-diff-Format dargestellt.
D.h., gelöschte Zeilen werden mit einem vorangestellten
-
und hinzugefügte Zeilen mit einem
vorangestellten +
angezeigt.
svn diff gibt auch Dateinamen und
Offset-Informationen aus, die das patch-Programm
verwenden kann, so dass Sie „Patches“
erzeugen können, indem Sie die diff-Ausgabe in eine Datei
umleiten:
$ svn diff > patchfile
Zum Beispiel können Sie die Patch-Datei vor einem Commit an einen anderen Entwickler zur Kontrolle oder zum Testen schicken.
Subversion verwendet seinen eingebauten
diff-Algorithmus, der standardmäßig das unified-diff-Format
benutzt. Falls Sie die Ausgabe von diff in einem anderen
Format haben möchten, geben Sie ein externes diff-Programm
mit der --diff-cmd
-Option an, und übergeben
Sie ihm beliebige Flags mit der
--extensions
-Option (-x
).
Um z.B. lokale Unterschiede in der Datei
foo.c
im Kontext-Ausgabeformat anzeigen
zu lassen und dabei die Groß- und Kleinschreibung zu
ignorieren, könnten Sie svn diff --diff-cmd
/usr/bin/diff --extensions '-i' foo.c
aufrufen.
Angenommen, Sie stellen beim Ansehen der Ausgabe von svn diff fest, dass alle Änderungen, die Sie an einer bestimmten Datei gemacht haben, fehlerhaft waren. Vielleicht hätten Sie die Datei überhaupt nicht ändern sollen, oder es wäre einfacher, von Anfang an unterschiedliche Änderungen zu machen.
Dies ist die perfekte Gelegenheit, svn revert zu benutzen:
$ svn revert README Rückgängig gemacht: »README«
Subversion stellt die Datei wieder so her, wie sie vor der
Änderung war, indem sie mit der
„unveränderten“ Kopie aus dem Cache im
.svn
-Bereich überschrieben wird. Beachten
Sie aber auch, dass svn revert
jegliche vorgemerkten Operationen
rückgängig machen kann – z.B. könnten Sie sich
entscheiden, eine neue Datei erst gar nicht hinzufügen zu
wollen:
$ svn status foo ? foo $ svn add foo A foo $ svn revert foo Rückgängig gemacht: »foo« $ svn status foo ? foo
svn revert
hat genau denselben Effekt, wie
item
item
aus der Arbeitskopie zu
löschen und dann svn update -r BASE
item
aufzurufen. Allerdings hat
svn revert beim Rückgängigmachen einer
Datei einen merklichen Unterschied – es muss beim
Wiederherstellen der Datei nicht Verbindung mit dem
Repository aufnehmen.
Oder vielleicht haben Sie die Datei versehentlich aus der Versionsverwaltung gelöscht:
$ svn status README $ svn delete README D README $ svn revert README Rückgängig gemacht: »README« $ svn status README
Wir haben bereits gesehen, wie svn status
-u
Konflikte vorhersagen kann. Angenommen, Sie
starten svn update und einige interessante
Dinge passieren:
$ svn update U INSTALL G README Konflikt in »bar.c« entdeckt. Auswahl: (p) zurückstellen, (df) voller Diff, (e) editieren, (h) Hilfe für weitere Optionen:
Die Codes U
und
G
sind kein Grund zur
Beunruhigung; diese Dateien haben die Änderungen aus dem
Repository sauber aufgenommen. Die mit
U
markierten Dateien
enthielten keine lokalen Änderungen, wurden jedoch mit
Änderungen aus dem Repository
geU
pdatet. Das
G
steht für
merG
ed, was bedeutet, dass
die Datei zwar lokale Änderungen enthielt, die Änderungen aus
dem Repository sich aber nicht damit überschnitten
haben.
Die nächsten beiden Zeilen jedoch sind Teil eines Features
(neu in Subversion 1.5) namens interaktive
Konfliktauflösung. Das bedeutet, dass die
Änderungen vom Server sich mit Ihren eigenen überschneiden,
uns Sie nun die Gelegenheit haben, den Konflikt aufzulösen.
Die gebräuchlichsten Optionen werden angezeigt, aber alle
Optionen können sie sehen, wenn Sie
h
eintippen:
… (p) zurückstellen - den Konflikt erst später auflösen (df) voller Diff - alle Änderungen in der zusammengeführten Datei anzeigen (e) editieren - zusammengeführte Datei in einem Editor ändern (r) aufgelöst - akzeptieren der zusammengeführten Version der Datei (mf) volle eigene Datei - die eigene Version der kompletten Datei akzeptieren (ignorieren fremder Änderungen) (tf) volle fremde Datei - die fremde Version der kompletten Datei akzeptieren (verlieren eigener Änderungen) (l) starten - Starten eines externen Programms zur Konfliktauflösung (h) Hilfe - diese Liste anzeigen
Bevor wir im Detail erklären, was jede Option bedeutet, gehen wir noch mal eben die Optionen durch.
p
)ostponeDie Datei im Konfliktzustand lassen, um nach Abschluss der Aktualisierung die Konfliktauflösung durchzuführen.
d
)iffDie Unterschiede zwischen der Basisrevision und der Konfliktdatei im unified-diff-Format anzeigen.
e
)ditDie Konfliktdatei im bevorzugten Editor, wie in
der Umgebungsvariablen EDITOR
angegeben, öffnen.
r
)esolvedNach dem Bearbeiten einer Datei teilen Sie svn mit, dass Sie die Konflikte in der Datei aufgelöst haben und der aktuelle Inhalt übernommen werden soll.
m
)ine-(f
)ullDie neuen vom Server erhaltenen Änderungen verwerfen und nur Ihre lokalen Änderungen an der zu überprüfenden Datei verwenden.
t
)heirs-(f
)ullIhre lokalen Änderungen an der zu überprüfenden Datei verwerfen und nur die neuen vom Server erhaltenen Änderungen verwenden.
l
)aunchEin externes Programm zur Konfliktauflösung starten. Das setzt Vorbereitungen voraus.
h
)elpDie Liste aller bei der interaktiven Konfliktauflösung möglichen Befehle anzeigen.
Wir werden diese Befehle nun detaillierter behandeln, wobei sie nach Funktionalität gruppiert werden.
Bevor Sie entscheiden, wie Sie einen Konflikt beseitigen
wollen, wollen Sie wahrscheinlich genau sehen, worin der
Konflikt besteht, und benutzen hierfür den Befehl
diff (d
):
… Select: (p) postpone, (df) diff-full, (e) edit, (h)elp for more options : d --- .svn/text-base/sandwich.txt.svn-base Tue Dec 11 21:33:57 2007 +++ .svn/tmp/tempfile.32.tmp Tue Dec 11 21:34:33 2007 @@ -1 +1,5 @@ -Just buy a sandwich. +<<<<<<< .mine +Go pick up a cheesesteak. +======= +Bring me a taco! +>>>>>>> .r32 …
Die erste Zeile des diff-Inhalts zeigt den vorherigen
Inhalt der Arbeitskopie (die BASE
-Revision),
die nächste Zeile beinhaltet Ihre Änderung und
die letzte Zeile ist die Änderung, die soeben vom Server
empfangen worden ist (gewöhnlich die
HEAD
-Revision). Mit diesen Informationen
sind Sie bereit für den nächsten Schritt.
Es gibt vier verschiedene Wege, um Konflikte interaktiv aufzulösen – von denen Ihnen zwei erlauben, Änderungen selektiv zusammenzuführen und zu editieren und zwei, die es Ihnen erlauben, einfach eine Version der Datei auszuwählen und weiterzumachen.
Falls Sie eine beliebige Kombination Ihrer lokalen
Änderungen auswählen wollen, können Sie den
„edit“-Befehl (e
)
verwenden, um die Datei mit den Konfliktmarken manuell in
einem Texteditor (der durch die Umgebungsvariable
EDITOR
bestimmt wird) zu bearbeiten. Die
Datei händisch in Ihrem Lieblingseditor zu bearbeiten ist
eine Art Konflikte zu beseitigen, die sich einer ziemlich
schlichten Technik bedient (siehe „Manuelle Konfliktauflösung“ für einen
Beispieldurchgang), so dass manche Leute lieber feinste
Merge-Tools benutzen.
Um ein Merge-Tool benutzen zu können, müssen Sie
entweder die Umgebungsvariable SVN_MERGE
setzen oder die merge-tool-cmd
-Option in
Ihrer Subversion-Konfigurationsdatei definieren (siehe „Configuration Options“ für weitere Details).
Subversion übergibt vier Argumente an das Merge-Tool: die
BASE
-Revision der Datei, die
Dateirevision, die durch die Aktualisierung vom Server empfangen
wurde, die Dateirevision, die Ihre lokale Bearbeitung
beinhaltet und die zusammengeführte Kopie der Datei (die
Konfliktmarken enthält). Falls Ihr Merge-Tool die Argumente
in einer anderen Reihenfolge oder in einem anderen Format
erwartet, werden Sie ein Wrapper-Script schreiben müssen,
das von Subversion aufgerufen wird. Nachdem Sie die Datei
bearbeitet haben und zufrieden mit Ihren Änderungen sind,
können Sie Subversion mitteilen, dass für die bearbeitete
Datei kein Konflikt mehr besteht, indem sie den
„resolve“-Befehl (r
)
benutzen.
Falls Sie entscheiden, dass Sie keine Änderungen
zusammenführen brauchen, sondern lediglich eine der beiden
Dateiversionen akzeptieren wollen, können Sie entweder Ihre
Änderungen (auch „meine“) mit dem
„mine-full“-Befehl (mf
)
oder die der Anderen mit dem „theirs-full“-Befehl
(tf
) auswählen.
Das hört sich vielleicht an wie ein passender Abschnitt
zur Vermeidung von Ehestreitigkeiten, doch es geht immer
noch um Subversion; also lesen Sie weiter. Falls Sie eine
Aktualisierung vornehmen und ein Konflikt auftaucht, den Sie
nicht begutachten oder auflösen können, ermöglicht Ihnen das
Eingeben von p
die Konfliktauflösung
Datei für Datei aufzuschieben, wenn Sie svn
update
aufrufen. Falls Sie aktualisieren wollen,
ohne Konflikte aufzulösen, können Sie die
--non-interactive
-Option an svn
update übergeben, und jede Datei mit Konflikten
wird automatisch mit einem
C
gekennzeichnet.
Das C
bedeutet
c
onflict. Das heißt, dass
die Änderungen vom Server sich mit Ihren eigenen
überschneiden, und Sie nach Abschluss der Aktualisierung
manuell aus den Änderungen wählen müssen. Wenn Sie eine
Konfliktauflösung verschieben, macht svn
typischerweise drei Dinge, um Ihnen bei der
Konfliktauflösung zu helfen:
Subversion gibt ein
C
während der
Aktualisierung aus und merkt sich, dass die Datei in
einem Konfliktzustand ist.
Falls Subversion die Datei als geeignet zum
Zusammenführen ansieht, fügt es
Konfliktmarken – besondere
Zeichenketten, die die Konfliktregion begrenzen –
in die Datei ein, um die überlappenden Bereiche
besonders hervorzuheben. (Subversion verwendet das
svn:mime-type
-Property, um
festzustellen, ob sich die Datei kontextuell zeilenweise
zusammenführen lässt. Siehe „File Content Type“, um
mehr zu erfahren.)
Für jede Datei mit Konflikten stellt Subversion drei zusätzliche unversionierte Dateien in Ihre Arbeitskopie:
filename.mine
Dies ist Ihre Datei aus der Arbeitskopie bevor
Sie aktualisierten – d.h. ohne
Konfliktmarken. Diese Datei beinhaltet nur Ihre
letzten Änderungen. (Falls Subversion diese Datei
als nicht-zusammenführbar erachtet, wird die
.mine
-Datei nicht erstellt,
da sie identisch mit der Datei der Arbeitskopie
wäre.)
filename.rOLDREV
Dies ist die Datei, die die
BASE
-Revision war bevor Sie
Ihre Arbeitskopie aktualisiert haben; also die
Datei, die Sie ausgecheckt hatten, bevor Sie Ihre
letzten Änderungen machten.
filename.rNEWREV
Dies ist die Datei, die Ihr Subversion-Client
soeben vom Server erhalten hat als Sie Ihre
Arbeitskopie aktualisierten. Diese Datei
entspricht der HEAD
-Revision
des Repositorys.
Hierbei ist OLDREV
die
Revisionsnummer der Datei in Ihrem
Verzeichnis .svn
, und
NEWREV
ist die
Revisionsnummer von HEAD
im
Repository.
Beispielsweise ändert Sally die Datei
sandwich.txt
aus dem Repository. Harry
hat gerade diese Datei in seiner Arbeitskopie geändert und
eingecheckt. Sally aktualisiert Ihre Arbeitskopie vor dem
einchecken und bekommt einen Konflikt, den sie
verschiebt:
$ svn update Konflikt in »sandwich.txt« entdeckt. Auswahl: (p) zurückstellen, (df) voller Diff, (e) editieren, (h) Hilfe für weitere Optionen: p C sandwich.txt Aktualisiert zu Revision 2. $ ls -1 sandwich.txt sandwich.txt.mine sandwich.txt.r1 sandwich.txt.r2
An dieser Stelle erlaubt Subversion Sally
nicht, die Datei
sandwich.txt
an das Repository zu
übergeben, solange die drei temporären Dateien nicht
entfernt werden:
$ svn commit -m "Add a few more things" svn: Übertragen schlug fehl (Details folgen): svn: Übertragung abgebrochen: »/home/sally/svn-work/sandwich.txt« bleibt im Konflikt
Falls Sie eine Konfliktauflösung aufgeschoben haben,
müssen Sie den Konflikt auflösen, bevor Ihnen Subversion
erlaubt, Ihre Änderungen in das Repository einzustellen. Sie
werden dafür den svn resolve-Befehl mit
einem von mehreren Argumenten für die
--accept
-Option aufrufen.
Falls Sie die Dateiversion vor Ihren Änderungen haben
möchten, wählen Sie das
base
-Argument.
Falls Sie die Version möchten, die nur Ihre Änderungen
enthält, wählen Sie das
mine-full
-Argument.
Falls Sie die Version möchten, die Ihre letzte
Aktualisierung vom Server gezogen hat (und somit Ihre
Änderungen vollständig verwerfen wollen), wählen Sie das
Argument theirs-full
.
Wenn Sie jedoch frei aus Ihren Änderungen und den
Änderungen vom Server wählen möchten, führen Sie den
konfliktbehafteten Text „händisch“ zusammen
(indem Sie die Konfliktmarken in der Datei begutachten und
editieren) und wählen das
working
-Argument.
svn resolve entfernt die drei
temporären Dateien und akzeptiert die Version, die Sie mit
der --accept
-Option angeben. Subversion
betrachtet die Datei nun als nicht mehr
konfliktbehaftet:
$ svn resolve --accept working sandwich.txt Konflikt von »sandwich.txt« aufgelöst
Das manuelle Auflösen von Konflikten kann ganz schön einschüchternd sein, wenn Sie es das erste Mal versuchen; jedoch kann es mit etwas Übung so leicht werden, wie vom Fahrrad zu fallen.
Hier ist ein Beispiel. Aufgrund einer schlechten Absprache
bearbeiten Sie und Ihre Mitarbeiterin Sally gleichzeitig die
Datei sandwich.txt
. Sally übergibt
ihre Änderungen an das Repository, und sobald Sie versuchen,
Ihre Arbeitskopie zu aktualisieren, erhalten Sie einen
Konflikt und müssen sandwich.txt
bearbeiten, um den Konflikt aufzulösen. Zunächst wollen wir
uns die Datei einmal ansehen:
$ cat sandwich.txt Top piece of bread Mayonnaise Lettuce Tomato Provolone <<<<<<< .mine Salami Mortadella Prosciutto ======= Sauerkraut Grilled Chicken >>>>>>> .r2 Creole Mustard Bottom piece of bread
Die Zeichenketten aus Kleiner-als-Zeichen, Gleichheitszeichen und Größer-als-Zeichen sind Konfliktmarken und gehören nicht zu den eigentlichen Daten, die in Konflikt stehen. Im Allgemeinen werden Sie sicherstellen wollen, dass die Konflikte aus der Datei entfernt werden, bevor sie das nächste Mal einen Commit durchführen. Der Text zwischen den ersten beiden Marken besteht aus den Änderungen, die Sie im Konfliktbereich vorgenommen haben:
<<<<<<< .mine Salami Mortadella Prosciutto =======
Der Text zwischen der zweiten und der dritten Marke ist der Text aus Sallys Commit:
======= Sauerkraut Grilled Chicken >>>>>>> .r2
Für gewöhnlich werden Sie nicht einfach die Konfliktmarken mitsamt der Änderungen von Sally löschen wollen – sie wird furchtbar überrascht sein, wenn das Sandwich kommt und nicht das drauf ist, was sie wollte. Hier ist der Zeitpunkt gekommen, zu dem Sie zum Telefon greifen oder durch das Büro gehen und Sally erklären, dass man in einem italienischen Delikatessenladen kein Sauerkraut bekommt. [6] Sobald Sie sich über die einzucheckenden Änderungen einig sind, können Sie Ihre Datei bearbeiten und die Konfliktmarken entfernen:
Top piece of bread Mayonnaise Lettuce Tomato Provolone Salami Mortadella Prosciutto Creole Mustard Bottom piece of bread
Verwenden Sie jetzt svn resolve, und Sie sind bereit, Ihre Änderungen an das repository zu übergeben:
$ svn resolve --accept working sandwich.txt Konflikt von »sandwich.txt« aufgelöst $ svn commit -m "Mach weiter mit meinem Sandwich, vergiss Sallys Änderungen."
Beachten Sie, dass svn resolve, anders als die meisten anderen Befehle, die wir in diesem Kapitel behandeln, erwartet, dass Sie ausdrücklich alle Dateien aufzählen, deren Konflikt Sie beseitigt haben. Auf alle Fälle sollten Sie sorgfältig vorgehen und svn resolve nur verwenden, falls Sie sicher sind, den Konflikt in Ihrer Datei beseitigt zu haben – sobald die temporären Dateien entfernt sind, lässt Subversion zu, dass Sie die Datei in das Repository stellen, selbst wenn sie noch Konfliktmarken enthält.
Falls Sie mal bei der Bearbeitung der konfliktbehafteten Datei verwirrt sein sollten, können Sie jederzeit in den drei Dateien nachsehen, die Subversion für Sie in der Arbeitskopie bereitstellt – dazu gehört auch Ihre Datei vor der Aktualisierung. Sie können sogar ein Merge-Tool eines Drittanbieters verwenden, um diese drei Dateien zu untersuchen.
Falls Sie einen Konflikt erhalten und entscheiden, dass
Sie Ihre Änderungen verwerfen wollen, können Sie
svn resolve --accept theirs-full
aufrufen, und Subversion wird Ihre Änderungen ignorieren und
die temporären Dateien entfernen:CONFLICTED-PATH
$ svn update Konflikt in »sandwich.txt« entdeckt. Auswahl: (p) zurückstellen, (df) voller Diff, (e) editieren, (h) Hilfe für weitere Optionen: p C sandwich.txt Aktualisiert zu Revision 2. $ ls sandwich.* sandwich.txt sandwich.txt.mine sandwich.txt.r2 sandwich.txt.r1 $ svn resolve --accept theirs-full sandwich.txt Konflikt von »sandwich.txt« aufgelöst
Falls Sie sich entscheiden, Ihre Änderungen zu verwerfen und erneut mit der Bearbeitung zu beginnen (ob nach einem Konflikt oder sonst zu jeder Zeit), machen Sie einfach Ihre Änderungen rückgängig:
$ svn revert sandwich.txt Rückgängig gemacht: »sandwich.txt« $ ls sandwich.* sandwich.txt
Beachten Sie, dass Sie beim Rückgängigmachen einer konfliktbehafteten Datei nicht svn resolve zu verwenden brauchen.
Endlich! Sie haben die Bearbeitung abgeschlossen, Sie haben alle Änderungen vom Server eingearbeitet, und Sie sind bereit, Ihre Änderungen an das Repository zu übergeben.
Der Befehl svn commit schickt all Ihre
Änderungen zum Repository. Wenn Sie eine Änderung übergeben,
müssen Sie einen Protokolleintrag
erstellen, der die Änderung beschreibt. Dieser Eintrag wird mit
der von Ihnen erzeugten neuen Revision verknüpft. Wenn Ihr
Eintrag kurz ist, können Sie ihn mit der Option
--message
(oder -m
) in der
Kommandozeile angeben:
$ svn commit -m "Anzahl Käsescheiben korrigiert." Sende sandwich.txt Übertrage Daten . Revision 3 übertragen.
Falls Sie jedoch Ihren Protokolleintrag während der Arbeit
erstellen möchten, können Sie Subversion mitteilen, sich den
Eintrag aus einer Datei zu holen, indem Sie den Dateinamen mit
der Option --file
(-F
)
angeben:
$ svn commit -F logmsg Sende sandwich.txt Übertrage Daten . Revision 4 übertragen.
Sollten Sie vergessen, entweder die Option
--message
oder die
--file
-Option anzugeben, startet Subversion
automatisch Ihren Lieblingseditor (siehe die Information zu
editor-cmd
in „Config“), damit Sie
einen Protokolleintrag erstellen können.
Wenn Sie gerade in Ihrem Editor einen Eintrag schreiben und sich entschließen, die Übergabe abzubrechen, können Sie einfach Ihren Editor beenden, ohne die Änderungen zu sichern. Falls Sie den Eintrag bereits gesichert haben sollten, löschen Sie einfach den Text, sichern Sie erneut und brechen dann ab:
$ svn commit Logmeldung unverändert oder nicht angegeben A)bbrechen, Weitermac)hen, E)ditieren: a $
Das Repository weiß nicht, ob Ihre Änderung im Ganzen einen Sinn ergeben, es ist ihm auch egal; es überprüft lediglich, ob nicht irgendjemand anderes irgendeine derselben Dateien geändert hat wie Sie, als Sie mal weggeschaut haben. Falls jemand das gemacht hat, wird die gesamte Übergabe mit einer Meldung fehlschlagen, dass eine oder mehrere Ihrer Dateien nicht mehr aktuell sind:
$ svn commit -m "Noch eine Regel hinzufügen" Sende rules.txt svn: Übertragen schlug fehl (Details folgen): svn: Datei »/rules.txt« ist veraltet …
(Der genaue Wortlaut dieser Fehlermeldung hängt vom verwendeten Netzwerkprotokoll und vom Server ab, doch die Bedeutung ist in allen Fällen gleich.)
Zu diesem Zeitpunkt müssen Sie svn
update
aufrufen, sich um eventuelle
Zusammenführungen oder Konflikte kümmern und die Übergabe
erneut versuchen.
Das deckt den grundlegenden Arbeitszyklus für die Verwendung von Subversion ab. Subversion bietet viele andere Möglichkeiten, die Sie benutzen können, um Ihr Repository und Ihre Arbeitskopie zu verwalten, doch der größte Teil Ihrer täglichen Arbeit mit Subversion wird lediglich die in diesem Kapitel behandelten Befehle berühren. Wir werden jedoch noch ein paar mehr Befehle behandeln, die Sie ziemlich oft verwenden werden.
Ihr Subversion-Repository ist wie eine Zeitmaschine. Es legt einen Eintrag für jede jemals übergebene Änderung an und erlaubt Ihnen, diese Geschichte durch die Untersuchung sowohl ehemaliger Datei- und Verzeichnisversionen als auch der begleitenden Metadaten zu erforschen. Mit einem einzigen Subversion-Befehl können Sie das Repository genauso auschecken (oder eine bestehende Arbeitskopie wiederherstellen), wie es zu einem beliebigen Zeitpunkt oder einer Revisionsnummer in der Vergangenheit war. Allerdings möchten Sie manchmal nur in die Vergangenheit spähen anstatt dorthin zu gehen.
Es gibt mehrere Befehle, die Sie mit historischen Daten aus dem Repository versorgen können:
Zeigt Ihnen grobe Informationen: Mit Revisionen verknüpfte Protokolleinträge zu Datum und Autor und welche Pfade sich in jeder Revision geändert haben.
Zeigt die Details einer bestimmten Änderung auf Zeilenebene
Holt eine Datei hervor wie sie mit einer bestimmten Revisionsnummer einmal ausgesehen hat und zeigt sie auf dem Bildschirm an
Zeigt die Dateien in einem Verzeichnis für eine gewünschte Revision an
Um Informationen über den Werdegang einer Datei oder eines Verzeichnisses zu bekommen, benutzen Sie den Befehl svn log. svn log versorgt Sie mit einem Eintrag, der Auskunft darüber gibt, wer Änderungen an einer Datei oder einem Verzeichnis gemacht hat, in welcher Revision die Änderung stattfand, zu welcher Zeit und welchem Datum die Revision entstand sowie – falls verfügbar – dem die Übergabe begleitenden Protokolleintrag:
$ svn log ------------------------------------------------------------------------ r3 | sally | 2008-05-15 23:09:28 -0500 (Thu, 15 May 2008) | 1 line include-Zeilen hinzugefügt und Anzahl der Käsescheiben korrigiert. ------------------------------------------------------------------------ r2 | harry | 2008-05-14 18:43:15 -0500 (Wed, 14 May 2008) | 1 line main()-Methoden hinzugefügt. ------------------------------------------------------------------------ r1 | sally | 2008-05-10 19:50:31 -0500 (Sat, 10 May 2008) | 1 line Erstimport ------------------------------------------------------------------------
Beachten Sie, dass die Protokolleinträge standardmäßig in
umgekehrter zeitlicher Reihenfolge
ausgegeben werden. Falls Sie eine andere Folge von Revisionen
in einer bestimmten Anordnung oder nur eine einzige Revision
sehen möchten, übergeben Sie die Option
--revision
(-r
):
$ svn log -r 5:19 # zeigt Protokolleintrag 5 bis 19 in chronologischer Reihenfolge $ svn log -r 19:5 # zeigt Protokolleintrag 5 bis 19 in umgekehrter Reihenfolge $ svn log -r 8 # zeigt Protokolleintrag für Revision 8
Sie können sich auch die Protokollgeschichte einer einzigen Datei oder eines einzigen Verzeichnisses ansehen. Zum Beispiel:
$ svn log foo.c … $ svn log http://foo.com/svn/trunk/code/foo.c …
Diese Befehle zeigen nur Protokolleinträge für die Revisionen, in der sich die Arbeitsdatei (oder URL) geändert hat.
Wenn Sie noch mehr Informationen über eine Datei oder ein
Verzeichnis benötigen, können Sie svn log
auch die Option --verbose
(-v
) mitgeben. Weil Ihnen Subversion erlaubt,
Dateien und Verzeichnisse zu kopieren und zu verschieben, ist
es wichtig, Pfadänderungen im Dateisystem
mitzuverfolgen. Daher beinhaltet bei dieser Option die Ausgabe
von svn log eine Liste veränderter Pfade in
einer Revision:
$ svn log -r 8 -v ------------------------------------------------------------------------ r8 | sally | 2008-05-21 13:19:25 -0500 (Wed, 21 May 2008) | 1 line Geänderte Pfade: M /trunk/code/foo.c M /trunk/code/bar.h A /trunk/code/doc/README Die Unterraumwinde gefrozzelt. ------------------------------------------------------------------------
svn log akzeptiert ebenfalls die Option
--quiet
(-q
), die den
Protokolleintrag unterdrückt. Zusammen mit der Option
--verbose
zeigt es nur die Namen der
geänderten Dateien an.
svn diff ist uns bereits begegnet – es zeigt Dateiunterschiede im unified-diff-Format; wir verwendeten es, um die lokalen Änderungen an unserer Arbeitskopie anzuzeigen, bevor wir sie dem Repository übergaben.
Tatsächlich stellt sich heraus, dass es drei verschiedene Verwendungsmöglichkeiten für svn diff gibt:
zum Untersuchen lokaler Änderungen
zum Vergleichen Ihrer Arbeitskopie mit dem Repository
zum Vergleichen von Revisionen im Repository
Wie wir gesehen haben, vergleicht der Aufruf von
svn diff
ohne Optionen die
Arbeitsdateien mit den zwischengespeicherten
„ursprünglichen“ Kopien im
.svn
-Bereich:
$ svn diff Index: rules.txt =================================================================== --- rules.txt (revision 3) +++ rules.txt (working copy) @@ -1,4 +1,5 @@ Be kind to others Freedom = Responsibility Everything in moderation -Chew with your mouth open +Chew with your mouth closed +Listen when others are speaking $
Wird eine einzelne Nummer mit --revision
(-r
) übergeben, wird die Arbeitskopie mit
der angegebenen Revision im Repository verglichen:
$ svn diff -r 3 rules.txt Index: rules.txt =================================================================== --- rules.txt (revision 3) +++ rules.txt (working copy) @@ -1,4 +1,5 @@ Be kind to others Freedom = Responsibility Everything in moderation -Chew with your mouth open +Chew with your mouth closed +Listen when others are speaking $
Werden zwei Revisionsnummern durch einen Doppelpunkt
getrennt mit --revision
(-r
) übergeben, werden die beiden
Revisionen direkt miteinander verglichen:
$ svn diff -r 2:3 rules.txt Index: rules.txt =================================================================== --- rules.txt (revision 2) +++ rules.txt (revision 3) @@ -1,4 +1,4 @@ Be kind to others -Freedom = Chocolate Ice Cream +Freedom = Responsibility Everything in moderation Chew with your mouth open $
Eine bequemere Möglichkeit, eine Revision mit der
Vorgänger-Revision zu vergleichen, bietet die Verwendung der
Option --change
(-c
):
$ svn diff -c 3 rules.txt Index: rules.txt =================================================================== --- rules.txt (revision 2) +++ rules.txt (revision 3) @@ -1,4 +1,4 @@ Be kind to others -Freedom = Chocolate Ice Cream +Freedom = Responsibility Everything in moderation Chew with your mouth open $
Zu guter Letzt können Sie Revisionen im Repository auch dann vergleichen, falls Sie gar keine Arbeitskopie auf Ihrem lokalen Rechner haben, indem Sie einfach den entsprechenden URL auf der Kommandozeile angeben:
$ svn diff -c 5 http://svn.example.com/repos/example/trunk/text/rules.txt … $
Wenn Sie svn cat und svn list verwenden, können Sie sich verschiedene Revisionen von Dateien und Verzeichnissen ansehen, ohne die Revision Ihrer Arbeitskopie ändern zu müssen. Tatsächlich brauchen Sie dafür nichteinmal eine Arbeitskopie.
Falls Sie eine frühere Version einer Datei untersuchen möchten und nicht notwendigerweise die Unterschiede zwischen zwei Dateien, können Sie svn cat verwenden:
$ svn cat -r 2 rules.txt Be kind to others Freedom = Chocolate Ice Cream Everything in moderation Chew with your mouth open $
Sie können die Ausgabe auch direkt in eine Datei umleiten:
$ svn cat -r 2 rules.txt > rules.txt.v2 $
Der Befehl svn list zeigt Ihnen, welche Dateien sich in einem Repository-Verzeichnis befinden, ohne die Dateien auf Ihren lokalen Rechner herunterladen zu müssen:
$ svn list http://svn.collab.net/repos/svn README branches/ clients/ tags/ trunk/
Falls Sie eine detailliertere Auflistung wünschen,
übergeben Sie die Option --verbose
(-v
), um eine Ausgabe ähnlich der folgenden
zu bekommen:
$ svn list -v http://svn.collab.net/repos/svn 20620 harry 1084 Jul 13 2006 README 23339 harry Feb 04 01:40 branches/ 21282 sally Aug 27 09:41 developer-resources/ 23198 harry Jan 23 17:17 tags/ 23351 sally Feb 05 13:26 trunk/
Die Spalten zeigen Ihnen die Revision, in der die Datei zuletzt geändert wurde, den Benutzer, der sie änderte, die Größe, falls es sich um eine Datei handelt, sowie den Namen des Objektes.
Der Befehl svn list
ohne
Argumente verwendet standardmäßig den
Repository-URL des aktuellen
Arbeitsverzeichnisses und nicht das
Verzeichnis der lokalen Arbeitskopie. Schließlich können
Sie, falls Sie eine Auflistung des lokalen Verzeichnisses
möchten, das einfache ls (oder irgendein
vernünftiges nicht-unixartiges Äquivalent) benutzen.
Zusätzlich zu den obigen Befehlen können Sie svn
update und svn checkout mit der
Option --revision
verwenden, um eine
vollständige Arbeitskopie „zeitlich
zurückzusetzen“:
[7]
$ svn checkout -r 1729 # Checkt eine neue Arbeitskopie von r1729 aus … $ svn update -r 1729 # Aktualisiert eine bestehende Arbeitskopie auf r1729 …
Viele Subversion-Neulinge versuchen das vorangehende svn update-Beispiel zu verwenden, um übergebene Änderungen „rückgängig“ zu machen, was allerdings nicht funktioniert, da Sie keine Änderungen übergeben können, die Sie durch das zeitliche Zurücksetzen einer Arbeitskopie erhalten haben, falls die geänderten Dateien neuere Revisionen haben. Siehe „Zurückholen gelöschter Objekte“ für eine Beschreibung, wie eine Übergabe „rückgängig“ gemacht wird.
Wenn Sie am Ende ein Release bauen und die Dateien aus
Subversion zu einem Bündel schnüren möchten, ohne allerdings
diese verdammten .svn
-Verzeichnisse dabei
zu haben, können Sie svn export verwenden,
um eine lokale Kopie des gesamten oder teilweisen Repositorys
ohne .svn
-Verzeichnisse zu erhalten. Wie
bei svn update und svn
checkout können Sie auch hier die Option
--revision
an svn export
übergeben:
$ svn export http://svn.example.com/svn/repos1 # Exportiert die letzte Revision … $ svn export http://svn.example.com/svn/repos1 -r 1729 # Exportiert Revision r1729 …
Nachdem wir nun die täglichen Aufgaben abgehandelt haben, für die Sie regelmäßig Subversion verwenden, gehen wir nun ein paar Verwaltungsaufgaben für Ihre Arbeitskopie durch.
Subversion merkt sich weder den Zustand noch das Vorhandensein einer Arbeitskopie auf dem Server, so dass serverseitig kein Aufwand für Arbeitskopien anfälllt. Dementsprechend besteht keine Notwendigkeit, dem Server mitzuteilen, dass Sie vorhaben, eine Arbeitskopie zu löschen.
Falls die Wahrscheinlichkeit besteht, dass Sie eine Arbeitskopie wiederverwenden möchten, ist es nicht verkehrt, sie einfach auf der Platte zu lassen, bis Sie sie wieder benutzen wollen. Zu diesem Zeitpunkt reicht lediglich ein svn update zum Aktualisieren, und sie ist gebrauchsfertig.
Falls Sie die Arbeitskopie jedoch bestimmt nicht mehr
verwenden möchten, können Sie sie ruhig löschen; jedoch
sollten Sie vorher darin nach unversionierten Dateien
suchen. Um diese Dateien zu finden, rufen Sie svn
status
auf und untersuchen alle Dateien, denen ein
?
voransteht, um sicherzugehen, dass sie
nicht wichtig sind. Wenn Sie die Untersuchung abgeschlossen
haben, können Sie Ihre Arbeitskopie ruhig löschen.
Wenn Subversion Ihre Arbeitskopie (oder irgendwelche
Informationen in .svn
) verändert,
versucht es das so sicher wie möglich zu machen. Bevor die
Arbeitskopie geändert wird, schreibt Subversion seine
Absichten in eine Protokolldatei. Dann führt es die Befehle in
der Protokolldatei aus, um die Änderungen anzuwenden, wobei es
während der Arbeit den relevanten Teil der Arbeitskopie
sperrt, um andere Clients davon abzuhalten, während der
Änderung auf die Arbeitskopie zuzugreifen. Zuletzt entfernt
Subversion die Protokolldatei. Architektonisch ist dies
ähnlich wie bei einem Dateisystem mit Journal. Falls eine
Subversion-Operation unterbrochen wird (z.B. wenn der Prozess
abgeschossen wird oder der Rechner abstürzt), bleibt die
Protokolldatei auf der Platte. Durch das erneute Ausführen der
Protokolldatei kann Subversion die vorher begonnene Operation
vervollständigen und Ihre Arbeitskopie gelangt wieder in
einen konsistenten Zustand.
Genau das macht svn cleanup: Es
durchsucht Ihre Arbeitskopie und führt etwaige übriggebliebene
Protokolldateien aus, wobei Sperren in der Arbeitskopie
entfernt werden. Fall Ihnen Subversion jemals mitteilt, dass
ein Teil Ihrer Arbeitskopie „gesperrt“ ist,
sollten Sie diesen Befehl aufrufen. Darüberhinaus zeigt
svn status ein L
neben
gesperrten Objekten an:
$ svn status L somedir M somedir/foo.c $ svn cleanup $ svn status M somedir/foo.c
Nun haben wir die meisten der Subversion-Client-Befehle behandelt. Erwähnenswerte Ausnahmen sind diejenigen, die sich mit dem Branchen und Mergen befassen (siehe Kapitel 4, Verzweigen und Zusammenführen) sowie mit Propertys (siehe „Properties“). Jedoch möchten Sie vielleicht einen Augenblick damit verbringen, um durch Kapitel 9, Subversion Complete Reference zu blättern, um ein Gefühl für all die verschiedenen Befehle zu bekommen, über die Subversion verfügt – und wie Sie sie verwenden können, um Ihre Arbeit zu erleichtern.
[3] Natürlich sind Sie nicht ernsthaft besorgt – erstens, weil Sie wissen, dass Sie nichts wirklich aus Subversion löschen können und zweitens, weil Ihr Subversion-Passwort nicht das gleiche ist wie irgendein anderes Ihrer 3 Millionen Passwörter, nicht wahr?
[4] Selbstverständlich wird nichts jemals
vollständig aus dem Repository
gelöscht – lediglich aus der
HEAD
-Revision des Repositorys.
Sie können alles was Sie gelöscht haben zurückholen,
indem Sie eine Revision auschecken
(oder hierauf aktualisieren), die älter ist, als die
Revision Ihrer Löschung. Siehe auch „Zurückholen gelöschter Objekte“.
[5] Und Sie haben keine WLAN-Karte. Sie dachten wohl, Sie kriegen uns, was?
[6] Und wenn Sie danach fragen, wird man Sie wahrscheinlich auf einer Schiene aus der Stadt tragen.
[7] Sehen Sie? Wir haben Ihnen gesagt, dass Subversion eine Zeitmaschine sei.
Inhaltsverzeichnis
If you've been reading this book chapter by chapter, from start to finish, you should by now have acquired enough knowledge to use the Subversion client to perform the most common version control operations. You understand how to check out a working copy from a Subversion repository. You are comfortable with submitting and receiving changes using the svn commit and svn update operations. You've probably even developed a reflex that causes you to run the svn status command almost unconsciously. For all intents and purposes, you are ready to use Subversion in a typical environment.
But the Subversion feature set doesn't stop at „common version control operations.“ It has other bits of functionality besides just communicating file and directory changes to and from a central repository.
This chapter highlights some of Subversion's features that, while important, aren't part of the typical user's daily routine. It assumes that you are familiar with Subversion's basic file and directory versioning capabilities. If you aren't, you'll want to first read Kapitel 1, Grundlegende Konzepte and Kapitel 2, Grundlegende Benutzung. Once you've mastered those basics and consumed this chapter, you'll be a Subversion power user!
As we described in „Revisionen“, revision numbers in Subversion are pretty straightforward—integers that keep getting larger as you commit more changes to your versioned data. Still, it doesn't take long before you can no longer remember exactly what happened in each and every revision. Fortunately, the typical Subversion workflow doesn't often demand that you supply arbitrary revisions to the Subversion operations you perform. For operations that do require a revision specifier, you generally supply a revision number that you saw in a commit email, in the output of some other Subversion operation, or in some other context that would give meaning to that particular number.
But occasionally, you need to pinpoint a moment in time for which you don't already have a revision number memorized or handy. So besides the integer revision numbers, svn allows as input some additional forms of revision specifiers: revision keywords and revision dates.
The various forms of Subversion revision specifiers can be
mixed and matched when used to specify revision ranges. For
example, you can use -r
where REV1
:REV2
REV1
is a revision keyword
and REV2
is a revision number, or
where REV1
is a date and
REV2
is a revision keyword, and so
on. The individual revision specifiers are independently
evaluated, so you can put whatever you want on the opposite
sides of that colon.
The Subversion client understands a number of revision
keywords. These keywords can be used instead of integer
arguments to the --revision
(-r
) option, and are resolved into specific
revision numbers by Subversion:
HEAD
The latest (or „youngest“) revision in the repository.
BASE
The revision number of an item in a working copy. If the item has been locally modified, this refers to the way the item appears without those local modifications.
COMMITTED
The most recent revision prior to, or equal to,
BASE
, in which an item changed.
PREV
The revision immediately before
the last revision in which an item changed.
Technically, this boils down to
COMMITTED
−1.
As can be derived from their descriptions, the
PREV
, BASE
, and
COMMITTED
revision keywords are used only
when referring to a working copy path—they don't apply
to repository URLs. HEAD
, on the other
hand, can be used in conjunction with both of these path
types.
Here are some examples of revision keywords in action:
$ svn diff -r PREV:COMMITTED foo.c # shows the last change committed to foo.c $ svn log -r HEAD # shows log message for the latest repository commit $ svn diff -r HEAD # compares your working copy (with all of its local changes) to the # latest version of that tree in the repository $ svn diff -r BASE:HEAD foo.c # compares the unmodified version of foo.c with the latest version of # foo.c in the repository $ svn log -r BASE:HEAD # shows all commit logs for the current versioned directory since you # last updated $ svn update -r PREV foo.c # rewinds the last change on foo.c, decreasing foo.c's working revision $ svn diff -r BASE:14 foo.c # compares the unmodified version of foo.c with the way foo.c looked # in revision 14
Revision numbers reveal nothing about the world outside
the version control system, but sometimes you need to
correlate a moment in real time with a moment in version
history. To facilitate this, the --revision
(-r
) option can also accept as input date
specifiers wrapped in curly braces ({
and
}
). Subversion accepts the standard
ISO-8601 date and time formats, plus a few others. Here are
some examples. (Remember to use quotes around any date that
contains spaces.)
$ svn checkout -r {2006-02-17} $ svn checkout -r {15:30} $ svn checkout -r {15:30:00.200000} $ svn checkout -r {"2006-02-17 15:30"} $ svn checkout -r {"2006-02-17 15:30 +0230"} $ svn checkout -r {2006-02-17T15:30} $ svn checkout -r {2006-02-17T15:30Z} $ svn checkout -r {2006-02-17T15:30-04:00} $ svn checkout -r {20060217T1530} $ svn checkout -r {20060217T1530Z} $ svn checkout -r {20060217T1530-0500} …
When you specify a date, Subversion resolves that date to the most recent revision of the repository as of that date, and then continues to operate against that resolved revision number:
$ svn log -r {2006-11-28} ------------------------------------------------------------------------ r12 | ira | 2006-11-27 12:31:51 -0600 (Mon, 27 Nov 2006) | 6 lines …
You can also use a range of dates. Subversion will find all revisions between both dates, inclusive:
$ svn log -r {2006-11-20}:{2006-11-29} …
Since the timestamp of a revision is stored as an unversioned, modifiable property of the revision (see „Properties“), revision timestamps can be changed to represent complete falsifications of true chronology, or even removed altogether. Subversion's ability to correctly convert revision dates into real revision numbers depends on revision datestamps maintaining a sequential ordering—the younger the revision, the younger its timestamp. If this ordering isn't maintained, you will likely find that trying to use dates to specify revision ranges in your repository doesn't always return the data you might have expected.
We've already covered in detail how Subversion stores and retrieves various versions of files and directories in its repository. Whole chapters have been devoted to this most fundamental piece of functionality provided by the tool. And if the versioning support stopped there, Subversion would still be complete from a version control perspective.
But it doesn't stop there.
In addition to versioning your directories and files, Subversion provides interfaces for adding, modifying, and removing versioned metadata on each of your versioned directories and files. We refer to this metadata as properties, and they can be thought of as two-column tables that map property names to arbitrary values attached to each item in your working copy. Generally speaking, the names and values of the properties can be whatever you want them to be, with the constraint that the names must contain only ASCII characters. And the best part about these properties is that they, too, are versioned, just like the textual contents of your files. You can modify, commit, and revert property changes as easily as you can file content changes. And the sending and receiving of property changes occurs as part of your typical commit and update operations—you don't have to change your basic processes to accommodate them.
Subversion has reserved the set of properties whose names
begin with svn:
as its own. While there
are only a handful of such properties in use today, you should
avoid creating custom properties for your own needs whose names
begin with this prefix. Otherwise, you run the risk that a
future release of Subversion will grow support for a feature
or behavior driven by a property of the same name but with
perhaps an entirely different interpretation.
Properties show up elsewhere in Subversion, too. Just as files and directories may have arbitrary property names and values attached to them, each revision as a whole may have arbitrary properties attached to it. The same constraints apply—human-readable names and anything-you-want binary values. The main difference is that revision properties are not versioned. In other words, if you change the value of, or delete, a revision property, there's no way, within the scope of Subversion's functionality, to recover the previous value.
Subversion has no particular policy regarding the use of
properties. It asks only that you not use property names that
begin with the prefix svn:
. That's the
namespace that it sets aside for its own use. And Subversion
does, in fact, use properties—both the versioned and
unversioned variety. Certain versioned properties have special
meaning or effects when found on files and directories, or they
house a particular bit of information about the revisions on
which they are found. Certain revision properties are
automatically attached to revisions by Subversion's commit
process, and they carry information about the revision. Most of
these properties are mentioned elsewhere in this or other
chapters as part of the more general topics to which they are
related. For an exhaustive list of Subversion's predefined
properties, see „Subversion Properties“.
In this section, we will examine the utility—both to users of Subversion and to Subversion itself—of property support. You'll learn about the property-related svn subcommands and how property modifications affect your normal Subversion workflow.
Just as Subversion uses properties to store extra information about the files, directories, and revisions that it contains, you might also find properties to be of similar use. You might find it useful to have a place close to your versioned data to hang custom metadata about that data.
Say you wish to design a web site that houses many digital photos and displays them with captions and a datestamp. Now, your set of photos is constantly changing, so you'd like to have as much of this site automated as possible. These photos can be quite large, so as is common with sites of this nature, you want to provide smaller thumbnail images to your site visitors.
Now, you can get this functionality using traditional
files. That is, you can have your
image123.jpg
and an
image123-thumbnail.jpg
side by side in a
directory. Or if you want to keep the filenames the same, you
might have your thumbnails in a different directory, such as
thumbnails/image123.jpg
. You can also
store your captions and datestamps in a similar fashion, again
separated from the original image file. But the problem here
is that your collection of files multiplies with each new
photo added to the site.
Now consider the same web site deployed in a way that
makes use of Subversion's file properties. Imagine having a
single image file, image123.jpg
, with
properties set on that file that are named
caption
, datestamp
, and
even thumbnail
. Now your working copy
directory looks much more manageable—in fact, it looks
to the casual browser like there are nothing but image files
in it. But your automation scripts know better. They know
that they can use svn (or better yet, they
can use the Subversion language bindings—see „Using the APIs“) to dig out the extra
information that your site needs to display without having to
read an index file or play path manipulation games.
While Subversion places few restrictions on the names and values you use for properties, it has not been designed to optimally carry large property values or large sets of properties on a given file or directory. Subversion commonly holds all the property names and values associated with a single item in memory at the same time, which can cause detrimental performance or failed operations when extremely large property sets are used.
Custom revision properties are also frequently used. One
common such use is a property whose value contains an issue
tracker ID with which the revision is associated, perhaps
because the change made in that revision fixes a bug filed in
the tracker issue with that ID. Other uses include hanging
more friendly names on the revision—it might be hard to
remember that revision 1935 was a fully tested revision. But
if there's, say, a test-results
property on
that revision with the value all passing
,
that's meaningful information to have.
The svn program affords a few ways to add or modify file and directory properties. For properties with short, human-readable values, perhaps the simplest way to add a new property is to specify the property name and value on the command line of the svn propset subcommand:
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c property 'copyright' set on 'calc/button.c' $
But we've been touting the flexibility that Subversion
offers for your property values. And if you are planning to
have a multiline textual, or even binary, property value, you
probably do not want to supply that value on the command line.
So the svn propset subcommand takes a
--file
(-F
) option for
specifying the name of a file that contains the new property
value.
$ svn propset license -F /path/to/LICENSE calc/button.c property 'license' set on 'calc/button.c' $
There are some restrictions on the names you can use for
properties. A property name must start with a letter, a colon
(:
), or an underscore
(_
); after that, you can also use digits,
hyphens (-
), and periods
(.
).
[8]
In addition to the propset command, the svn program supplies the propedit command. This command uses the configured editor program (see „Config“) to add or modify properties. When you run the command, svn invokes your editor program on a temporary file that contains the current value of the property (or that is empty, if you are adding a new property). Then, you just modify that value in your editor program until it represents the new value you wish to store for the property, save the temporary file, and then exit the editor program. If Subversion detects that you've actually changed the existing value of the property, it will accept that as the new property value. If you exit your editor without making any changes, no property modification will occur:
$ svn propedit copyright calc/button.c ### exit the editor without changes No changes to property 'copyright' on 'calc/button.c' $
We should note that, as with other svn subcommands, those related to properties can act on multiple paths at once. This enables you to modify properties on whole sets of files with a single command. For example, we could have done the following:
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/* property 'copyright' set on 'calc/Makefile' property 'copyright' set on 'calc/button.c' property 'copyright' set on 'calc/integer.c' … $
All of this property adding and editing isn't really very useful if you can't easily get the stored property value. So the svn program supplies two subcommands for displaying the names and values of properties stored on files and directories. The svn proplist command will list the names of properties that exist on a path. Once you know the names of the properties on the node, you can request their values individually using svn propget. This command will, given a property name and a path (or set of paths), print the value of the property to the standard output stream.
$ svn proplist calc/button.c Properties on 'calc/button.c': copyright license $ svn propget copyright calc/button.c (c) 2006 Red-Bean Software
There's even a variation of the
proplist command that will list both the
name and the value for all of the properties. Simply supply the
--verbose
(-v
) option.
$ svn proplist -v calc/button.c Properties on 'calc/button.c': copyright : (c) 2006 Red-Bean Software license : ================================================================ Copyright (c) 2006 Red-Bean Software. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the recipe for Fitz's famous red-beans-and-rice. …
The last property-related subcommand is propdel. Since Subversion allows you to store properties with empty values, you can't remove a property altogether using svn propedit or svn propset. For example, this command will not yield the desired effect:
$ svn propset license '' calc/button.c property 'license' set on 'calc/button.c' $ svn proplist -v calc/button.c Properties on 'calc/button.c': copyright : (c) 2006 Red-Bean Software license : $
You need to use the propdel subcommand to delete properties altogether. The syntax is similar to the other property commands:
$ svn propdel license calc/button.c property 'license' deleted from 'calc/button.c'. $ svn proplist -v calc/button.c Properties on 'calc/button.c': copyright : (c) 2006 Red-Bean Software $
Remember those unversioned revision properties? You can
modify those, too, using the same svn
subcommands that we just described. Simply add the
--revprop
command-line parameter and specify
the revision whose property you wish to modify. Since
revisions are global, you don't need to specify a target path
to these property-related commands so long as you are
positioned in a working copy of the repository whose
revision property you wish to modify. Otherwise, you can
simply provide the URL of any path in the repository of
interest (including the repository's root URL). For example,
you might want to replace the commit log message of an
existing revision.
[9]
If your current working directory is part of a working copy of
your repository, you can simply run the
svn propset command with no target path:
$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop property 'svn:log' set on repository revision '11' $
But even if you haven't checked out a working copy from that repository, you can still effect the property change by providing the repository's root URL:
$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop \ http://svn.example.com/repos/project property 'svn:log' set on repository revision '11' $
Note that the ability to modify these unversioned properties must be explicitly added by the repository administrator (see „Berichtigung des Protokolleintrags“). That's because the properties aren't versioned, so you run the risk of losing information if you aren't careful with your edits. The repository administrator can set up methods to protect against this loss, and by default, modification of unversioned properties is disabled.
Users should, where possible, use svn propedit instead of svn propset. While the end result of the commands is identical, the former will allow them to see the current value of the property that they are about to change, which helps them to verify that they are, in fact, making the change they think they are making. This is especially true when modifying unversioned revision properties. Also, it is significantly easier to modify multiline property values in a text editor than at the command line.
Now that you are familiar with all of the property-related svn subcommands, let's see how property modifications affect the usual Subversion workflow. As we mentioned earlier, file and directory properties are versioned, just like your file contents. As a result, Subversion provides the same opportunities for merging—cleanly or with conflicts—someone else's modifications into your own.
As with file contents, your property changes are local modifications, made permanent only when you commit them to the repository with svn commit. Your property changes can be easily unmade, too—the svn revert command will restore your files and directories to their unedited states—contents, properties, and all. Also, you can receive interesting information about the state of your file and directory properties by using the svn status and svn diff commands.
$ svn status calc/button.c M calc/button.c $ svn diff calc/button.c Property changes on: calc/button.c ___________________________________________________________________ Name: copyright + (c) 2006 Red-Bean Software $
Notice how the status subcommand
displays M
in the second column instead of
the first. That is because we have modified the properties on
calc/button.c
, but not its textual
contents. Had we changed both, we would have seen
M
in the first column, too. (We cover
svn status in „Verschaffen Sie sich einen Überblick über Ihre
Änderungen“).
You might also have noticed the nonstandard way that Subversion currently displays property differences. You can still use svn diff and redirect its output to create a usable patch file. The patch program will ignore property patches—as a rule, it ignores any noise it can't understand. This does, unfortunately, mean that to fully apply a patch generated by svn diff, any property modifications will need to be applied by hand.
Properties are a powerful feature of Subversion, acting as key components of many Subversion features discussed elsewhere in this and other chapters—textual diff and merge support, keyword substitution, newline translation, and so on. But to get the full benefit of properties, they must be set on the right files and directories. Unfortunately, that step can be easily forgotten in the routine of things, especially since failing to set a property doesn't usually result in an obvious error (at least compared to, say, failing to add a file to version control). To help your properties get applied to the places that need them, Subversion provides a couple of simple but useful features.
Whenever you introduce a file to version control using the
svn add or svn import
commands, Subversion tries to assist by setting some common
file properties automatically. First, on operating systems
whose filesystems support an execute permission bit,
Subversion will automatically set the
svn:executable
property on newly added or
imported files whose execute bit is enabled. (See „File Executability“ later in
this chapter for more about this property.)
Second, Subversion tries to determine the file's MIME
type. If you've configured a
mime-types-files
runtime configuration
parameter, Subversion will try to find a MIME type mapping in
that file for your file's extension. If it finds such a
mapping, it will set your file's
svn:mime-type
property to the MIME type it
found. If no mapping file is configured, or no mapping for
your file's extension could be found, Subversion runs a very
basic heuristic to determine whether the file contains nontextual
content. If so, it automatically sets the
svn:mime-type
property on that file to
application/octet-stream
(the generic
„this is a collection of bytes“ MIME type). Of
course, if Subversion guesses incorrectly, or if you wish to
set the svn:mime-type
property to something
more precise—perhaps image/png
or
application/x-shockwave-flash
—you can
always remove or edit that property. (For more on
Subversion's use of MIME types, see „File Content Type“ later in
this chapter.)
Subversion also provides, via its runtime configuration
system (see „Runtime Configuration Area“), a more
flexible automatic property setting feature that allows you
to create mappings of filename patterns to property names and
values. Once again, these mappings affect adds and imports,
and can not only override the default MIME type decision made
by Subversion during those operations, but can also set
additional Subversion or custom properties, too. For example,
you might create a mapping that says that anytime you add
JPEG files—ones whose names match the pattern
*.jpg
—Subversion should automatically
set the svn:mime-type
property on those
files to image/jpeg
. Or perhaps any files
that match *.cpp
should have
svn:eol-style
set to
native
, and svn:keywords
set to Id
. Automatic property support is
perhaps the handiest property-related tool in the Subversion
toolbox. See „Config“ for more about
configuring that support.
Fortunately for Subversion users who routinely find themselves on different computers with different operating systems, Subversion's command-line program behaves almost identically on all those systems. If you know how to wield svn on one platform, you know how to wield it everywhere.
However, the same is not always true of other general classes of software or of the actual files you keep in Subversion. For example, on a Windows machine, the definition of a „text file“ would be similar to that used on a Linux box, but with a key difference—the character sequences used to mark the ends of the lines of those files. There are other differences, too. Unix platforms have (and Subversion supports) symbolic links; Windows does not. Unix platforms use filesystem permission to determine executability; Windows uses filename extensions.
Because Subversion is in no position to unite the whole world in common definitions and implementations of all of these things, the best it can do is to try to help make your life simpler when you need to work with your versioned files and directories on multiple computers and operating systems. This section describes some of the ways Subversion does this.
Subversion joins the ranks of the many applications that
recognize and make use of Multipurpose Internet Mail
Extensions (MIME) content types. Besides being a
general-purpose storage location for a file's content type,
the value of the svn:mime-type
file
property determines some behavioral characteristics of
Subversion itself.
For example, one of the benefits that Subversion typically
provides is contextual, line-based merging of changes received
from the server during an update into your working file. But
for files containing nontextual data, there is often no
concept of a „line.“ So, for versioned files
whose svn:mime-type
property is set to a
nontextual MIME type (generally, something that doesn't begin
with text/
, though there are exceptions),
Subversion does not attempt to perform contextual merges
during updates. Instead, any time you have locally modified a
binary working copy file that is also being updated, your file
is left untouched and Subversion creates two new files. One
file has a .oldrev
extension and contains
the BASE revision of the file. The other file has a
.newrev
extension and contains the
contents of the updated revision of the file. This behavior
is really for the protection of the user against failed
attempts at performing contextual merges on files that simply
cannot be contextually merged.
The svn:mime-type
property, when set
to a value that does not indicate textual file contents, can
cause some unexpected behaviors with respect to other
properties. For example, since the idea of line endings
(and therefore, line-ending conversion) makes no sense when
applied to nontextual files, Subversion will prevent you
from setting the svn:eol-style
property
on such files. This is obvious when attempted on a single
file target—svn propset will error
out. But it might not be as clear if you perform a
recursive property set, where Subversion will silently skip
over files that it deems unsuitable for a given
property.
Beginning in Subversion 1.5, users can configure a new
mime-types-file
runtime configuration
parameter, which identifies the location of a MIME types
mapping file. Subversion will consult this mapping file to
determine the MIME type of newly added and imported
files.
Also, if the svn:mime-type
property is
set, then the Subversion Apache module will use its value to
populate the Content-type:
HTTP header when
responding to GET requests. This gives your web browser a
crucial clue about how to display a file when you use it to
peruse your Subversion repository's contents.
On many operating systems, the ability to execute a file
as a command is governed by the presence of an execute
permission bit. This bit usually defaults to being disabled,
and must be explicitly enabled by the user for each file that
needs it. But it would be a monumental hassle to have to
remember exactly which files in a freshly checked-out working
copy were supposed to have their executable bits toggled on,
and then to have to do that toggling. So, Subversion provides
the svn:executable
property as a way to
specify that the executable bit for the file on which that
property is set should be enabled, and Subversion honors that
request when populating working copies with such files.
This property has no effect on filesystems that have no
concept of an executable permission bit, such as FAT32 and
NTFS.
[11]
Also, although it has no defined values, Subversion will force
its value to *
when setting this property.
Finally, this property is valid only on files, not on
directories.
Unless otherwise noted using a versioned file's
svn:mime-type
property, Subversion
assumes the file contains human-readable data. Generally
speaking, Subversion uses this knowledge only to determine
whether contextual difference reports for that file are
possible. Otherwise, to Subversion, bytes are bytes.
This means that by default, Subversion doesn't pay any
attention to the type of end-of-line (EOL)
markers used in your files. Unfortunately,
different operating systems have different conventions about
which character sequences represent the end of a line of text
in a file. For example, the usual line-ending token used by
software on the Windows platform is a pair of ASCII control
characters—a carriage return (CR
)
followed by a line feed (LF
). Unix
software, however, just uses the LF
character to denote the end of a line.
Not all of the various tools on these operating systems
understand files that contain line endings in a format that
differs from the native line-ending
style of the operating system on which they are
running. So, typically, Unix programs treat the
CR
character present in Windows files as a
regular character (usually rendered as ^M
),
and Windows programs combine all of the lines of a Unix file
into one giant line because no carriage return-linefeed (or
CRLF
) character combination was found to
denote the ends of the lines.
This sensitivity to foreign EOL markers can be frustrating for folks who share a file across different operating systems. For example, consider a source code file, and developers that edit this file on both Windows and Unix systems. If all the developers always use tools that preserve the line-ending style of the file, no problems occur.
But in practice, many common tools either fail to properly read a file with foreign EOL markers, or convert the file's line endings to the native style when the file is saved. If the former is true for a developer, he has to use an external conversion utility (such as dos2unix or its companion, unix2dos) to prepare the file for editing. The latter case requires no extra preparation. But both cases result in a file that differs from the original quite literally on every line! Prior to committing his changes, the user has two choices. Either he can use a conversion utility to restore the modified file to the same line-ending style that it was in before his edits were made, or he can simply commit the file—new EOL markers and all.
The result of scenarios like these include wasted time and unnecessary modifications to committed files. Wasted time is painful enough. But when commits change every line in a file, this complicates the job of determining which of those lines were changed in a nontrivial way. Where was that bug really fixed? On what line was a syntax error introduced?
The solution to this problem is the
svn:eol-style
property. When this
property is set to a valid value, Subversion uses it to
determine what special processing to perform on the file so
that the file's line-ending style isn't flip-flopping with
every commit that comes from a different operating
system. The valid values are:
native
This causes the file to contain the EOL markers
that are native to the operating system on which
Subversion was run. In other words, if a user on a
Windows machine checks out a working copy that
contains a file with an
svn:eol-style
property set to
native
, that file will contain
CRLF
EOL markers. A Unix user
checking out a working copy that contains the same
file will see LF
EOL markers in his
copy of the file.
Note that Subversion will actually store the file
in the repository using normalized
LF
EOL markers regardless of the
operating system. This is basically transparent to
the user, though.
CRLF
This causes the file to contain
CRLF
sequences for EOL markers,
regardless of the operating system in use.
LF
This causes the file to contain
LF
characters for EOL markers,
regardless of the operating system in use.
CR
This causes the file to contain
CR
characters for EOL markers,
regardless of the operating system in use. This
line-ending style is not very common.
In any given working copy, there is a good chance that alongside all those versioned files and directories are other files and directories that are neither versioned nor intended to be. Text editors litter directories with backup files. Software compilers generate intermediate—or even final—files that you typically wouldn't bother to version. And users themselves drop various other files and directories wherever they see fit, often in version control working copies.
It's ludicrous to expect Subversion working copies to be somehow impervious to this kind of clutter and impurity. In fact, Subversion counts it as a feature that its working copies are just typical directories, just like unversioned trees. But these not-to-be-versioned files and directories can cause some annoyance for Subversion users. For example, because the svn add and svn import commands act recursively by default and don't know which files in a given tree you do and don't wish to version, it's easy to accidentally add stuff to version control that you didn't mean to. And because svn status reports, by default, every item of interest in a working copy—including unversioned files and directories—its output can get quite noisy where many of these things exist.
So Subversion provides two ways for telling it which files you would prefer that it simply disregard. One of the ways involves the use of Subversion's runtime configuration system (see „Runtime Configuration Area“), and therefore applies to all the Subversion operations that make use of that runtime configuration—generally those performed on a particular computer or by a particular user of a computer. The other way makes use of Subversion's directory property support and is more tightly bound to the versioned tree itself, and therefore affects everyone who has a working copy of that tree. Both of the mechanisms use file patterns (strings of literal and special wildcard characters used to match against filenames) to decide which files to ignore.
The Subversion runtime configuration system provides an
option, global-ignores
, whose value is a
whitespace-delimited collection of file patterns. The
Subversion client checks these patterns against the names of the
files that are candidates for addition to version control, as
well as to unversioned files that the svn
status command notices. If any file's name matches
one of the patterns, Subversion will basically act as if the
file didn't exist at all. This is really useful for the kinds
of files that you almost never want to version, such as editor
backup files such as Emacs' *~
and
.*~
files.
When found on a versioned directory, the
svn:ignore
property is expected to contain a
list of newline-delimited file patterns that Subversion should
use to determine ignorable objects in that same directory.
These patterns do not override those found in the
global-ignores
runtime configuration option,
but are instead appended to that list. And it's worth noting
again that, unlike the global-ignores
option,
the patterns found in the svn:ignore
property apply only to the directory on which that property is
set, and not to any of its subdirectories. The
svn:ignore
property is a good way to tell
Subversion to ignore files that are likely to be present in
every user's working copy of that directory, such as compiler
output or—to use an example more appropriate to this
book—the HTML, PDF, or PostScript files generated as the
result of a conversion of some source DocBook XML files to a
more legible output format.
Subversion's support for ignorable file patterns extends only to the one-time process of adding unversioned files and directories to version control. Once an object is under Subversion's control, the ignore pattern mechanisms no longer apply to it. In other words, don't expect Subversion to avoid committing changes you've made to a versioned file simply because that file's name matches an ignore pattern—Subversion always notices all of its versioned objects.
The global list of ignore patterns tends to be more a
matter of personal taste and ties more closely to a user's
particular tool chain than to the details of any particular
working copy's needs. So, the rest of this section will focus
on the svn:ignore
property and its
uses.
Say you have the following output from svn status:
$ svn status calc M calc/button.c ? calc/calculator ? calc/data.c ? calc/debug_log ? calc/debug_log.1 ? calc/debug_log.2.gz ? calc/debug_log.3.gz
In this example, you have made some property modifications
to button.c
, but in your working copy, you
also have some unversioned files: the latest
calculator
program that you've compiled
from your source code, a source file named
data.c
, and a set of debugging output logfiles.
Now, you know that your build system always results in
the calculator
program being generated.
[12]
And you know that your test suite always leaves those debugging
logfiles lying around. These facts are true for all working
copies of this project, not just your own. And you know that
you aren't interested in seeing those things every time you run
svn status, and you are pretty sure that
nobody else is interested in them either. So you use
svn propedit svn:ignore calc
to add some
ignore patterns to the calc
directory. For
example, you might add this as the new value of the
svn:ignore
property:
calculator debug_log*
After you've added this property, you will now have a local
property modification on the calc
directory. But notice what else is different about your
svn status output:
$ svn status M calc M calc/button.c ? calc/data.c
Now, all that cruft is missing from the output! Your
calculator
compiled program and all those
logfiles are still in your working copy; Subversion just isn't
constantly reminding you that they are present and unversioned.
And now with all the uninteresting noise removed from the
display, you are left with more intriguing items—such as
that source code file data.c
that you
probably forgot to add to version control.
Of course, this less-verbose report of your working copy
status isn't the only one available. If you actually want to
see the ignored files as part of the status report, you can pass
the --no-ignore
option to Subversion:
$ svn status --no-ignore M calc M calc/button.c I calc/calculator ? calc/data.c I calc/debug_log I calc/debug_log.1 I calc/debug_log.2.gz I calc/debug_log.3.gz
As mentioned earlier, the list of file patterns to ignore is
also used by svn add and svn
import. Both of these operations involve asking
Subversion to begin managing some set of files and directories.
Rather than force the user to pick and choose which files in a
tree she wishes to start versioning, Subversion uses the ignore
patterns—both the global and the per-directory
lists—to determine which files should not be swept into
the version control system as part of a larger recursive
addition or import operation. And here again, you can use the
--no-ignore
option to tell Subversion ignore
its ignores list and operate on all the files and directories
present.
Even if svn:ignore
is set, you may run
into problems if you use shell wildcards in a command. Shell
wildcards are expanded into an explicit list of targets before
Subversion operates on them, so running svn
is just like
running SUBCOMMAND
*svn
. In the case of the
svn add command, this has an effect similar
to passing the SUBCOMMAND
file1 file2 file3 …--no-ignore
option. So
instead of using a wildcard, use svn add --force
.
to do a bulk scheduling of unversioned things for
addition. The explicit target will ensure that the current
directory isn't overlooked because of being already under
version control, and the --force
option will
cause Subversion to crawl through that directory, adding
unversioned files while still honoring the
svn:ignore
property and
global-ignores
runtime configuration
variable. Be sure to also provide the --depth
files
option to the svn add
command if you don't want a fully recursive crawl for things
to add.
Subversion has the ability to substitute keywords—pieces of useful, dynamic information about a versioned file—into the contents of the file itself. Keywords generally provide information about the last modification made to the file. Because this information changes each time the file changes, and more importantly, just after the file changes, it is a hassle for any process except the version control system to keep the data completely up to date. Left to human authors, the information would inevitably grow stale.
For example, say you have a document in which you would
like to display the last date on which it was modified. You
could burden every author of that document to, just before
committing their changes, also tweak the part of the
document that describes when it was last changed. But
sooner or later, someone would forget to do that. Instead,
simply ask Subversion to perform keyword substitution on the
LastChangedDate
keyword. You control
where the keyword is inserted into your document by placing
a keyword anchor at the desired
location in the file. This anchor is just a string of text
formatted as
$
KeywordName
$
.
All keywords are case-sensitive where they appear as
anchors in files: you must use the correct capitalization
for the keyword to be expanded. You should consider the
value of the svn:keywords
property to be
case-sensitive, too—certain keyword names will be recognized
regardless of case, but this behavior is deprecated.
Subversion defines the list of keywords available for substitution. That list contains the following five keywords, some of which have aliases that you can also use:
Date
This keyword describes the last time the file was
known to have been changed in the repository, and is of
the form $Date: 2006-07-22 21:42:37 -0700 (Sat,
22 Jul 2006) $
. It may also be specified as
LastChangedDate
. Unlike the
Id
keyword, which uses UTC, the
Date
keyword displays dates using the
local time zone.
Revision
This keyword describes the last known revision in
which this file changed in the repository, and looks
something like $Revision: 144 $
.
It may also be specified as
LastChangedRevision
or
Rev
.
Author
This keyword describes the last known user to
change this file in the repository, and looks
something like $Author: harry $
.
It may also be specified as
LastChangedBy
.
HeadURL
This keyword describes the full URL to the latest
version of the file in the repository, and looks
something like $HeadURL:
http://svn.collab.net/repos/trunk/README $
.
It may be abbreviated as
URL
.
Id
This keyword is a compressed combination of the other
keywords. Its substitution looks something like
$Id: calc.c 148 2006-07-28 21:30:43Z sally
$
, and is interpreted to mean that the file
calc.c
was last changed in revision
148 on the evening of July 28, 2006 by the user
sally
. The date displayed by this
keyword is in UTC, unlike that of the
Date
keyword (which uses the local time
zone).
Several of the preceding descriptions use the phrase „last known“ or similar wording. Keep in mind that keyword expansion is a client-side operation, and your client „knows“ only about changes that have occurred in the repository when you update your working copy to include those changes. If you never update your working copy, your keywords will never expand to different values even if those versioned files are being changed regularly in the repository.
Simply adding keyword anchor text to your file does nothing special. Subversion will never attempt to perform textual substitutions on your file contents unless explicitly asked to do so. After all, you might be writing a document [13] about how to use keywords, and you don't want Subversion to substitute your beautiful examples of unsubstituted keyword anchors!
To tell Subversion whether to substitute keywords
on a particular file, we again turn to the property-related
subcommands. The svn:keywords
property,
when set on a versioned file, controls which keywords will
be substituted on that file. The value is a space-delimited
list of keyword names or aliases.
For example, say you have a versioned file named
weather.txt
that looks like
this:
Here is the latest report from the front lines. $LastChangedDate$ $Rev$ Cumulus clouds are appearing more frequently as summer approaches.
With no svn:keywords
property set on
that file, Subversion will do nothing special. Now, let's
enable substitution of the
LastChangedDate
keyword.
$ svn propset svn:keywords "Date Author" weather.txt property 'svn:keywords' set on 'weather.txt' $
Now you have made a local property modification on the
weather.txt
file. You will see no
changes to the file's contents (unless you made some of your
own prior to setting the property). Notice that the file
contained a keyword anchor for the Rev
keyword, yet we did not include that keyword in the property
value we set. Subversion will happily ignore requests to
substitute keywords that are not present in the file and
will not substitute keywords that are not present in the
svn:keywords
property value.
Immediately after you commit this property change,
Subversion will update your working file with the new
substitute text. Instead of seeing your keyword anchor
$LastChangedDate$
, you'll see its
substituted result. That result also contains the name of
the keyword and continues to be delimited by the dollar sign
($
) characters. And as we predicted, the
Rev
keyword was not substituted because
we didn't ask for it to be.
Note also that we set the svn:keywords
property to Date Author
, yet the keyword
anchor used the alias $LastChangedDate$
and still expanded correctly:
Here is the latest report from the front lines. $LastChangedDate: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $ $Rev$ Cumulus clouds are appearing more frequently as summer approaches.
If someone else now commits a change to
weather.txt
, your copy of that file
will continue to display the same substituted keyword value
as before—until you update your working copy. At that
time, the keywords in your weather.txt
file will be resubstituted with information that
reflects the most recent known commit to that file.
Subversion 1.2 introduced a new variant of the keyword
syntax, which brought additional, useful—though perhaps
atypical—functionality. You can now tell Subversion
to maintain a fixed length (in terms of the number of bytes
consumed) for the substituted keyword. By using a
double colon (::
) after the keyword name,
followed by a number of space characters, you define that
fixed width. When Subversion goes to substitute your
keyword for the keyword and its value, it will essentially
replace only those space characters, leaving the overall
width of the keyword field unchanged. If the substituted
value is shorter than the defined field width, there will be
extra padding characters (spaces) at the end of the
substituted field; if it is too long, it is truncated with a
special hash (#
) character just before
the final dollar sign terminator.
For example, say you have a document in which you have some section of tabular data reflecting the document's Subversion keywords. Using the original Subversion keyword substitution syntax, your file might look something like:
$Rev$: Revision of last commit $Author$: Author of last commit $Date$: Date of last commit
Now, that looks nice and tabular at the start of things. But when you then commit that file (with keyword substitution enabled, of course), you see:
$Rev: 12 $: Revision of last commit $Author: harry $: Author of last commit $Date: 2006-03-15 02:33:03 -0500 (Wed, 15 Mar 2006) $: Date of last commit
The result is not so beautiful. And you might be tempted to then adjust the file after the substitution so that it again looks tabular. But that holds only as long as the keyword values are the same width. If the last committed revision rolls into a new place value (say, from 99 to 100), or if another person with a longer username commits the file, stuff gets all crooked again. However, if you are using Subversion 1.2 or later, you can use the new fixed-length keyword syntax and define some field widths that seem sane, so your file might look like this:
$Rev:: $: Revision of last commit $Author:: $: Author of last commit $Date:: $: Date of last commit
You commit this change to your file. This time,
Subversion notices the new fixed-length keyword syntax and
maintains the width of the fields as defined by the padding
you placed between the double colon and the trailing dollar
sign. After substitution, the width of the fields is
completely unchanged—the short values for
Rev
and Author
are
padded with spaces, and the long Date
field is truncated by a hash character:
$Rev:: 13 $: Revision of last commit $Author:: harry $: Author of last commit $Date:: 2006-03-15 0#$: Date of last commit
The use of fixed-length keywords is especially handy when performing substitutions into complex file formats that themselves use fixed-length fields for data, or for which the stored size of a given data field is overbearingly difficult to modify from outside the format's native application (such as for Microsoft Office documents).
Be aware that because the width of a keyword field is measured in bytes, the potential for corruption of multibyte values exists. For example, a username that contains some multibyte UTF-8 characters might suffer truncation in the middle of the string of bytes that make up one of those characters. The result will be a mere truncation when viewed at the byte level, but will likely appear as a string with an incorrect or garbled final character when viewed as UTF-8 text. It is conceivable that certain applications, when asked to load the file, would notice the broken UTF-8 text and deem the entire file corrupt, refusing to operate on the file altogether. So, when limiting keywords to a fixed size, choose a size that allows for this type of byte-wise expansion.
By default, most Subversion operations on directories act in a recursive manner. For example, svn checkout creates a working copy with every file and directory in the specified area of the repository, descending recursively through the repository tree until the entire structure is copied to your local disk. Subversion 1.5 introduces a feature called sparse directories (or shallow checkouts) that allows you to easily check out a working copy—or a portion of a working copy—more shallowly than full recursion, with the freedom to bring in previously ignored files and subdirectories at a later time.
For example, say we have a repository with a tree of files and directories with names of the members of a human family with pets. (It's an odd example, to be sure, but bear with us.) A regular svn checkout operation will give us a working copy of the whole tree:
$ svn checkout file:///var/svn/repos mom A mom/son A mom/son/grandson A mom/daughter A mom/daughter/granddaughter1 A mom/daughter/granddaughter1/bunny1.txt A mom/daughter/granddaughter1/bunny2.txt A mom/daughter/granddaughter2 A mom/daughter/fishie.txt A mom/kitty1.txt A mom/doggie1.txt Checked out revision 1. $
Now, let's check out the same tree again, but this time we'll ask Subversion to give us only the topmost directory with none of its children at all:
$ svn checkout file:///var/svn/repos mom-empty --depth empty Checked out revision 1 $
Notice that we added to our original svn
checkout command line a new --depth
option. This option is present on many of Subversion's
subcommands and is similar to the
--non-recursive
(-N
) and
--recursive
(-R
) options. In
fact, it combines, improves upon, supercedes, and ultimately
obsoletes these two older options. For starters, it expands the
supported degrees of depth specification available to users,
adding some previously unsupported (or inconsistently supported)
depths. Here are the depth values that you can request for a
given Subversion operation:
--depth empty
Include only the immediate target of the operation, not any of its file or directory children.
--depth files
Include the immediate target of the operation and any of its immediate file children.
--depth immediates
Include the immediate target of the operation and any of its immediate file or directory children. The directory children will themselves be empty.
--depth infinity
Include the immediate target, its file and directory children, its children's children, and so on to full recursion.
Of course, merely combining two existing options into one hardly constitutes a new feature worthy of a whole section in our book. Fortunately, there is more to this story. This idea of depth extends not just to the operations you perform with your Subversion client, but also as a description of a working copy citizen's ambient depth, which is the depth persistently recorded by the working copy for that item. Its key strength is this very persistence—the fact that it is sticky. The working copy remembers the depth you've selected for each item in it until you later change that depth selection; by default, Subversion commands operate on the working copy citizens present, regardless of their selected depth settings.
You can check the recorded ambient depth of a working copy using the svn info command. If the ambient depth is anything other than infinite recursion, svn info will display a line describing that depth value:
$ svn info mom-immediates | grep '^Depth:' Depth: immediates $
Our previous examples demonstrated checkouts of infinite depth (the default for svn checkout) and empty depth. Let's look now at examples of the other depth values:
$ svn checkout file:///var/svn/repos mom-files --depth files A mom-files/kitty1.txt A mom-files/doggie1.txt Checked out revision 1. $ svn checkout file:///var/svn/repos mom-immediates --depth immediates A mom-immediates/son A mom-immediates/daughter A mom-immediates/kitty1.txt A mom-immediates/doggie1.txt Checked out revision 1. $
As described, each of these depths is something more than only the target, but something less than full recursion.
We've used svn checkout as an example
here, but you'll find the --depth
option
present on many other Subversion commands, too. In those other
commands, depth specification is a way to limit the scope of an
operation to some depth, much like the way the older
--non-recursive
(-N
) and
--recursive
(-R
) options
behave. This means that when operating on a working copy of
some depth, while requesting an operation of a shallower depth,
the operation is limited to that shallower depth. In fact, we
can make an even more general statement: given a working copy of
any arbitrary—even mixed—ambient depth, and a
Subversion command with some requested operational depth, the
command will maintain the ambient depth of the working copy
members while still limiting the scope of the operation to the
requested (or default) operational depth.
In addition to the --depth
option, the
svn update and svn switch
subcommands also accept a second depth-related option:
--set-depth
. It is with this option that you
can change the sticky depth of a working copy item. Watch what
happens as we take our empty-depth checkout and gradually
telescope it deeper using svn update
--set-depth
:NEW-DEPTH
TARGET
$ svn update --set-depth files mom-empty A mom-empty/kittie1.txt A mom-empty/doggie1.txt Updated to revision 1. $ svn update --set-depth immediates mom-empty A mom-empty/son A mom-empty/daughter Updated to revision 1. $ svn update --set-depth infinity mom-empty A mom-empty/son/grandson A mom-empty/daughter/granddaughter1 A mom-empty/daughter/granddaughter1/bunny1.txt A mom-empty/daughter/granddaughter1/bunny2.txt A mom-empty/daughter/granddaughter2 A mom-empty/daughter/fishie1.txt Updated to revision 1. $
As we gradually increased our depth selection, the repository gave us more pieces of our tree.
In our example, we operated only on the root of our working copy, changing its ambient depth value. But we can independently change the ambient depth value of any subdirectory inside the working copy, too. Careful use of this ability allows us to flesh out only certain portions of the working copy tree, leaving other portions absent altogether (hence the „sparse“ bit of the feature's name). Here's an example of how we might build out a portion of one branch of our family's tree, enable full recursion on another branch, and keep still other pieces pruned (absent from disk).
$ rm -rf mom-empty $ svn checkout file:///var/svn/repos mom-empty --depth empty Checked out revision 1. $ svn update --set-depth empty mom-empty/son A mom-empty/son Updated to revision 1. $ svn update --set-depth empty mom-empty/daughter A mom-empty/daughter Updated to revision 1. $ svn update --set-depth infinity mom-empty/daughter/granddaughter1 A mom-empty/daughter/granddaughter1 A mom-empty/daughter/granddaughter1/bunny1.txt A mom-empty/daughter/granddaughter1/bunny2.txt Updated to revision 1. $
Fortunately, having a complex collection of ambient depths
in a single working copy doesn't complicate the way you interact
with that working copy. You can still make, revert, display,
and commit local modifications in your working copy without
providing any new options (including --depth
and
--set-depth
) to the relevant subcommands. Even
svn update works as it does elsewhere when no
specific depth is provided—it updates the working copy
targets that are present while honoring their sticky
depths.
You might at this point be wondering, „So what? When
would I use this?“ One scenario where this feature
finds utility is tied to a particular repository layout,
specifically where you have many related or codependent
projects or software modules living as siblings in a single
repository location (trunk/project1
,
trunk/project2
,
trunk/project3
, etc.). In such
scenarios, it might be the case that you personally care
about only a handful of those projects—maybe some primary
project and a few other modules on which it depends. You can
check out individual working copies of all of these things, but
those working copies are disjoint and, as a result, it can be
cumbersome to perform operations across several or all of them
at the same time. The alternative is to use the sparse
directories feature, building out a single working copy that
contains only the modules you care about. You'd start with an
empty-depth checkout of the common parent directory of the
projects, and then update with infinite depth only the items you
wish to have, like we demonstrated in the previous example.
Think of it like an opt-in system for working copy
citizens.
Subversion 1.5's implementation of shallow checkouts is
good but does not support a couple of interesting behaviors.
First, you cannot de-telescope a working copy item. Running
svn update --set-depth empty
in an
infinite-depth working copy will not have the effect of
discarding everything but the topmost directory—it will
simply error out. Second, there is no depth value to indicate
that you wish an item to be explicitly excluded. You have to do
implicit exclusion of an item by including everything
else.
Subversion's copy-modify-merge version control model lives and dies on its data merging algorithms—specifically on how well those algorithms perform when trying to resolve conflicts caused by multiple users modifying the same file concurrently. Subversion itself provides only one such algorithm: a three-way differencing algorithm that is smart enough to handle data at a granularity of a single line of text. Subversion also allows you to supplement its content merge processing with external differencing utilities (as described in „External diff3“), some of which may do an even better job, perhaps providing granularity of a word or a single character of text. But common among those algorithms is that they generally work only on text files. The landscape starts to look pretty grim when you start talking about content merges of nontextual file formats. And when you can't find a tool that can handle that type of merging, you begin to run into problems with the copy-modify-merge model.
Let's look at a real-life example of where this model runs aground. Harry and Sally are both graphic designers working on the same project, a bit of marketing collateral for an automobile mechanic. Central to the design of a particular poster is an image of a car in need of some bodywork, stored in a file using the PNG image format. The poster's layout is almost finished, and both Harry and Sally are pleased with the particular photo they chose for their damaged car—a baby blue 1967 Ford Mustang with an unfortunate bit of crumpling on the left front fender.
Now, as is common in graphic design work, there's a change
in plans, which causes the car's color to be a concern. So Sally
updates her working copy to HEAD
, fires up
her photo-editing software, and sets about tweaking the image so
that the car is now cherry red. Meanwhile, Harry, feeling
particularly inspired that day, decides that the image would
have greater impact if the car also appears to have suffered
greater impact. He, too, updates to HEAD
,
and then draws some cracks on the vehicle's windshield. He
manages to finish his work before Sally finishes hers, and after
admiring the fruits of his undeniable talent, he commits the
modified image. Shortly thereafter, Sally is finished with the
car's new finish and tries to commit her changes. But, as
expected, Subversion fails the commit, informing Sally that
her version of the image is now out of date.
Here's where the difficulty sets in. If Harry and Sally were making changes to a text file, Sally would simply update her working copy, receiving Harry's changes in the process. In the worst possible case, they would have modified the same region of the file, and Sally would have to work out by hand the proper resolution to the conflict. But these aren't text files—they are binary images. And while it's a simple matter to describe what one would expect the results of this content merge to be, there is precious little chance that any software exists that is smart enough to examine the common baseline image that each of these graphic artists worked against, the changes that Harry made, and the changes that Sally made, and then spit out an image of a busted-up red Mustang with a cracked windshield!
Of course, things would have gone more smoothly if Harry and Sally had serialized their modifications to the image—if, say, Harry had waited to draw his windshield cracks on Sally's now-red car, or if Sally had tweaked the color of a car whose windshield was already cracked. As is discussed in „Die „Kopieren – Ändern – Zusammenfassen“ - Lösung“, most of these types of problems go away entirely where perfect communication between Harry and Sally exists. [14] But as one's version control system is, in fact, one form of communication, it follows that having that software facilitate the serialization of nonparallelizable editing efforts is no bad thing. This is where Subversion's implementation of the lock-modify-unlock model steps into the spotlight. This is where we talk about Subversion's locking feature, which is similar to the „reserved checkouts“ mechanisms of other version control systems.
Subversion's locking feature exists ultimately to minimize wasted time and effort. By allowing a user to programmatically claim the exclusive right to change a file in the repository, that user can be reasonably confident that any energy he invests on unmergeable changes won't be wasted—his commit of those changes will succeed. Also, because Subversion communicates to other users that serialization is in effect for a particular versioned object, those users can reasonably expect that the object is about to be changed by someone else. They, too, can then avoid wasting their time and energy on unmergeable changes that won't be committable due to eventual out-of-dateness.
When referring to Subversion's locking feature, one is actually talking about a fairly diverse collection of behaviors, which include the ability to lock a versioned file [15] (claiming the exclusive right to modify the file), to unlock that file (yielding that exclusive right to modify), to see reports about which files are locked and by whom, to annotate files for which locking before editing is strongly advised, and so on. In this section, we'll cover all of these facets of the larger locking feature.
In the Subversion repository, a lock is a piece of metadata that grants exclusive access to one user to change a file. This user is said to be the lock owner. Each lock also has a unique identifier, typically a long string of characters, known as the lock token. The repository manages locks, ultimately handling their creation, enforcement, and removal. If any commit transaction attempts to modify or delete a locked file (or delete one of the parent directories of the file), the repository will demand two pieces of information—that the client performing the commit be authenticated as the lock owner, and that the lock token has been provided as part of the commit process as a form of proof that the client knows which lock it is using.
To demonstrate lock creation, let's refer back to our example of multiple graphic designers working on the same binary image files. Harry has decided to change a JPEG image. To prevent other people from committing changes to the file while he is modifying it (as well as alerting them that he is about to change it), he locks the file in the repository using the svn lock command.
$ svn lock banana.jpg -m "Editing file for tomorrow's release." 'banana.jpg' locked by user 'harry'. $
The preceding example demonstrates a number of new things.
First, notice that Harry passed the
--message
(-m
) option to
svn lock. Similar to svn
commit, the svn lock command can
take comments—via either --message
(-m
) or --file
(-F
)—to describe the reason for locking the
file. Unlike svn commit, however,
svn lock will not demand a message by
launching your preferred text editor. Lock comments are
optional, but still recommended to aid communication.
Second, the lock attempt succeeded. This means that the file wasn't already locked, and that Harry had the latest version of the file. If Harry's working copy of the file had been out of date, the repository would have rejected the request, forcing Harry to svn update and reattempt the locking command. The locking command would also have failed if the file had already been locked by someone else.
As you can see, the svn lock command prints confirmation of the successful lock. At this point, the fact that the file is locked becomes apparent in the output of the svn status and svn info reporting subcommands.
$ svn status K banana.jpg $ svn info banana.jpg Path: banana.jpg Name: banana.jpg URL: http://svn.example.com/repos/project/banana.jpg Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec Revision: 2198 Node Kind: file Schedule: normal Last Changed Author: frank Last Changed Rev: 1950 Last Changed Date: 2006-03-15 12:43:04 -0600 (Wed, 15 Mar 2006) Text Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006) Properties Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006) Checksum: 3b110d3b10638f5d1f4fe0f436a5a2a5 Lock Token: opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e Lock Owner: harry Lock Created: 2006-06-14 17:20:31 -0500 (Wed, 14 Jun 2006) Lock Comment (1 line): Editing file for tomorrow's release. $
The fact that the svn info command,
which does not contact the repository when run against working
copy paths, can display the lock token reveals an important
piece of information about those tokens: they are cached in
the working copy. The presence of the lock token is critical.
It gives the working copy authorization to make use of the
lock later on. Also, the svn status
command shows a K
next to the file (short
for locKed), indicating that the lock token is present.
Now that Harry has locked banana.jpg
,
Sally is unable to change or delete that file:
$ svn delete banana.jpg D banana.jpg $ svn commit -m "Delete useless file." Deleting banana.jpg svn: Commit failed (details follow): svn: Server sent unexpected return value (423 Locked) in response to DELETE\ request for '/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/\ banana.jpg' $
But Harry, after touching up the banana's shade of yellow, is able to commit his changes to the file. That's because he authenticates as the lock owner and also because his working copy holds the correct lock token:
$ svn status M K banana.jpg $ svn commit -m "Make banana more yellow" Sending banana.jpg Transmitting file data . Committed revision 2201. $ svn status $
Notice that after the commit is finished, svn
status shows that the lock token is no longer
present in the working copy. This is the standard behavior of
svn commit—it searches the working
copy (or list of targets, if you provide such a list) for
local modifications and sends all the lock tokens it
encounters during this walk to the server as part of the
commit transaction. After the commit completes successfully,
all of the repository locks that were mentioned are
released—even on files that weren't
committed. This is meant to discourage users from
being sloppy about locking or from holding locks for too long.
If Harry haphazardly locks 30 files in a directory named
images
because he's unsure of which files
he needs to change, yet changes only four of those files, when he
runs svn commit images
, the process will
still release all 30 locks.
This behavior of automatically releasing locks can be
overridden with the --no-unlock
option to
svn commit. This is best used for those
times when you want to commit changes, but still plan to make
more changes and thus need to retain existing locks. You can
also make this your default behavior by setting the
no-unlock
runtime configuration option (see
„Runtime Configuration Area“).
Of course, locking a file doesn't oblige one to commit a change to it. The lock can be released at any time with a simple svn unlock command:
$ svn unlock banana.c 'banana.c' unlocked.
When a commit fails due to someone else's locks, it's
fairly easy to learn about them. The easiest way is to run
svn status --show-updates
:
$ svn status -u M 23 bar.c M O 32 raisin.jpg * 72 foo.h Status against revision: 105 $
In this example, Sally can see not only that her copy of
foo.h
is out of date, but also that one of the
two modified files she plans to commit is locked in the
repository. The O
symbol stands for
„Other,“ meaning that a lock exists on the file
and was created by somebody else. If she were to attempt a
commit, the lock on raisin.jpg
would
prevent it. Sally is left wondering who made the lock, when,
and why. Once again, svn info has the
answers:
$ svn info http://svn.example.com/repos/project/raisin.jpg Path: raisin.jpg Name: raisin.jpg URL: http://svn.example.com/repos/project/raisin.jpg Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec Revision: 105 Node Kind: file Last Changed Author: sally Last Changed Rev: 32 Last Changed Date: 2006-01-25 12:43:04 -0600 (Sun, 25 Jan 2006) Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b Lock Owner: harry Lock Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006) Lock Comment (1 line): Need to make a quick tweak to this image. $
Just as you can use svn info to examine objects in the working copy, you can also use it to examine objects in the repository. If the main argument to svn info is a working copy path, then all of the working copy's cached information is displayed; any mention of a lock means that the working copy is holding a lock token (if a file is locked by another user or in another working copy, svn info on a working copy path will show no lock information at all). If the main argument to svn info is a URL, the information reflects the latest version of an object in the repository, and any mention of a lock describes the current lock on the object.
So in this particular example, Sally can see that Harry locked the file on February 16 to „make a quick tweak.“ It being June, she suspects that he probably forgot all about the lock. She might phone Harry to complain and ask him to release the lock. If he's unavailable, she might try to forcibly break the lock herself or ask an administrator to do so.
A repository lock isn't sacred—in Subversion's default configuration state, locks can be released not only by the person who created them, but by anyone. When somebody other than the original lock creator destroys a lock, we refer to this as breaking the lock.
From the administrator's chair, it's simple to break locks. The svnlook and svnadmin programs have the ability to display and remove locks directly from the repository. (For more information about these tools, see „Der Werkzeugkasten eines Administrators“.)
$ svnadmin lslocks /var/svn/repos Path: /project2/images/banana.jpg UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923 Owner: frank Created: 2006-06-15 13:29:18 -0500 (Thu, 15 Jun 2006) Expires: Comment (1 line): Still improving the yellow color. Path: /project/raisin.jpg UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b Owner: harry Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006) Expires: Comment (1 line): Need to make a quick tweak to this image. $ svnadmin rmlocks /var/svn/repos /project/raisin.jpg Removed lock on '/project/raisin.jpg'. $
The more interesting option is to allow users to break
each other's locks over the network. To do this, Sally simply
needs to pass the --force
to the svn
unlock command:
$ svn status -u M 23 bar.c M O 32 raisin.jpg * 72 foo.h Status against revision: 105 $ svn unlock raisin.jpg svn: 'raisin.jpg' is not locked in this working copy $ svn info raisin.jpg | grep URL URL: http://svn.example.com/repos/project/raisin.jpg $ svn unlock http://svn.example.com/repos/project/raisin.jpg svn: Unlock request failed: 403 Forbidden (http://svn.example.com) $ svn unlock --force http://svn.example.com/repos/project/raisin.jpg 'raisin.jpg' unlocked. $
Now, Sally's initial attempt to unlock failed because she
ran svn unlock directly on her working copy
of the file, and no lock token was present. To remove the
lock directly from the repository, she needs to pass a URL
to svn unlock. Her first attempt to unlock
the URL fails, because she can't authenticate as the lock
owner (nor does she have the lock token). But when she
passes --force
, the authentication and
authorization requirements are ignored, and the remote lock is
broken.
Simply breaking a lock may not be enough. In
the running example, Sally may not only want to break Harry's
long-forgotten lock, but relock the file for her own use.
She can accomplish this by using svn unlock
with --force
and then svn lock
back-to-back, but there's a small chance that somebody else
might lock the file between the two commands. The simpler thing
to do is to steal the lock, which involves
breaking and relocking the file all in one atomic step. To
do this, Sally passes the --force
option
to svn lock:
$ svn lock raisin.jpg svn: Lock request failed: 423 Locked (http://svn.example.com) $ svn lock --force raisin.jpg 'raisin.jpg' locked by user 'sally'. $
In any case, whether the lock is broken or stolen, Harry may be in for a surprise. Harry's working copy still contains the original lock token, but that lock no longer exists. The lock token is said to be defunct. The lock represented by the lock token has either been broken (no longer in the repository) or stolen (replaced with a different lock). Either way, Harry can see this by asking svn status to contact the repository:
$ svn status K raisin.jpg $ svn status -u B 32 raisin.jpg $ svn update B raisin.jpg $ svn status $
If the repository lock was broken, then svn
status --show-updates
displays a
B
(Broken) symbol next to the file. If a
new lock exists in place of the old one, then a
T
(sTolen) symbol is shown. Finally,
svn update notices any defunct lock tokens
and removes them from the working copy.
We've seen how svn lock and svn unlock can be used to create, release, break, and steal locks. This satisfies the goal of serializing commit access to a file. But what about the larger problem of preventing wasted time?
For example, suppose Harry locks an image file and then
begins editing it. Meanwhile, miles away, Sally wants to do
the same thing. She doesn't think to run svn status
--show-updates
, so she has no idea that Harry has
already locked the file. She spends hours editing the file,
and when she tries to commit her change, she discovers that
either the file is locked or that she's out of date.
Regardless, her changes aren't mergeable with Harry's. One of
these two people has to throw away his or her work, and a lot of
time has been wasted.
Subversion's solution to this problem is to provide a
mechanism to remind users that a file ought to be locked
before the editing begins. The mechanism
is a special property: svn:needs-lock
. If
that property is attached to a file (regardless of its value,
which is irrelevant), Subversion will try to use
filesystem-level permissions to make the file read-only—unless,
of course, the user has explicitly locked the file.
When a lock token is present (as a result of using
svn lock), the file becomes read/write.
When the lock is released, the file becomes read-only
again.
The theory, then, is that if the image file has this property attached, Sally would immediately notice something is strange when she opens the file for editing: many applications alert users immediately when a read-only file is opened for editing, and nearly all would prevent her from saving changes to the file. This reminds her to lock the file before editing, whereby she discovers the preexisting lock:
$ /usr/local/bin/gimp raisin.jpg gimp: error: file is read-only! $ ls -l raisin.jpg -r--r--r-- 1 sally sally 215589 Jun 8 19:23 raisin.jpg $ svn lock raisin.jpg svn: Lock request failed: 423 Locked (http://svn.example.com) $ svn info http://svn.example.com/repos/project/raisin.jpg | grep Lock Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b Lock Owner: harry Lock Created: 2006-06-08 07:29:18 -0500 (Thu, 08 June 2006) Lock Comment (1 line): Making some tweaks. Locking for the next two hours. $
Users and administrators alike are encouraged to attach
the svn:needs-lock
property to any file
that cannot be contextually merged. This is the primary
technique for encouraging good locking habits and preventing
wasted effort.
Note that this property is a communication tool that works independently from the locking system. In other words, any file can be locked, whether or not this property is present. And conversely, the presence of this property doesn't make the repository require a lock when committing.
Unfortunately, the system isn't flawless. It's possible that even when a file has the property, the read-only reminder won't always work. Sometimes applications misbehave and „hijack“ the read-only file, silently allowing users to edit and save the file anyway. There's not much that Subversion can do in this situation—at the end of the day, there's simply no substitution for good interpersonal communication. [16]
Sometimes it is useful to construct a working copy that is made out of a number of different checkouts. For example, you may want different subdirectories to come from different locations in a repository or perhaps from different repositories altogether. You could certainly set up such a scenario by hand—using svn checkout to create the sort of nested working copy structure you are trying to achieve. But if this layout is important for everyone who uses your repository, every other user will need to perform the same checkout operations that you did.
Fortunately, Subversion provides support for
externals definitions. An externals
definition is a mapping of a local directory to the
URL—and ideally a particular revision—of a versioned
directory. In Subversion, you declare externals definitions in
groups using the svn:externals
property. You
can create or modify this property using svn
propset or svn propedit (see „Manipulating Properties“). It can be set on any
versioned directory, and its value describes both the external
repository location and the client-side directory to which that
location should be checked out.
The convenience of the svn:externals
property is that once it is set on a versioned directory,
everyone who checks out a working copy with that directory also
gets the benefit of the externals definition. In other words,
once one person has made the effort to define the nested working
copy structure, no one else has to bother—Subversion will,
after checking out the original working copy, automatically also
check out the external working copies.
The relative target subdirectories of externals definitions must not already exist on your or other users' systems—Subversion will create them when it checks out the external working copy.
You also get in the externals definition design all the
regular benefits of Subversion properties. The definitions are
versioned. If you need to change an externals definition, you
can do so using the regular property modification subcommands.
When you commit a change to the svn:externals
property, Subversion will synchronize the checked-out items
against the changed externals definition when you next run
svn update
. The same thing will happen when
others update their working copies and receive your changes to
the externals definition.
Because the svn:externals
property has
a multiline value, we strongly recommend that you use
svn propedit instead of svn
propset.
Subversion releases prior to 1.5 honor an externals definition format that is a multiline table of subdirectories (relative to the versioned directory on which the property is set), optional revision flags, and fully qualified, absolute Subversion repository URLs. An example of this might looks as follows:
$ svn propget svn:externals calc third-party/sounds http://svn.example.com/repos/sounds third-party/skins -r148 http://svn.example.com/skinproj third-party/skins/toolkit -r21 http://svn.example.com/skin-maker
When someone checks out a working copy of the
calc
directory referred to in the previous
example, Subversion also continues to check out the items found
in its externals definition.
$ svn checkout http://svn.example.com/repos/calc A calc A calc/Makefile A calc/integer.c A calc/button.c Checked out revision 148. Fetching external item into calc/third-party/sounds A calc/third-party/sounds/ding.ogg A calc/third-party/sounds/dong.ogg A calc/third-party/sounds/clang.ogg … A calc/third-party/sounds/bang.ogg A calc/third-party/sounds/twang.ogg Checked out revision 14. Fetching external item into calc/third-party/skins …
As of Subversion 1.5, though, a new format of the
svn:externals
property is supported.
Externals definitions are still multiline, but the order and
format of the various pieces of information have changed. The
new syntax more closely mimics the order of arguments you might
pass to svn checkout: the optional revision
flags come first, then the external Subversion repository URL,
and finally the relative local subdirectory. Notice, though,
that this time we didn't say „fully qualified, absolute
Subversion repository URLs.“ That's because the new
format supports relative URLs and URLs that carry peg revisions.
The previous example of an externals definition might, in
Subversion 1.5, look like the following:
$ svn propget svn:externals calc http://svn.example.com/repos/sounds third-party/sounds -r148 http://svn.example.com/skinproj third-party/skins -r21 http://svn.example.com/skin-maker third-party/skins/toolkit
Or, making use of the peg revision syntax (which we describe in detail in „Peg and Operative Revisions“), it might appear as:
$ svn propget svn:externals calc http://svn.example.com/repos/sounds third-party/sounds http://svn.example.com/skinproj@148 third-party/skins http://svn.example.com/skin-maker@21 third-party/skins/toolkit
You should seriously consider using explicit revision numbers in all of your externals definitions. Doing so means that you get to decide when to pull down a different snapshot of external information, and exactly which snapshot to pull. Besides avoiding the surprise of getting changes to third-party repositories that you might not have any control over, using explicit revision numbers also means that as you backdate your working copy to a previous revision, your externals definitions will also revert to the way they looked in that previous revision, which in turn means that the external working copies will be updated to match the way they looked back when your repository was at that previous revision. For software projects, this could be the difference between a successful and a failed build of an older snapshot of your complex codebase.
For most repositories, these three ways of formatting the
externals definitions have the same ultimate effect. They all
bring the same benefits. Unfortunately, they all bring the same
annoyances, too. Since the definitions shown use absolute URLs,
moving or copying a directory to which they are attached will
not affect what gets checked out as an external (though the
relative local target subdirectory will, of course, move with the
renamed directory). This can be confusing—even
frustrating—in certain situations. For example, say you
have a top-level directory named
my-project
, and you've created an externals
definition on one of its subdirectories
(my-project/some-dir
) that tracks the
latest revision of another of its subdirectories
(my-project/external-dir
).
$ svn checkout http://svn.example.com/projects . A my-project A my-project/some-dir A my-project/external-dir … Fetching external item into 'my-project/some-dir/subdir' Checked out external at revision 11. Checked out revision 11. $ svn propget svn:externals my-project/some-dir subdir http://svn.example.com/projects/my-project/external-dir $
Now you use svn move to rename the
my-project
directory. At this point, your
externals definition will still refer to a path under the
my-project
directory, even though that
directory no longer exists.
$ svn move -q my-project renamed-project $ svn commit -m "Rename my-project to renamed-project." Deleting my-project Adding renamed-project Committed revision 12. $ svn update Fetching external item into 'renamed-project/some-dir/subdir' svn: Target path does not exist $
Also, absolute URLs can cause problems with repositories
that are available via multiple URL schemes. For example, if
your Subversion server is configured to allow everyone to check
out the repository over http://
or
https://
, but only allow commits to come in
via https://
, you have an interesting problem
on your hands. If your externals definitions use the
http://
form of the repository URLs, you
won't be able to commit anything from the working copies created
by those externals. On the other hand, if they use the
https://
form of the URLs, anyone who might
be checking out via http://
because his
client doesn't support https://
will be
unable to fetch the external items. Be aware, too, that if you
need to reparent your working copy (using svn switch
with the --relocate
option), externals definitions will
not also be reparented.
Subversion 1.5 takes a huge step in relieving these frustrations. As mentioned earlier, the URLs used in the new externals definition format can be relative, and Subversion provides syntax magic for specifying multiple flavors of URL relativity.
../
Relative to the URL of the directory on which
the svn:externals
property is
set
^/
Relative to the root of the repository in
which the svn:externals
property is
versioned
//
Relative to the scheme of the URL of the
directory on which the svn:externals
property is set
/
Relative to the root URL of the server on
which the svn:externals
property is
versioned
So, looking a fourth time at our previous externals definition example, and making use of the new absolute URL syntax in various ways, we might now see:
$ svn propget svn:externals calc ^/sounds third-party/sounds /skinproj@148 third-party/skins //svn.example.com/skin-maker@21 third-party/skins/toolkit
The support that exists for externals definitions in
Subversion remains less than ideal, though. An externals
definition can point only to directories, not to files. Also, the
local subdirectory part of the definition cannot contain
..
parent directory indicators (such as
../../skins/myskin
). Perhap most
disappointingly, the working copies created via the externals
definition support are still disconnected from the primary
working copy (on whose versioned directories the
svn:externals
property was actually set).
And Subversion still truly operates only on nondisjoint working
copies. So, for example, if you want to commit changes that
you've made in one or more of those external working copies, you
must run svn commit explicitly on those
working copies—committing on the primary working copy will
not recurse into any external ones.
We've already mentioned some of the additional shortcomings
of the old svn:externals
format and how the
new Subversion 1.5 format improves upon it. But be careful when
making use of the new format that you don't inadvertently cause
problems for other folks accessing your repository who are using
older Subversion clients. While Subversion 1.5 clients will
continue to recognize and support the original externals
definition format, older clients will not
be able to correctly parse the new format.
Besides the svn checkout, svn
update, svn switch, and
svn export commands which actually manage the
disjoint (or disconnected) subdirectories
into which externals are checked out, the svn
status command also recognizes externals definitions.
It displays a status code of X
for the
disjoint external subdirectories, and then recurses into those
subdirectories to display the status of the external items
themselves. You can pass the
--ignore-externals
option to any of these
subcommands to disable externals definition processing.
We copy, move, rename, and completely replace files and directories on our computers all the time. And your version control system shouldn't get in the way of your doing these things with your version-controlled files and directories, either. Subversion's file management support is quite liberating, affording almost as much flexibility for versioned files as you'd expect when manipulating your unversioned ones. But that flexibility means that across the lifetime of your repository, a given versioned object might have many paths, and a given path might represent several entirely different versioned objects. This introduces a certain level of complexity to your interactions with those paths and objects.
Subversion is pretty smart about noticing when an object's version history includes such „changes of address.“ For example, if you ask for the revision history log of a particular file that was renamed last week, Subversion happily provides all those logs—the revision in which the rename itself happened, plus the logs of relevant revisions both before and after that rename. So, most of the time, you don't even have to think about such things. But occasionally, Subversion needs your help to clear up ambiguities.
The simplest example of this occurs when a directory or file
is deleted from version control, and then a new directory or
file is created with the same name and added to version control.
The thing you deleted and the thing you later added aren't the
same thing. They merely happen to have had the same
path—/trunk/object
, for example.
What, then, does it mean to ask Subversion about the history of
/trunk/object
? Are you asking about the
thing currently at that location, or the old thing you deleted
from that location? Are you asking about the operations that
have happened to all the objects that have
ever lived at that path? Subversion needs a hint about what you
really want.
And thanks to moves, versioned object history can get far
more twisted than even that. For example, you might have a
directory named concept
, containing some
nascent software project you've been toying with. Eventually,
though, that project matures to the point that the idea seems to
actually have some wings, so you do the unthinkable and decide
to give the project a name.
[17]
Let's say you called your software Frabnaggilywort. At this
point, it makes sense to rename the directory to reflect the
project's new name, so concept
is renamed
to frabnaggilywort
. Life goes on,
Frabnaggilywort releases a 1.0 version and is downloaded and
used daily by hordes of people aiming to improve their
lives.
It's a nice story, really, but it doesn't end there.
Entrepreneur that you are, you've already got another think in
the tank. So you make a new directory,
concept
, and the cycle begins again. In
fact, the cycle begins again many times over the years, each
time starting with that old concept
directory, then sometimes seeing that directory renamed as the
idea cures, sometimes seeing it deleted when you scrap the idea.
Or, to get really sick, maybe you rename
concept
to something else for a while, but
later rename the thing back to concept
for
some reason.
In scenarios like these, attempting to instruct Subversion to work with these reused paths can be a little like instructing a motorist in Chicago's West Suburbs to drive east down Roosevelt Road and turn left onto Main Street. In a mere 20 minutes, you can cross „Main Street“ in Wheaton, Glen Ellyn, and Lombard. And no, they aren't the same street. Our motorist—and our Subversion—need a little more detail to do the right thing.
In version 1.1, Subversion introduced a way for you to tell
it exactly which Main Street you meant. It's called the
peg revision, and it is provided to
Subversion for the sole purpose of identifying a unique line of
history. Because at most, one versioned object may occupy a path
at any given time—or, more precisely, in any one
revision—the combination of a path and a peg revision is
all that is needed to refer to a specific line of history. Peg
revisions are specified to the Subversion command-line client
using at syntax, so called because the
syntax involves appending an „at sign“
(@
) and the peg revision to the end of the
path with which the revision is associated.
But what of the --revision
(-r
) of which we've spoken so much in this
book? That revision (or set of revisions) is called the
operative revision (or
operative revision range). Once a
particular line of history has been identified using a path and
peg revision, Subversion performs the requested operation using
the operative revision(s). To map this to our Chicagoland
streets analogy, if we are told to go to 606 N. Main Street in
Wheaton,
[18]
we can think of „Main Street“ as our path and
„Wheaton“ as our peg revision. These two pieces of
information identify a unique path that can be traveled (north or
south on Main Street), and they keep us from traveling up and
down the wrong Main Street in search of our destination. Now we
throw in „606 N.“ as our operative revision of
sorts, and we know exactly where to
go.
Say that long ago we created our repository, and in revision 1
we added our first concept
directory, plus an
IDEA
file in that directory talking about
the concept. After several revisions in which real code was
added and tweaked, we, in revision 20, renamed this directory to
frabnaggilywort
. By revision 27, we had a
new concept, a new concept
directory to
hold it, and a new IDEA
file to describe
it. And then five years and thousands of revisions flew by,
just like they would in any good romance story.
Now, years later, we wonder what the
IDEA
file looked like back in revision 1.
But Subversion needs to know whether we are asking about how the
current file looked back in revision 1, or
whether we are asking for the contents of whatever file lived at
concepts/IDEA
in revision 1. Certainly
those questions have different answers, and because of peg
revisions, you can ask those questions. To find out how the
current IDEA
file looked in that old
revision, you run:
$ svn cat -r 1 concept/IDEA svn: Unable to find repository location for 'concept/IDEA' in revision 1
Of course, in this example, the current
IDEA
file didn't exist yet in revision 1,
so Subversion gives an error. The previous command is shorthand
for a longer notation which explicitly lists a peg revision.
The expanded notation is:
$ svn cat -r 1 concept/IDEA@BASE svn: Unable to find repository location for 'concept/IDEA' in revision 1
And when executed, it has the expected results.
The perceptive reader is probably wondering at this point whether
the peg revision syntax causes problems for working copy paths
or URLs that actually have at signs in them. After
all, how does svn know whether
news@11
is the name of a directory in my
tree or just a syntax for „revision 11 of
news
“? Thankfully, while
svn will always assume the latter, there is a
trivial workaround. You need only append an at sign to the
end of the path, such as news@11@
.
svn cares only about the last at sign in
the argument, and it is not considered illegal to omit a literal
peg revision specifier after that at sign. This workaround
even applies to paths that end in an at sign—you would
use filename@@
to talk about a file named
filename@
.
Let's ask the other question, then—in revision 1, what
were the contents of whatever file occupied the address
concepts/IDEA
at the time? We'll use an
explicit peg revision to help us out.
$ 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.
Notice that we didn't provide an operative revision this time. That's because when no operative revision is specified, Subversion assumes a default operative revision that's the same as the peg revision.
As you can see, the output from our operation appears to be
correct. The text even mentions frabbing naggily worts, so this
is almost certainly the file that describes the software now
called Frabnaggilywort. In fact, we can verify this using the
combination of an explicit peg revision and explicit operative
revision. We know that in HEAD
, the
Frabnaggilywort project is located in the
frabnaggilywort
directory. So we specify
that we want to see how the line of history identified in
HEAD
as the path
frabnaggilywort/IDEA
looked in revision
1.
$ 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.
And the peg and operative revisions need not be so trivial,
either. For example, say frabnaggilywort
had been deleted from HEAD
, but we know it
existed in revision 20, and we want to see the diffs for its
IDEA
file between revisions 4 and 10. We
can use the peg revision 20 in conjunction with the URL that
would have held Frabnaggilywort's IDEA
file
in revision 20, and then use 4 and 10 as our operative revision
range.
$ 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.
Fortunately, most folks aren't faced with such complex situations. But when you are, remember that peg revisions are that extra hint Subversion needs to clear up ambiguity.
It is commonplace for a developer to find himself working at any given time on multiple different, distinct changes to a particular bit of source code. This isn't necessarily due to poor planning or some form of digital masochism. A software engineer often spots bugs in his peripheral vision while working on some nearby chunk of source code. Or perhaps he's halfway through some large change when he realizes the solution he's working on is best committed as several smaller logical units. Often, these logical units aren't nicely contained in some module, safely separated from other changes. The units might overlap, modifying different files in the same module, or even modifying different lines in the same file.
Developers can employ various work methodologies to keep these logical changes organized. Some use separate working copies of the same repository to hold each individual change in progress. Others might choose to create short-lived feature branches in the repository and use a single working copy that is constantly switched to point to one such branch or another. Still others use diff and patch tools to back up and restore uncommitted changes to and from patch files associated with each change. Each of these methods has its pros and cons, and to a large degree, the details of the changes being made heavily influence the methodology used to distinguish them.
Subversion 1.5 brings a new changelists feature that adds yet another method to the mix. Changelists are basically arbitrary labels (currently at most one per file) applied to working copy files for the express purpose of associating multiple files together. Users of many of Google's software offerings are familiar with this concept already. For example, Gmail doesn't provide the traditional folders-based email organization mechanism. In Gmail, you apply arbitrary labels to emails, and multiple emails can be said to be part of the same group if they happen to share a particular label. Viewing only a group of similarly labeled emails then becomes a simple user interface trick. Many other Web 2.0 sites have similar mechanisms—consider the „tags“ used by sites such as YouTube and Flickr, „categories“ applied to blog posts, and so on. Folks understand today that organization of data is critical, but that how that data is organized needs to be a flexible concept. The old files-and-folders paradigm is too rigid for some applications.
Subversion's changelist support allows you to create changelists by applying labels to files you want to be associated with that changelist, remove those labels, and limit the scope of the files on which its subcommands operate to only those bearing a particular label. In this section, we'll look in detail at how to do these things.
You can create, modify, and delete changelists using the svn changelist command. More accurately, you use this command to set or unset the changelist association of a particular working copy file. A changelist is effectively created the first time you label a file with that changelist; it is deleted when you remove that label from the last file that had it. Let's examine a usage scenario that demonstrates these concepts.
Harry is fixing some bugs in the calculator application's mathematics logic. His work leads him to change a couple of files:
$ svn status M integer.c M mathops.c $
While testing his bug fix, Harry notices that his changes
bring to light a tangentially related bug in the user
interface logic found in button.c
. Harry
decides that he'll go ahead and fix that bug, too, as a
separate commit from his math fixes. Now, in a small working
copy with only a handful of files and few logical changes,
Harry can probably keep his two logical change groupings
mentally organized without any problem. But today he's going
to use Subversion's changelists feature as a special favor to
the authors of this book.
Harry first creates a changelist and associates with it the two files he's already changed. He does this by using the svn changelist command to assign the same arbitrary changelist name to those files:
$ svn changelist math-fixes integer.c mathops.c Path 'integer.c' is now a member of changelist 'math-fixes'. Path 'mathops.c' is now a member of changelist 'math-fixes'. $ svn status --- Changelist 'math-fixes': M integer.c M mathops.c $
As you can see, the output of svn status reflects this new grouping.
Harry now sets off to fix the secondary UI problem. Since he knows which file he'll be changing, he assigns that path to a changelist, too. Unfortunately, Harry carelessly assigns this third file to the same changelist as the previous two files:
$ svn changelist math-fixes button.c Path 'button.c' is now a member of changelist 'math-fixes'. $ svn status --- Changelist 'math-fixes': button.c M integer.c M mathops.c $
Fortunately, Harry catches his mistake. At this point, he
has two options. He can remove the changelist association
from button.c
, and then assign a
different changelist name:
$ svn changelist --remove button.c Path 'button.c' is no longer a member of a changelist. $ svn changelist ui-fix button.c Path 'button.c' is now a member of changelist 'ui-fix'. $
Or, he can skip the removal and just assign a new
changelist name. In this case, Subversion will first warn
Harry that button.c
is being removed from
the first changelist:
$ svn changelist ui-fix button.c svn: warning: Removing 'button.c' from changelist 'math-fixes'. Path 'button.c' is now a member of changelist 'ui-fix'. $ svn status --- Changelist 'ui-fix': button.c --- Changelist 'math-fixes': M integer.c M mathops.c $
Harry now has two distinct changelists present in his
working copy, and svn status will group its
output according to these changelist determinations. Notice
that even though Harry hasn't yet modified
button.c
, it still shows up in the output
of svn status as interesting because it has
a changelist assignment. Changelists can be added to and
removed from files at any time, regardless of whether they
contain local modifications.
Harry now fixes the user interface problem in
button.c
.
$ svn status --- Changelist 'ui-fix': M button.c --- Changelist 'math-fixes': M integer.c M mathops.c $
The visual grouping that Harry sees in the output of
svn status as shown in our previous section
is nice, but not entirely useful. The
status command is but one of many
operations that he might wish to perform on his working copy.
Fortunately, many of Subversion's other operations understand
how to operate on changelists via the use of the
--changelist
option.
When provided with a --changelist
option,
Subversion commands will limit the scope of their operation to
only those files to which a particular changelist name is
assigned. If Harry now wants to see the actual changes he's
made to the files in his math-fixes
changelist, he could explicitly list only
the files that make up that changelist on the svn
diff command line.
$ svn diff integer.c mathops.c Index: integer.c =================================================================== --- integer.c (revision 1157) +++ integer.c (working copy) … Index: mathops.c =================================================================== --- mathops.c (revision 1157) +++ mathops.c (working copy) … $
That works okay for a few files, but what if Harry's change touched 20 or 30 files? That would be an annoyingly long list of explicitly named files. Now that he's using changelists, though, Harry can avoid explicitly listing the set of files in his changelist from now on, and instead provide just the changelist name:
$ svn diff --changelist math-fixes Index: integer.c =================================================================== --- integer.c (revision 1157) +++ integer.c (working copy) … Index: mathops.c =================================================================== --- mathops.c (revision 1157) +++ mathops.c (working copy) … $
And when it's time to commit, Harry can again use the
--changelist
option to limit the scope of the
commit to files in a certain changelist. He might commit his
user interface fix by doing the following:
$ svn ci -m "Fix a UI bug found while working on math logic." \ --changelist ui-fix Sending button.c Transmitting file data . Committed revision 1158. $
In fact, the svn commit command
provides a second changelists-related option:
--keep-changelists
. Normally, changelist
assignments are removed from files after they are committed.
But if --keep-changelists
is provided,
Subversion will leave the changelist assignment on the
committed (and now unmodified) files. In any case, committing
files assigned to one changelist leaves other changelists
undisturbed.
$ svn status --- Changelist 'math-fixes': M integer.c M mathops.c $
The --changelist
option acts only as a
filter for Subversion command targets, and will not add
targets to an operation. For example, on a commit operation
specified as svn commit /path/to/dir
, the
target is the directory /path/to/dir
and its children (to infinite depth). If you then add a
changelist specifier to that command, only those files in
and under /path/to/dir
that are
assigned that changelist name will be considered as targets
of the commit—the commit will not include files
located elsewhere (such is in
/path/to/another-dir
), regardless of
their changelist assignment, even if they are part of the
same working copy as the operation's target(s).
Even the svn changelist command accepts
the --changelist
option. This allows you to
quickly and easily rename or remove a changelist:
$ svn changelist math-bugs --changelist math-fixes --depth infinity . svn: warning: Removing 'integer.c' from changelist 'math-fixes'. Path 'integer.c' is now a member of changelist 'math-bugs'. svn: warning: Removing 'mathops.c' from changelist 'math-fixes'. Path 'mathops.c' is now a member of changelist 'math-bugs'. $ svn changelist --remove --changelist math-bugs --depth infinity . Path 'integer.c' is no longer a member of a changelist. Path 'mathops.c' is no longer a member of a changelist. $
Finally, you can specify multiple instances of the
--changelist
option on a single command
line. Doing so limits the operation you are performing to
files found in any of the specified changesets.
Subversion's changelist feature is a handy tool for grouping working copy files, but it does have a few limitations. Changelists are artifacts of a particular working copy, which means that changelist assignments cannot be propagated to the repository or otherwise shared with other users. Changelists can be assigned only to files—Subversion doesn't currently support the use of changelists with directories. Finally, you can have at most one changelist assignment on a given working copy file. Here is where the blog post category and photo service tag analogies break down—if you find yourself needing to assign a file to multiple changelists, you're out of luck.
At some point, you're going to need to understand how your
Subversion client communicates with its server. Subversion's
networking layer is abstracted, meaning that Subversion clients
exhibit the same general behaviors no matter what sort of server
they are operating against. Whether speaking the HTTP protocol
(http://
) with the Apache HTTP Server or
speaking the custom Subversion protocol
(svn://
) with svnserve,
the basic network model is the same. In this section, we'll
explain the basics of that network model, including how
Subversion manages authentication and authorization
matters.
The Subversion client spends most of its time managing working copies. When it needs information from a remote repository, however, it makes a network request, and the server responds with an appropriate answer. The details of the network protocol are hidden from the user—the client attempts to access a URL, and depending on the URL scheme, a particular protocol is used to contact the server (see the sidebar Repository URLs).
Run svn --version
to see
which URL schemes and protocols the client knows how to
use.
When the server process receives a client request, it often demands that the client identify itself. It issues an authentication challenge to the client, and the client responds by providing credentials back to the server. Once authentication is complete, the server responds with the original information that the client asked for. Notice that this system is different from systems such as CVS, where the client preemptively offers credentials („logs in“) to the server before ever making a request. In Subversion, the server „pulls“ credentials by challenging the client at the appropriate moment, rather than the client „pushing“ them. This makes certain operations more elegant. For example, if a server is configured to allow anyone in the world to read a repository, the server will never issue an authentication challenge when a client attempts to svn checkout.
If the particular network requests issued by the client
result in a new revision being created in the repository
(e.g., svn commit), Subversion uses the
authenticated username associated with those requests as the
author of the revision. That is, the authenticated user's
name is stored as the value of the
svn:author
property on the new revision
(see „Subversion Properties“). If
the client was not authenticated (i.e., if the server
never issued an authentication challenge), the revision's
svn:author
property is empty.
Many servers are configured to require authentication on
every request. This would be a big annoyance to users if
they were forced to type their passwords over and over again.
Fortunately, the Subversion client has a remedy for
this—a built-in system for caching authentication
credentials on disk. By default, whenever the command-line
client successfully responds to a server's authentication
challenge, it saves the credentials in the user's private
runtime configuration area
(~/.subversion/auth/
on Unix-like systems
or %APPDATA%/Subversion/auth/
on Windows;
see „Runtime Configuration Area“ for more details
about the runtime configuration system). Successful
credentials are cached on disk and keyed on a combination of the
server's hostname, port, and authentication realm.
When the client receives an authentication challenge, it first looks for the appropriate credentials in the user's disk cache. If seemingly suitable credentials are not present, or if the cached credentials ultimately fail to authenticate, the client will, by default, fall back to prompting the user for the necessary information.
The security-conscious reader will suspect immediately that there is reason for concern here. „Caching passwords on disk? That's terrible! You should never do that!“
The Subversion developers recognize the legitimacy of such concerns, and so Subversion works with available mechanisms provided by the operating system and environment to try to minimize the risk of leaking this information. Here's a breakdown of what this means for users on the most common platforms:
On Windows 2000 and later, the Subversion client uses standard Windows cryptography services to encrypt the password on disk. Because the encryption key is managed by Windows and is tied to the user's own login credentials, only the user can decrypt the cached password. (Note that if the user's Windows account password is reset by an administrator, all of the cached passwords become undecipherable. The Subversion client will behave as though they don't exist, prompting for passwords when required.)
Similarly, on Mac OS X, the Subversion client stores all repository passwords in the login keyring (managed by the Keychain service), which is protected by the user's account password. User preference settings can impose additional policies, such as requiring that the user's account password be entered each time the Subversion password is used.
For other Unix-like operating systems, no standard
„keychain“ services exist. However,
the auth/
caching area is still
permission-protected so that only the user (owner) can
read data from it, not the world at large. The operating
system's own file permissions protect the passwords.
Of course, for the truly paranoid, none of these mechanisms meets the test of perfection. So for those folks willing to sacrifice convenience for the ultimate in security, Subversion provides various ways of disabling its credentials caching system altogether.
To disable caching for a single command, pass the
--no-auth-cache
option:
$ svn commit -F log_msg.txt --no-auth-cache Authentication realm: <svn://host.example.com:3690> example realm Username: joe Password for 'joe': Adding newfile Transmitting file data . Committed revision 2324. # password was not cached, so a second commit still prompts us $ svn delete newfile $ svn commit -F new_msg.txt Authentication realm: <svn://host.example.com:3690> example realm Username: joe …
Or, if you want to disable credential caching permanently,
you can edit the config
file in your
runtime configuration area and set the
store-auth-creds
option to
no
. This will prevent the storing of
credentials used in any Subversion interactions you perform on
the affected computer. This can be extended to cover all
users on the computer, too, by modifying the system-wide
runtime configuration area (described in „Configuration Area Layout“).
[auth] store-auth-creds = no
Sometimes users will want to remove specific credentials
from the disk cache. To do this, you need to navigate into
the auth/
area and manually delete the
appropriate cache file. Credentials are cached in individual
files; if you look inside each file, you will see keys and
values. The svn:realmstring
key describes
the particular server realm that the file is associated
with:
$ ls ~/.subversion/auth/svn.simple/ 5671adf2865e267db74f09ba6f872c28 3893ed123b39500bca8a0b382839198e 5c3c22968347b390f349ff340196ed39 $ cat ~/.subversion/auth/svn.simple/5671adf2865e267db74f09ba6f872c28 K 8 username V 3 joe K 8 password V 4 blah K 15 svn:realmstring V 45 <https://svn.domain.com:443> Joe's repository END
Once you have located the proper cache file, just delete it.
One last word about svn's
authentication behavior, specifically regarding the
--username
and --password
options. Many client subcommands accept these options, but it
is important to understand that using these options does
not automatically send credentials to the
server. As discussed earlier, the server „pulls“
credentials from the client when it deems necessary; the
client cannot „push“ them at will. If a username
and/or password are passed as options, they will be
presented to the server only if the server requests them. These
options are typically used to authenticate as a different user
than Subversion would have chosen by default (such as your
system login name) or when trying to avoid interactive
prompting (such as when calling svn from a
script).
A common mistake is to misconfigure a server so
that it never issues an authentication challenge. When
users pass --username
and
--password
options to the client, they're
surprised to see that they're never used; that is, new
revisions still appear to have been committed
anonymously!
Here is a final summary that describes how a Subversion client behaves when it receives an authentication challenge.
First, the client checks whether the user specified
any credentials as command-line options
(--username
and/or
--password
). If so, the client will try
to use those credentials to authenticate against the
server.
If no command-line credentials were provided, or the
provided ones were invalid, the client looks up the server's
hostname, port, and realm in the runtime configuration's
auth/
area, to see whether appropriate
credentials are cached there. If so, it attempts to use
those credentials to authenticate.
Finally, if the previous mechanisms failed to
successfully authenticate the user against the server, the
client resorts to interactively prompting the user for
valid credentials (unless instructed not to do so via the
--non-interactive
option or its
client-specific equivalents).
If the client successfully authenticates by any of these methods, it will attempt to cache the credentials on disk (unless the user has disabled this behavior, as mentioned earlier).
After reading this chapter, you should have a firm grasp on some of Subversion's features that, while perhaps not used every time you interact with your version control system, are certainly handy to know about. But don't stop here! Read on to the following chapter, where you'll learn about branches, tags, and merging. Then you'll have nearly full mastery of the Subversion client. Though our lawyers won't allow us to promise you anything, this additional knowledge could make you measurably more cool. [19]
[8] If you're familiar with XML, this is pretty much the ASCII subset of the syntax for XML "Name".
[9] Fixing spelling errors, grammatical gotchas, and
„just-plain-wrongness“ in commit log
messages is perhaps the most common use case for the
--revprop
option.
[10] You think that was rough? During that same era,
WordPerfect also used .DOC
for their
proprietary file format's preferred extension!
[11] The Windows filesystems use file extensions (such as
.EXE
, .BAT
, and
.COM
) to denote executable
files.
[12] Isn't that the whole point of a build system?
[13] … or maybe even a section of a book …
[14] Communication wouldn't have been such bad medicine for Harry and Sally's Hollywood namesakes, either, for that matter.
[15] Subversion does not currently allow locks on directories.
[16] Except, perhaps, a classic Vulcan mind-meld.
[17] „You're not supposed to name it. Once you name it, you start getting attached to it.“—Mike Wazowski
[18] 606 N. Main Street, Wheaton, Illinois, is the home of the Wheaton History Center. It seemed appropriate….
[19] No purchase necessary. Certains terms and conditions apply. No guarantee of coolness—implicit or otherwise—exists. Mileage may vary.
Inhaltsverzeichnis
„君子务本 (Der Edle pflegt die Wurzel)“ | ||
--Konfuzius |
Verzweigen (Branching), Etikettieren (Tagging) und Zusammenführen (Merging) sind Konzepte, die fast allen Versionskontrollsystemen gemein sind. Falls Sie mit diesen Begriffen nicht vertraut sein sollten, geben wir in diesem Kapitel eine gute Einführung. Falls Sie damit vertraut sind, werden Sie es hoffentlich interessant finden, zu sehen, wie Subversion diese Konzepte implementiert.
Verzweigen ist ein grundlegender Teil der Versionskontrolle. Falls Sie Subversion erlauben wollen, Ihre Daten zu verwalten, ist dies eine Fähigkeit, von der Sie letztendlich abhängig sein werden. Dieses Kapitel geht davon aus, dass Sie mit den grundlegenden Konzepten von Subversion vertraut sind (Kapitel 1, Grundlegende Konzepte).
Angenommen, Ihre Aufgabe ist es, ein Dokument für eine Abteilung Ihrer Firma zu pflegen – eine Art Handbuch. Eines Tages fragt eine andere Abteilung nach dem gleichen Handbuch, jedoch an einigen Stellen für ihre Bedürfnisse „abgewandelt“, da sie auf etwas andere Weise arbeiten.
Was machen Sie in dieser Situation? Sie machen das Offensichtliche: Sie erstellen eine Kopie Ihres Dokumentes und beginnen, die beiden Kopien getrennt zu pflegen. Sobald Sie irgendeine Abteilung auffordert, kleine Änderungen vorzunehmen, pflegen Sie diese in die eine oder andere Kopie ein.
Oftmals möchten Sie die selbe Änderung in beiden Kopien machen. Wenn Sie zum Beispiel einen Schreibfehler in der ersten Kopie entdecken, ist es sehr wahrscheinlich, dass dieser Fehler auch in der zweiten Kopie vorliegt. Schließlich sind die beiden Dokumente fast gleich; sie unterscheiden sich nur in kleinen Dingen.
Das ist das Grundkonzept eines Zweigs (Branch) – nämlich eine Entwicklungslinie, die unabhängig von einer anderen existiert, jedoch über eine gemeinsame Geschichte verfügt, wenn lang genug in der Zeit zurück gegangen wird. Ein Zweig beginnt sein Leben stets als eine Kopie von etwas und läuft von da an weiter, wobei er seine eigene Geschichte erzeugt (siehe Abbildung 4.1, „Entwicklungszweige“).
Subversion verfügt über Befehle, die Ihnen helfen, parallele Zweige Ihrer Dateien und Verzeichnisse zu verwalten. Es erlaubt Ihnen, durch das Kopieren Ihrer Daten, Zweige zu erstellen und merkt sich, dass die Zweige untereinander in Beziehung stehen. Es hilft Ihnen auch, Änderungen von einem Zweig auf den anderen zu duplizieren. Schließlich ermöglicht es, dass Teile Ihrer Arbeitskopie verschiedene Zweige repräsentieren können, was Ihnen während Ihrer täglichen Arbeit erlaubt, verschiedene Entwicklungslinien zu „mischen und gegenüberzustellen“.
An dieser Stelle sollten Sie verstehen, wie jede Übergabe an das Repository dort einen völlig neuen Dateibaum („Revision“ genannt) erzeugt. Wenn nicht, blättern Sie zurück und lesen Sie in „Revisionen“ über Revisionen nach.
Für dieses Kapitel verwenden wir das Beispiel aus Kapitel 1, Grundlegende Konzepte. Erinnern Sie sich, dass Sie und Ihre
Mitarbeiterin Sally sich ein Repository teilen, das zwei
Projekte beinhaltet: paint
und
calc
. Beachten Sie, dass in Abbildung 4.2, „Repository-Struktur zu Beginn“ dieses Mal jedoch jedes
Projektverzeichnis Unterverzeichnisse namens
trunk
und branches
beinhaltet. Der Grund hierfür wird bald klar sein.
Wie vorher sei hier angenommen, dass sowohl Sally als auch
Sie Arbeitskopien des „calc“ Projektes
besitzen. Ausdrücklich hat jeder von Ihnen eine Arbeitskopie von
/calc/trunk
. Alle Dateien des Projektes
befinden sich in diesem Unterverzeichnis statt in
/calc
selber, da Ihr Team entschieden hat,
dass in /calc/trunk
die
„Hauptlinie“ der Entwicklung stattfindet.
Sagen wir mal, dass Sie die Aufgabe bekommen haben, ein
großes Stück Software umzusetzen. Die Erstellung benötigt eine
lange Zeit und berührt alle Dateien im Projekt. Das Problem,
dass sofort auftaucht ist, dass Sie nicht Sally in die Quere
kommen möchten, die gerade hier und da kleinere Fehler
beseitigt. Sie ist abhängig von der Tatsache, dass die letzte
Version des Projektes (in /calc/trunk
)
stets benutzbar ist. Wenn Sie nun damit beginnen, Stück für
Stück Ihre Änderungen zu übergeben, werden Sie gewiss die Dinge
für Sally (und auch für andere Teammitglieder) in Unordnung
bringen.
Eine Strategie ist, sich in ein Loch zu verkriechen: Sie und
Sally können für eine Woche oder zwei den Informationsaustausch
einstellen. Das heißt, Sie fangen damit an, die Dateien Ihrer
Arbeitskopie auszuräumen und umzuorganisieren, ohne Änderungen
zu übergeben oder die Arbeitskopie zu aktualisieren, bevor Sie
mit Ihrer Arbeit vollständig fertig sind. Das wirft allerdings
einige Probleme auf. Erstens ist das nicht sehr sicher. Viele
Leute möchten Ihre Arbeit regelmäßig ins Repository sichern, für
den Fall, dass etwas Schlimmes mit der Arbeitskopie passieren
könnte. Zweitens ist das nicht sehr flexibel. Falls Sie Ihre
Arbeit an mehreren Rechnern verrichten (vielleicht haben Sie
eine Arbeitskopie von /calc/trunk
auf zwei
unterschiedlichen Maschinen), müssten Sie entweder alle
Änderungen manuell hin und her kopieren oder die gesamte Arbeit
an nur einem Rechner erledigen. Ebenso schwierig wäre es, Ihre
Änderungen mit anderen zu teilen. Eine weit verbreitete
„beste Vorgehensweise“ ist es, Ihren Mitarbeitern
zu erlauben, während Sie mit Ihrer Arbeit fortfahren, Ihre
bisherigen Ergebnisse zu überprüfen. Wenn niemand Ihre
unmittelbaren Änderungen sieht, haben Sie keine möglichen
Rückmeldungen und es könnte sein, dass Sie für Wochen einen
falschen Weg einschlagen, bevor es jemand aus Ihrem Team
bemerkt. Schließlich könnte es am Ende, wenn Sie mit Ihren
Änderungen fertig sind, sehr schwierig sein, Ihr Arbeitsergebnis
wieder mit dem Hauptteil der Quelltexte Ihrer Firma
zusammenzuführen. Sally (und andere) hätten viele andere
Änderungen ins Repository übergeben haben können, die sich
schwer in Ihre Arbeitskopie einarbeiten ließen –
besonders, falls Sie svn update nach Wochen
der Isolierung ausführen.
Die bessere Lösung ist, Ihren eigenen Zweig oder Ihre eigene Entwicklungslinie im Repository zu erzeugen. Dies erlaubt Ihnen, Ihre halbfertigen Arbeitsergebnisse regelmäßig zu sichern, ohne andere zu stören; dennoch können Sie selektiv Informationen mit Ihren Kollegen teilen. Im Weiteren werden Sie sehen, wie das funktioniert.
Es ist sehr einfach, einen Zweig zu erzeugen – Sie
erstellen mit dem Befehl svn copy eine
Kopie des Projektes im Repository. Subversion kann nicht nur
Dateien, sondern auch komplette Verzeichnisse kopieren. In
diesem Fall möchten Sie eine Kopie des Verzeichnisses
/calc/trunk
machen. Wo soll die neue
Kopie angelegt werden? Wo Sie wünschen – es ist eine
Frage der Projektkonventionen. Sagen wir mal, dass Ihr Team
die Konvention vereinbart hat, Zweige im Bereich
/calc/branches
des Repositorys anzulegen,
und Sie Ihren Zweig my-calc-branch
nennen
möchten. Sie werden ein neues Verzeichnis
/calc/branches/my-calc-branch
anlegen,
das als Kopie von /calc/trunk
beginnt.
Sie haben vielleicht schon gesehen, wie mit svn copy in einer Arbeitskopie eine Datei auf eine andere kopiert wird. Es kann allerdings auch verwendet werden, um eine „entfernte“ Kopie innerhalb des Repositorys durchzuführen. Kopieren Sie einfach einen URL auf einen anderen:
$ svn copy http://svn.example.com/repos/calc/trunk \ http://svn.example.com/repos/calc/branches/my-calc-branch \ -m "Privaten Zweig von /calc/trunk angelegt." Revision 341 übertragen.
Dieser Befehl bewirkt eine fast sofortige Übergabe im
Repository, wobei in Revision 341 ein neues Verzeichnis
erzeugt wird. Das neue Verzeichnis ist eine Kopie von
/calc/trunk
. Dies wird in Abbildung 4.3, „Repository mit neuer Kopie“ gezeigt.
[20]
Obwohl es auch möglich ist, einen Zweig zu erzeugen, indem
svn copy verwendet wird, um ein Verzeichnis
innerhalb der Arbeitskopie zu duplizieren, wird dieses
Vorgehen nicht empfohlen. Es kann in der Tat sehr langsam
sein! Das client-seitige Kopieren eines Verzeichnisses besitzt
einen linearen Zeitaufwand, da wirklich jede Datei und jedes
Verzeichnis auf der lokalen Platte dupliziert werden muss. Das
Kopieren eines Verzeichnisses auf dem Server jedoch besitzt
einen konstanten Zeitaufwand und ist die Art und Weise, auf
die die meisten Leute Zweige erstellen.
Da Sie nun einen Zweig des Projektes erzeugt haben, können Sie eine neue Arbeitskopie auschecken, um ihn zu benutzen:
$ svn checkout http://svn.example.com/repos/calc/branches/my-calc-branch A my-calc-branch/Makefile A my-calc-branch/integer.c A my-calc-branch/button.c Ausgecheckt, Revision 341.
An dieser Arbeitskopie ist nichts besonders; sie spiegelt
bloß ein anderes Verzeichnis im Repository wieder. Wenn Sie
Änderungen übergeben, wird sie Sally jedoch nicht sehen, wenn
sie aktualisiert, da sie eine Arbeitskopie von
/calc/trunk
hat. (Stellen Sie sicher,
dass Sie „Zweige durchlaufen“ weiter
unten in diesem Kapitel lesen: Der Befehl svn
switch ist eine Alternative für die Bereitstellung
einer Arbeitskopie eines Zweiges.)
Tun wir mal so, als ob eine Woche ins Land geht und die folgenden Übergaben stattfinden:
Sie machen eine Änderung an
/calc/branches/my-calc-branch/button.c
,
die die Revision 342 erzeugt.
Sie machen eine Änderung an
/calc/branches/my-calc-branch/integer.c
,
die die Revision 343 erzeugt.
Sally macht eine Änderung an
/calc/trunk/integer.c
, die die Revision
344 erzeugt.
Nun finden zwei unabhängige Entwicklungslinien (siehe
Abbildung 4.4, „Die Verzweigung der Geschichte einer Datei“) auf
integer.c
statt.
Es wird interessant, wenn Sie die Geschichte der
Änderungen an Ihrer Kopie von integer.c
betrachten:
$ pwd /home/user/my-calc-branch $ svn log -v integer.c ------------------------------------------------------------------------ r343 | user | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Geänderte Pfade: M /calc/branches/my-calc-branch/integer.c * integer.c: Wazjub gefrozzelt. ------------------------------------------------------------------------ r341 | user | 2002-11-03 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Geänderte Pfade: A /calc/branches/my-calc-branch (from /calc/trunk:340) Privaten Zweig von /calc/trunk angelegt. ------------------------------------------------------------------------ r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines Geänderte Pfade: M /calc/trunk/integer.c * integer.c: Einen Docstring geändert. ------------------------------------------------------------------------ r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines Geänderte Pfade: A /calc/trunk/integer.c * integer.c: Diese Datei dem Projekt hinzugefügt. ------------------------------------------------------------------------
Beachten Sie, dass Subversion die Geschichte von
integer.c
auf Ihrem Zweig über die
gesamte Zeit zurück verfolgt, und dabei sogar über den Punkt
hinweg geht, an dem es kopiert wurde. Es zeigt die Erzeugung
des Zweigs als ein Ereignis in der Geschichte, da
integer.c
implizit kopiert wurde, als
alles andere in /calc/trunk/
kopiert
wurde. Sehen Sie nun, was passiert, wenn Sally den gleichen
Befehl auf Ihre Arbeitskopie der Datei anwendet:
$ pwd /home/sally/calc $ svn log -v integer.c ------------------------------------------------------------------------ r344 | sally | 2002-11-07 15:27:56 -0600 (Thu, 07 Nov 2002) | 2 lines Changed paths: M /calc/trunk/integer.c * integer.c: fix a bunch of spelling errors. ------------------------------------------------------------------------ r303 | sally | 2002-10-29 21:14:35 -0600 (Tue, 29 Oct 2002) | 2 lines Changed paths: M /calc/trunk/integer.c * integer.c: changed a docstring. ------------------------------------------------------------------------ r98 | sally | 2002-02-22 15:35:29 -0600 (Fri, 22 Feb 2002) | 2 lines Changed paths: A /calc/trunk/integer.c * integer.c: adding this file to the project. ------------------------------------------------------------------------
Sally sieht ihre eigene Änderung in Revision 344, aber nicht die Änderung, die Sie in Revision 343 gemacht haben. Was Subversion angeht, hatten diese beiden Übergaben Auswirkungen auf unterschiedliche Dateien an unterschiedlichen Repository-Orten. Dennoch zeigt Subversion doch, dass die beiden Dateien einen Teil der Geschichte gemeinsam haben. Bevor die Kopie des Zweiges in Revision 341 gemacht wurde, waren die Dateien dieselbe Datei. Deshalb sehen sowohl Sie als auch Sally die Änderungen, die in den Revisionen 303 und 98 gemacht wurden.
Sie sollten sich zwei Lektionen aus diesem Abschnitt merken. Erstens besitzt Subversion kein internes Konzept für einen Zweig – es weiß lediglich, wie Kopien angelegt werden. Wenn Sie ein Verzeichnis kopieren, ist das entstehende Verzeichnis bloß ein „Zweig“, weil Sie ihm diese Bedeutung geben. Sie mögen über das Verzeichnis anders denken oder es anders behandeln, doch für Subversion ist es einfach ein gewöhnliches Verzeichnis, das nebenbei mit einigen zusätzlichen historischen Informationen ausgestattet ist.
Zweitens bestehen die Zweige von Subversion, bedingt durch
den Kopiermechanismus, als normale
Dateisystemverzeichnisse im Repository. Das ist ein
Unterschied zu anderen Versionskontrollsystemen, bei denen
Zweige typischerweise definiert werden, indem auf einer
eigenen Ebene den Dateisammlungen „Etiketten“
hinzugefügt werden. Der Ort Ihres Zweig-Verzeichnisses spielt
für Subversion keine Rolle. Die meisten Teams folgen der
Konvention, alle Zweige in einem Verzeichnis namens
/branches
abzulegen, jedoch steht es
Ihnen frei, eine Vorgehensweise nach Ihren Wünschen zu
erfinden.
Nun arbeiten Sie und Sally auf parallelen Zweigen des Projektes: Sie arbeiten auf einem privaten Zweig, und Sally arbeitet auf dem Stamm oder dem Hauptzweig der Entwicklung.
Bei Projekten mit einer großen Zahl von Mitarbeitern haben die meisten gewöhnlich Arbeitskopien vom Stamm. Sobald jemand eine langwierige Änderung machen muss, die wahrscheinlich den Stamm stören würde, ist die Standardvorgehensweise, einen Zweig zu erzeugen und die Änderungen bis zum Abschluss der Arbeiten nach dorthin zu übergeben.
Die gute Nachricht ist also, dass Sie und Sally sich nicht in die Quere kommen. Die schlechte Nachricht ist, dass es sehr leicht ist, zu weit auseinander zu treiben. Erinnern Sie sich, dass eins der Probleme bei der Strategie „sich in ein Loch zu verkriechen“ war, dass es zu dem Zeitpunkt, an dem Sie mit dem Zweig fertig sind, fast unmöglich sein kann, Ihre Änderungen ohne eine riesige Zahl an Konflikten auf den Stamm zurückzuführen.
Stattdessen könnten Sie und Sally fortfahren, während der Arbeit Änderungen gemeinsam zu verwenden. Es liegt an Ihnen, zu entscheiden, welche Änderungen teilenswert sind; Subversion bietet Ihnen die Fähigkeit, Änderungen selektiv zwischen Zweigen zu „kopieren“. Und wenn Sie mit Ihrem Zweig vollständig fertig sind, kann die gesamte Menge Ihrer Änderungen vom Zweig auf den Stamm zurück kopiert werden. In der Terminologie von Subversion heißt der allgemeine Vorgang, Änderungen von einem Zweig auf einen anderen zu übertragen Zusammenführen (Merging) und wird durch verschiedene Aufrufe des Befehls svn merge durchgeführt.
In den folgenden Beispielen gehen wir davon aus, dass sowohl auf Ihrem Subversion-Client als auch auf dem Server Subversion 1.5 (oder neuer) läuft. Falls einer von beiden älter als Version 1.5 ist, wird es komplizierter: Das System wird Änderungen nicht automatisch mitverfolgen, so dass Sie schmerzhafte manuelle Methoden anwenden müssen, um ähnliche Resultate zu erzielen. Dass heißt, dass Sie stets die detaillierte Syntax beim Zusammenführen verwenden müssen, um bestimmte Revisionsintervalle zu übertragen (siehe „Merge-Syntax: Die vollständige Enthüllung“ weiter unten in diesem Kapitel), und besonders sorgfältig verfolgen müssen, was bereits zusammengeführt ist und was nicht. Aus diesem Grund empfehlen wir Ihnen dringend, sicherzustellen, dass Ihr Client und Server mindestens die Version 1.5 haben.
Bevor wir weitermachen, sollten wir Sie warnen, dass Sie auf den kommenden Seiten viele Erörterungen zum Thema „Änderungen“ erwarten. Viele mit Versionskontrollsystemen erfahrene Leute benutzen die Begriffe „Änderung“ und „Änderungsmenge“ (Changeset) austauschbar, so dass wir klären sollten, was Subversion unter einer Änderungsmenge versteht.
Jeder scheint eine etwas unterschiedliche Definition für den Begriff Änderungsmenge zu haben oder zumindest eine unterschiedliche Erwartung darüber, was es für ein Versionskontrollsystem bedeutet, so etwas zu besitzen. Für unsere Zwecke reicht es aus, zu sagen, dass eine Änderungsmenge lediglich eine Sammlung von Änderungen mit einem eindeutigen Namen ist. Die Änderungen können aus der Bearbeitung an Textdateien, Modifizierungen an der Baumstruktur oder Justierungen an Metadaten bestehen. In einfachen Worten ist eine Änderungsmenge einfach ein Patch mit einem Namen, auf den Sie sich beziehen können.
In Subversion bezeichnet eine globale Revisionsnummer N
einen Baum im Repository: Sie beschreibt das Aussehen des
Repositorys nach der N-ten Übergabe. Sie ist auch der Name
einer impliziten Änderungsmenge: Wenn Sie den Baum N mit dem
Baum N−1 vergleichen, können Sie genau den Patch
ableiten, der übergeben wurde. Daher ist es einfach, sich
Revision N nicht nur als Baum sondern auch als Änderungsmenge
vorzustellen. Falls Sie ein Fehlerverwaltungssystem verwenden,
können Sie die Revisionsnummern benutzen, um auf bestimmte
Patches zu verweisen, die Fehler beheben – zum Beispiel:
„Dieser Fehler wurde durch r9238 behoben“. Dann
kann jemand svn log -r 9238
aufrufen,
um den Protokolleintrag zu genau der Änderungsmenge zu lesen,
die den Fehler behoben hat, und sich mit svn diff
-c 9238
den eigentlichen Patch ansehen. Und auch
(wie Sie bald sehen werden) der Subversion Befehl svn
merge kann Revisionsnummern verwenden. Sie können
bestimmte Änderungsmengen von einem Zweig mit einem anderen
zusammenführen, indem sie in den Argumenten zum entsprechenden
Kommando benannt werden: Die Übergabe von -c
9238
an svn merge würde das
Änderungsmenge r9238 mit Ihrer Arbeitskopie
zusammenführen.
Machen wir mit unserem Beispiel weiter und nehmen an, dass
eine Woche vergangen ist seitdem Sie begonnen haben, auf
Ihrem privaten Zweig zu arbeiten. Ihre Arbeit ist noch nicht
beendet, jedoch wissen Sie, dass gleichzeitig andere Leute in
Ihrem Team weiterhin wichtige Änderungen im
/trunk
des Projektes gemacht haben. Es
ist in Ihrem Interesse, diese Änderungen in Ihren Zweig zu
übernehmen, um sicherzustellen, dass sie sich gut mit Ihren
Änderungen vertragen. Dies ist tatsächlich eine der besten
Vorgehensweisen: Ihren Zweig regelmäßig mit der
Hauptentwicklungslinie zu synchronisieren hilft,
„überraschende“ Konflikte zu vermeiden, wenn es
an der Zeit ist, Ihre Änderungen zurück auf den Stamm zu
bringen.
Subversion kennt die Geschichte Ihres Zweigs und weiß, wann Sie ihn vom Stamm abgezweigt haben. Um die letzten, aktuellsten Änderungen vom Stamm auf Ihren Zweig zu bringen, sollten Sie zunächst sicherstellen, dass die Arbeitskopie des Zweigs „sauber“ ist – dass sie keine lokalen Änderungen hat, die durch svn status angezeigt werden. Dann rufen Sie einfach die folgenden Befehle auf:
$ pwd /home/user/my-calc-branch $ svn merge http://svn.example.com/repos/calc/trunk --- Zusammenführen von r345 bis r356 in ».«: U button.c U integer.c
Diese einfache Syntax – svn merge
– fordert
Subversion auf, alle neuen Änderungen von dem URL mit dem
aktuellen Arbeitsverzeichnis (welches typischerweise das
Wurzelverzeichnis Ihrer Arbeitskopie ist)
zusammenzuführen. Nach dem Ausführen des vorangegangenen
Beispiels enthält Ihre Arbeitskopie nun neue lokale
Änderungen, die Nachbildungen all der Änderungen auf dem Stamm
seit der Erstellung Ihres Zweiges sind:URL
$ svn status M . M button.c M integer.c
Zu diesem Zeitpunkt ist es weise, sich die Änderungen
mithilfe von svn diff sorgfältig anzusehen,
und anschließend die Software von Ihrem Zweig zu bauen und zu
testen. Beachten Sie, dass auch das aktuelle
Arbeitsverzeichnis („.
“)
verändert wurde; svn diff zeigt an, dass
seine Eigenschaft svn:mergeinfo
entweder
angelegt oder modifiziert wurde. Das ist ein wichtiges
Metadatum in Zusammenhang mit Zusammenführungen, das Sie
nicht anfassen sollten, da es von
künftigen svn merge-Befehlen benötigt wird.
(Wir werden später in diesem Kapitel mehr über diese Metadaten
erfahren.)
Nach der Übernahme kann es möglich sein, dass Sie noch
einige Konflikte auflösen müssen (wie bei svn
update) oder möglicherweise noch einige kleinere
Bearbeitungen durchzuführen haben, damit alles wieder
funktioniert. (Denken Sie daran, dass die Abwesenheit
syntaktischer Konflikte nicht bedeutet,
dass keine semantischen Konflikte
vorhanden sind!) Falls ernsthafte Probleme auftauchen, können
Sie jederzeit die lokalen Änderungen mit svn revert
. -R
wieder rückgängig machen und eine lange
„was geht hier eigentlich vor“-Unterredung mit
Ihren Mitarbeitern führen. Falls jedoch alles gut aussieht,
können Sie die Änderungen an das Repository übergeben:
$ svn commit -m "Die letzten Änderungen von trunk mit my-calc-branch zusammengeführt." Sende . Sende button.c Sende integer.c Übertrage Daten .. Revision 357 übertragen.
An dieser Stelle ist Ihr Zweig „synchron“ mit dem Stamm, und Sie können sich ruhig zurücklehnen in der Gewissheit, dass Sie sich nicht zu weit von der Arbeit aller anderen entfernen, während Sie isoliert weiterarbeiten.
Nehmen wir an, noch eine Woche sei ins Land gegangen. Sie haben weitere Änderungen an Ihren Zweig übergeben, und Ihre Kollegen haben damit weitergemacht, den Stamm zu verbessern. Nun möchten Sie mal wieder die letzten Änderungen vom Stamm mit Ihrem Zweig abgleichen, damit Sie wieder synchron sind. Starten Sie einfach noch einmal den svn merge-Befehl!
$ svn merge http://svn.example.com/repos/calc/trunk --- Zusammenführen von r357 bis r380 in ».«: U integer.c U Makefile A README
Subversion weiß, welche Änderungen Sie bereits mit Ihrem Zweig abgeglichen haben, so dass es sorgfältig nur die Änderungen berücksichtigt, die Sie noch nicht haben. Einmal mehr müssen Sie bauen, testen und die lokalen Änderungen an Ihren Zweig mit svn commit übergeben.
Was passiert jedoch, wenn Sie schließlich Ihre Arbeit abgeschlossen haben? Ihre neue Funktion ist fertig, und Sie sind bereit, die Änderungen von Ihrem Zweig zurück auf den Stamm zu überführen (so dass Ihr Team die Früchte Ihrer Arbeit genießen kann). Die Vorgehensweise ist einfach. Zunächst synchronisieren Sie Ihren Zweig noch einmal mit dem Stamm, wie Sie es bisher gemacht haben:
$ svn merge http://svn.example.com/repos/calc/trunk --- Zusammenführen von r381 bis r385 in ».«: U button.c U README $ # bauen, testen, ... $ svn commit -m "Letzte Zusammenführung der Änderungen von trunk changes in my-calc-branch." Sende . Sende button.c Sende README Übertrage Daten .. Revision 390 übertragen.
Nun verwenden Sie svn merge, um Ihre
Änderungen vom Zweig zurück auf den Stamm zu überführen. Sie
benötigen eine aktuelle Arbeitskopie von
/trunk
. Sie bekommen sie entweder durch
svn checkout, indem Sie von irgendwo auf
Ihrer Platte eine alte Arbeitskopie vom Stamm hervorholen,
oder den Befehl svn switch (siehe „Zweige durchlaufen“) verwenden. Wie auch
immer Sie Ihre Arbeitskopie bereitstellen, denken Sie daran,
dass Sie die Überführung in einer Arbeitskopie durchführen,
die keine lokalen Änderungen beinhaltet
und jüngst aktualisiert wurde (d.h., keine Mischung aus
lokalen Revisionen ist). Falls Ihre Arbeitskopie nicht
„sauber“ in diesem Sinn ist, könnte es Ihnen
einige unnötige konfliktbezogene Kopfschmerzen bereiten, und
svn merge wird wahrscheinlich einen Fehler
ausgeben.
Sobald Sie eine saubere Arbeitskopie des Stamms haben, sind Sie bereit, Ihren Zweig damit zusammenzuführen:
$ pwd /home/user/calc-trunk $ svn update # (stellen Sie sicher, dass die Arbeitskopie aktuell ist) Revision 390. $ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch -- Zusammenführen der Unterschiede zwischen Projektarchiv-URLs in ».«: U button.c U integer.c U Makefile U . $ # bauen, testen, überprüfen, ... $ svn commit -m "Merge my-calc-branch back into trunk!" Sende . Sende button.c Sende integer.c Sende Makefile Übertrage Daten .. Revision 391 übertragen.
Gratulation! Ihr Zweig ist nun zurück in die
Hauptentwicklungslinie überführt worden. Beachten Sie, dass
dieses Mal die Option --reintegrate
verwendet
wurde. Diese Option ist kritisch, wenn Änderungen von einem
Zweig in die ursprüngliche Entwicklungslinie reintegriert
werden – vergessen Sie sie nicht! Sie wird benötigt, da
diese Art der „Rücküberführung“ etwas anderes
ist, als was Sie bisher gemacht haben. Vorher haben wir
svn merge aufgefordert, die „nächste
Änderungsmenge“ von einer Entwicklungslinie (dem Stamm)
zu holen und sie mit einer anderen (Ihrem Zweig)
abzugleichen. Das ist recht überschaubar, und Subversion weiß
jedesmal, wo es wieder ansetzen soll. Bei unseren
vorangehenden Beispielen können Sie sehen, dass es erst die
Intervalle 345:356 vom Stamm auf den Zweig überführte; später
fuhr es mit dem nächsten verfügbaren aufeinanderfolgenden
Intervall 356:380 fort. Wenn Sie die letzte Synchronisierung
machen, wird es das Intervall 380:385 zusammenführen.
Wenn Sie jedoch den Zweig auf den Stamm zurückführen,
sehen die dem zugrundeliegenden Berechnungen ganz anders
aus. Ihr Zweig ist nun ein Mischmasch aus abgeglichenen
Änderungen vom Stamm und privaten Änderungen auf dem Zweig, so
dass es kein einfaches, aufeinanderfolgendes Intervall mit
Revisionen zum Herüberkopieren gibt. Indem Sie die Option
--reintegrate
angeben, fordern Sie Subversion
auf, sorgfältig nur die Änderungen von
Ihrem Zweig zu replizieren. (Und tatsächlich macht es das so,
dass es die letzte Version auf dem Stamm mit der letzten
Version auf dem Zweig vergleicht: Der Unterschied macht genau
die Änderung auf dem Zweig aus!)
Nachdem nun Ihr privater Zweig mit dem Stamm zusammengeführt wurde, können Sie ihn aus dem Repository löschen:
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \ -m "Remove my-calc-branch." Revision 392 übertragen.
Aber halt! Ist die Geschichte des Zweigs nicht wertvoll?
Was, wenn jemand sich eines Tages die Evolution Ihrer Funktion
ansehen möchte und hierfür auf die Änderungen des Zweiges
schauen möchte? Keine Sorge! Denken Sie daran, dass, obwohl
Ihr Zweig nicht mehr im Verzeichnis
/branches
sichtbar ist, seine Existenz
gleichwohl ein unveränderbarer Teil der Geschichte des
Repositorys ist. Ein einfacher Befehl svn
log auf dem /branches
URL wird
die gesamte Geschichte des Zweiges anzeigen. Ihr Zweig kann
eines Tages sogar wiederbelebt werden, sollten Sie dieses
wünschen (siehe „Zurückholen gelöschter Objekte“).
Sobald in Subversion 1.5 eine Zusammenführung mit
--reintegrate
vom Zweig auf den Stamm
durchgeführt wurde, kann der Zweig nicht mehr für weitere
Arbeiten verwendet werden. Er kann weder Änderungen vom Stamm
korrekt absorbieren, noch kann er ordentlich auf den Stamm
zurückintegriert werden. Aus diesem Grund sollten Sie ihn
zerstören und erneut aus dem Stamm erzeugen, wenn Sie weiter
auf dem Zweig arbeiten wollen:
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \ -m "my-calc-branch löschen." Revision 392 übertragen. $ svn copy http://svn.example.com/repos/calc/trunk \ http://svn.example.com/repos/calc/branches/new-branch -m "Einen neuen Zweig von trunk anlegen." Revision 393 übertragen. $ cd my-calc-branch $ svn switch http://svn.example.com/repos/calc/branches/new-branch Aktualisiert zu Revision 393.
Der letzte Befehl des vorangegangenen Beispiels – svn switch – ist eine Art, ein bestehendes Arbeitsverzeichnis auf ein unterschiedliches Repository-Verzeichnis zu aktualisieren. Wir werden das genauer in „Zweige durchlaufen“ besprechen.
Der grundsätzliche Mechanismus, den Subversion verwendet,
um Änderungsmengen zu verfolgen – d.h. welche Änderungen
auf welchen Zweig übertragen worden sind – besteht aus
dem Festhalten von Daten in Eigenschaften. Daten über das
Zusammenführen werden speziell in der Eigenschaft
svn:mergeinfo
vermerkt, die an Dateien und
Verzeichnissen hängt. (Falls Sie mit Subversion-Eigenschaften
nicht vertraut sind, ist es nun an der Zeit, „Properties“ zu überfliegen.)
Sie können sich die Eigenschaft ansehen, wie jede andere auch:
$ cd my-calc-branch $ svn propget svn:mergeinfo . /trunk:341-390
Es wird nicht empfohlen, dass Sie
selbst den Wert dieser Eigenschaft ändern, es sei denn, Sie
wissen wirklich, was Sie tun. Diese Eigenschaft wird
automatisch von Subversion gepflegt, sobald Sie den Befehl
svn merge ausführen. Ihr Wert gibt
Aufschluss darüber, welche Änderungen (von einem gegebenen
Pfad) mit dem in Frage kommenden Verzeichnis abgeglichen
wurden. In diesem Fall ist der Pfad
/trunk
, und das Verzeichnis, das die
bestimmten Änderungen erhalten hat, ist
/branches/my-calc-branch
.
Es gibt auch einen Unterbefehl, svn mergeinfo, der hilfreich dabei ist, nicht nur die Änderungsmengen anzuzeigen, die ein Verzeichnis absorbiert hat, sondern auch, welche Änderungsmengen für einen Abgleich noch in Frage kommen. Das ergibt eine Art Vorschau der nächsten Änderungsmengen, die svn merge auf Ihren Zweig abgleichen wird.
$ cd my-calc-branch # Welche Änderungen wurden bereits vom Stamm auf den Zweig abgeglichen? $ svn mergeinfo http://svn.example.com/repos/calc/trunk r341 r342 r343 … r388 r389 r390 # Welche Änderungen kommen für einen Abgleich vom Stamm auf den Zweig noch in Frage? $ svn mergeinfo http://svn.example.com/repos/calc/trunk --show-revs eligible r391 r392 r393 r394 r395
Der Befehl svn mergeinfo erwartet einen
„Quell“-URL (woher die Änderungen kommen würden)
und einen optionalen „Ziel“-URL (wohin die
Änderungen abgeglichen würden). Falls kein Ziel-URL angegeben
ist, wird angenommen, dass das aktuelle Arbeitsverzeichnis das
Ziel ist. Weil wir im vorangegangenen Beispiel unser
Arbeitsverzeichnis vom Zweig abfragen, geht der Befehl davon
aus, dass wir daran interessiert sind, Änderungen für
/branches/mybranch
vom angegebenen
Stamm-URL zu erhalten.
Eine andere Methode, eine genauere Vorschau auf einen
Abgleich zu bekommen, ist die Verwendung der Option
--dry-run
:
$ svn merge http://svn.example.com/repos/calc/trunk --dry-run U integer.c $ svn status # es wird nichts ausgegeben, die Arbeitskopie ist unverändert
Die Option --dry-run
macht tatsächlich
überhaupt keine lokalen Änderungen an der Arbeitskopie. Sie
zeigt nur Status-Codes, die ausgegeben
würden, wenn ein echter Abgleich
stattfände. Sie ist nützlich, um eine Vorschau für einen
möglichen Abgleich auf „hoher Ebene“ zu erhalten,
falls svn diff zu detailliert wäre.
Nach dem Durchführen eines Abgleichs, aber vor der
Übergabe des Ergebnisses, können Sie svn diff
--depth=empty
verwenden, um nur die Änderungen am unmittelbaren Ziel des
Abgleichs zu sehen. Falls das Ziel ein Verzeichnis war,
werden nur Unterschiede von Eigenschaften angezeigt. Das ist
eine praktische Methode, um sich die Änderungen an der
Eigenschaft /pfad/zum/abgleichs/ziel
svn:mergeinfo
anzusehen, die
dort durch den Abgleich vermerkt wurden, und die Sie daran
erinnern, was Sie eben abgeglichen haben.
Natürlich ist die beste Methode, eine Vorschau eines
Abgleichs zu erhalten, ihn zu machen! Denken Sie daran, dass
der Aufruf von svn merge an sich nichts
Riskantes ist (es sei denn, sie haben lokale Änderungen an
Ihrer Arbeitskopie gemacht – aber wir haben bereits
betont, dass Sie in eine derartige Umgebung nicht abgleichen
sollten). Falls Ihnen das Ergebnis des Abgleichs nicht
gefallen sollte, rufen Sie einfach svn revert
. -R
auf, um die Änderungen an Ihrer Arbeitskopie
rückgängig zu machen, und versuchen Sie den Befehl erneut mit
unterschiedlichen Optionen. Der Abgleich ist solange nicht
endgültig, bis Sie mit svn commit das
Ergebnis übergeben.
Während es vollkommen in Ordnung ist, durch wiederholte Aufrufe von svn merge und svn revert mit Abgleichen zu experimentieren, könnte es allerdings sein, dass Sie über einige lästige (aber leicht zu umgehende) Fallstricke stolpern. Wenn zum Beispiel durch den Abgleich eine neue Datei hinzugefügt wird (d.h., sie wird zum Hinzufügen markiert), so wird svn revert sie nicht wirklich entfernen; es entfernt lediglich die Markierung zum Hinzufügen. Was übrig bleibt, ist eine unversionierte Datei. Wenn Sie dann den Abgleich erneut versuchen, könnten Sie einen Konflikt bekommen, weil die unversionierte Datei „im Weg steht“. Die Lösung? Nach dem Rückgängigmachen sollten Sie die Arbeitskopie aufräumen und unversionierte Dateien und Verzeichnisse entfernen. Die Ausgabe von svn status sollte so sauber wie möglich sein und idealerweise gar nichts anzeigen.
Sehr häufig wird svn merge verwendet,
um eine Änderung rückgängig zu machen, die bereits an das
Repository übergeben worden war. Nehmen wir einmal an, Sie
arbeiten fröhlich in einer Arbeitskopie von
/calc/trunk
und entdecken, dass die
damalige Änderung an integer.c
in
Revision 303 völlig falsch war. Sie hätte nie übergeben werden
sollen. Sie können svn merge verwenden, um
die Änderung in Ihrer Arbeitskopie
„zurückzunehmen“, und dann die lokale Änderung an
das Repository übergeben. Alles, was Sie hierfür tun müssen,
ist, eine umgekehrte Differenz anzugeben.
(Sie machen das durch die Angabe von --revision
303:302
oder durch das äquivalente --change
-303
.)
$ svn merge -c -303 http://svn.example.com/repos/calc/trunk --- Reverse-merging r303 into 'integer.c': -- Rückwärtiges Zusammenführen von r303 in »integer.c«: U integer.c $ svn status M . M integer.c $ svn diff … # überprüfen, ob die Änderung entfernt wurde … $ svn commit -m "Änderung aus in r303 rückgängig machen." Sende integer.c Übertrage Daten . Revision 350 übertragen.
Wie wir früher bereits erwähnten, kann man eine
Repository-Version als eine bestimmte Änderungsmenge
betrachten. Bei Verwendung der Option -r
wird
svn merge aufgefordert, eine Änderungsmenge
oder ein ganzes Intervall von Änderungsmengen auf Ihre
Arbeitskopie anzuwenden. In unserem Fall, bei dem wir eine
Änderung zurücknehmen, fordern wir svn
merge auf, die Änderungsmenge #303
rückwärts auf unsere Arbeitskopie
anzuwenden.
Merken Sie sich, dass ein solches Rückgängigmachen wie
jeder andere svn merge-Vorgang ist, so dass
Sie svn status und svn
diff benutzen sollten, um sicherzustellen, dass Ihre
Arbeit in dem Zustand ist, den Sie haben möchten, und
verwenden Sie anschließend svn commit, um
die endgültige Version in das Repository zu bringen. Nach der
Übergabe wird sich diese bestimmte Änderungsmenge nicht mehr
in der HEAD
-Revision wiederfinden.
Nun denken Sie vielleicht: Gut, aber das hat doch nicht
wirklich die Übergabe rückgängig gemacht, oder? Die Änderung
besteht immer noch in Revision 303. Falls jemand eine Version
des Projektes calc
zwischen den
Revisionen 303 und 349 auscheckt, wird doch trotzdem die
fehlerhafte Änderung sichtbar, oder nicht?
Ja, das stimmt. Wenn wir davon sprechen, eine Änderung zu
„entfernen“, sprechen wir eigentlich darüber, sie
aus der HEAD
-Revision zu entfernen. Die
ursprüngliche Änderung besteht immer noch in der Geschichte
des Repositorys. Für die meisten Situationen ist das
ausreichend. Die meisten Leute sind sowieso nur am
HEAD
eines Projektes interessiert. Es gibt
jedoch Spezialfälle, in denen Sie wirklich alle Beweise der
Übergabe vernichten möchten. (Vielleicht hat jemand ein
vertrauliches Dokument in das Repository übergeben.) Das ist
leider nicht so einfach, da Subversion absichtlich so
konstruiert wurde, dass es niemals Informationen
verliert. Revisionen sind unveränderliche Bäume, die
aufeinander aufbauen. Die Beseitigung einer Revision aus der
Geschichte würde einen Dominoeffekt auslösen, Chaos in allen
nachfolgenden Revisionen anrichten und möglicherweise alle
Arbeitskopien ungültig machen.
[21]
Das Tolle an Versionskontrollsystemen ist, dass
Informationen nie verlorengehen. Selbst wenn Sie eine Datei
oder ein Verzeichnis löschen, ist es zwar nicht mehr in der
HEAD
-Revision vorhanden, jedoch noch in
früheren Revisionen. Eine der häufigsten Fragen neuer Benutzer
ist: „Wie bekomme ich meine alte Datei oder mein altes
Verzeichnis zurück?“
Der erste Schritt ist es, genau zu definieren welches Objekt Sie zurückholen möchten. Hier ist eine nützliche Metapher: Sie können sich vorstellen, dass jedes Objekt im Repository in einem zweidimensionalen Koordinatensystem befindet. Die erste Koordinate ist ein bestimmter Revisionsbaum und die zweite Koordinate ist ein Pfad innerhalb dieses Baumes. So kann jede Version Ihrer Datei oder Ihres Verzeichnisses durch ein bestimmtes Koordinatenpaar definiert werden. (Erinnern Sie sich an die Syntax einer „Peg-Revision“ – foo.c@224 – die in „Peg and Operative Revisions“ erwähnt wurde.)
Zunächst sollten Sie svn log benutzen,
um das exakte Koordinatenpaar zu ermitteln, das Sie
zurückholen wollen. Eine gute Strategie ist es, svn
log --verbose
in einem Verzeichnis aufzurufen, in
dem das gelöschte Objekt einmal enthalten war. Die Option
--verbose
(-v
) gibt eine
Liste aller geänderten Objekte in jeder Revision aus; Sie
müssen nur noch die Revision finden, in der Sie die Datei oder
das Verzeichnis gelöscht haben. Sie können das visuell tun
oder ein Werkzeug zur Untersuchung der Protokollausgaben
einsetzen (mit grep oder vielleicht durch
eine inkrementelle Suche in einem Editor).
$ cd parent-dir $ svn log -v … ------------------------------------------------------------------------ r808 | joe | 2003-12-26 14:29:40 -0600 (Fri, 26 Dec 2003) | 3 lines Geänderte Pfade: D /calc/trunk/real.c M /calc/trunk/integer.c Schnelle Funktionen zur Fourier-Transformation zu integer.c hinzugefügt. real.c gelöscht, da Code jetzt in double.c. …
In diesem Beispiel nehmen wir an, dass Sie nach der
gelöschten Datei real.c
suchen. Beim
Durchsehen der Protokolle des Elternverzeichnisses haben Sie
entdeckt, dass diese Datei in Revision 808 gelöscht
wurde. Daher war die letzte Revision in der die Datei noch
vorhanden war die unmittelbare Vorgänger-Revision. Die
Schlussfolgerung: Sie möchten den Pfad
/calc/trunk/real.c
aus Revision 807
zurückholen.
Das war der schwierige Teil – die Nachforschung. Nun, da Sie wissen, was Sie wiederherstellen wollen, haben Sie die Wahl zwischen zwei verschiedenen Methoden.
Die eine Option ist, svn merge zu
verwenden, um Revision 808 „rückwärts“
anzuwenden. (Wir haben bereits in
„Änderungen rückgängig machen“
besprochen, wie Änderungen rückgängig gemacht werden.) Das
hätte den Effekt, real.c
als lokale
Änderung erneut hinzuzufügen. Die Datei würde zum Hinzufügen
ins Repository markiert, und nach der Übergabe wäre die Datei
wieder in HEAD
vorhanden.
In diesem besonderen Beispiel ist das aber wahrscheinlich
nicht die beste Strategie. Die Rückwärts-Anwendung von
Revision 808 würde nicht nur real.c
zum
Hinzufügen markieren, sondern, wie aus den Protokollmeldungen
hervorgeht, dass ebenso bestimmte Änderungen an
integer.c
zurücknehmen, was Sie aber
nicht wollen. Sie können sicherlich Revision 808 rückwärts
anwenden und dann mit svn revert die
lokalen Änderungen an integer.c
zurücknehmen; allerdings ist diese Technik nicht sehr
effektiv. Was wäre, wenn 90 Dateien in Revision 808 geändert
worden wären?
Eine zweite, zielorientiertere, Strategie ist es, den Befehl svn merge überhaupt nicht zu verwenden, sondern stattdessen svn copy. Kopieren Sie einfach das exakte „Koordinatenpaar“ aus Revision und Pfad vom Repository in Ihre Arbeitskopie:
$ svn copy http://svn.example.com/repos/calc/trunk/real.c@807 ./real.c $ svn status A + real.c $ svn commit -m "real.c aus revision 807 wiederhergestellt, /calc/trunk/real.c." Hinzufügen real.c Übertrage Daten . Revision 1390 übertragen.
Das Plus-Zeichen in der Statusausgabe zeigt an, dass das
Objekt nicht bloß zu Hinzufügen vorgemerkt ist, sondern zum
Hinzufügen „mit Geschichte“. Subversion merkt
sich, woher es kopiert wurde. Künftig wird beim Anwenden von
svn log auf diese Datei die gesamte
Geschichte, über das Zurückholen hinweg, inklusive der
Geschichte vor Revision 807 durchlaufen. In anderen Worten,
dieses neue real.c
ist nicht wirklich
neu; es ist ein direkter Nachfahre der ursprünglichen,
gelöschten Datei. Dies ist normalerweise eine gute und
nützliche Sache. Falls Sie jedoch die Datei
ohne geschichtliche Verbindung zur alten
Datei zurückholen wollen, funktioniert diese Technik
ebensogut:
$ svn cat http://svn.example.com/repos/calc/trunk/real.c@807 > ./real.c $ svn add real.c A real.c $ svn commit -m "real.c aus Revision 807 wiederhergestellt." Hinzufügen real.c Übertrage Daten . Revision 1390 übertragen.
Obwohl unser Beispiel zeigt, wie eine Datei zurückgeholt wird, sollten sie beachten, dass dieselben Techniken auch beim Wiederherstellen von gelöschten Verzeichnissen funktionieren. Beachten Sie auch, dass die Wiederherstellung nicht unbedingt in Ihrer Arbeitskopie passieren muss – sie kann auch vollständig im Repository ausgeführt werden:
$ svn copy http://svn.example.com/repos/calc/trunk/real.c@807 \ http://svn.example.com/repos/calc/trunk/ \ -m "real.c aus Revision 807 wiederhergestellt." Revision 1390 übertragen. $ svn update A real.c Aktualisiert zu Revision 1390.
Hier endet die automatische Magie. Früher oder später, sobald Sie den Dreh beim Verzweigen und Zusammenführen heraus haben, werden Sie Subversion fragen müssen, bestimmte Änderungen von einem Ort zum anderen zusammenzuführen. Um dies tun zu können, werden Sie damit beginnen müssen, kompliziertere Argumente an svn merge zu übergeben. Der nächste Abschnitt beschreibt die vollständig erweiterte Syntax des Befehls und behandelt eine Anzahl verbreiteter Szenarien, die diese benötigen.
Genauso oft wie der Begriff „Änderungsmenge“ wird die Wendung die Rosinen herauspicken in Versionskontrollsystemen verwendet. Das bezieht sich darauf, eine bestimmte Änderungsmenge von einem Zweig auszuwählen und sie auf einen anderen anzuwenden. Die Rosinen herauszupicken kann sich auch darauf beziehen, eine bestimmte Menge von (nicht notwendigerweise angrenzenden) Änderungsmengen von einem auf einen anderen Zweig zu duplizieren. Dies steht im Gegensatz zu den üblicheren Zusammenführungs-Szenarien, bei denen der „nächste“ zusammenhängende Bereich von Revisionen automatisch dupliziert wird.
Warum sollte jemand nur eine einzelne Änderung wollen? Das
kommt häufiger vor, als Sie denken. Gehen wir beispielsweise
einmal zurück in die Vergangenheit und stellen uns vor, dass
Sie Ihren Zweig noch nicht wieder mit dem Stamm
zusammengeführt hätten. In der Kaffeeküche bekommen Sie mit,
dass Sally eine interessante Änderung an
integer.c
auf dem Stamm gemacht hat. Als
Sie sich die Geschichte der Übergaben auf dem Stamm ansehen,
entdecken Sie, dass sie in Revision 355 einen kritischen
Fehler beseitigt hat, der direkte Auswirkungen auf die
Funktion hat, an der Sie gerade arbeiten. Es kann sein, dass
Sie noch nicht bereit sind, alle Änderungen vom Stamm zu
übernehmen, jedoch benötigen Sie diese bestimmte
Fehlerbehebung, um mit Ihrer Arbeit weitermachen zu
können.
$ svn diff -c 355 http://svn.example.com/repos/calc/trunk Index: integer.c =================================================================== --- integer.c (revision 354) +++ integer.c (revision 355) @@ -147,7 +147,7 @@ case 6: sprintf(info->operating_system, "HPFS (OS/2 or NT)"); break; case 7: sprintf(info->operating_system, "Macintosh"); break; case 8: sprintf(info->operating_system, "Z-System"); break; - case 9: sprintf(info->operating_system, "CP/MM"); + case 9: sprintf(info->operating_system, "CP/M"); break; case 10: sprintf(info->operating_system, "TOPS-20"); break; case 11: sprintf(info->operating_system, "NTFS (Windows NT)"); break; case 12: sprintf(info->operating_system, "QDOS"); break;
Ebenso wie Sie svn diff im vorigen Beispiel benutzt haben, um sich Revision 355 anzusehen, können Sie die gleiche Option an svn merge übergeben:
$ svn merge -c 355 http://svn.example.com/repos/calc/trunk U integer.c $ svn status M integer.c
Sie können nun Ihre üblichen Tests durchführen, bevor Sie diese Änderung an den Zweig übergeben. Nach der Übergabe merkt sich Subversion, dass r355 mit dem Zweig zusammengeführt wurde, so dass künftige „magische“ Zusammenführungen, die Ihren Zweig mit dem Stamm synchronisieren, r355 überspringen. (Das Zusammenführen derselben Änderung auf denselben Zweig führt fast immer zu einem Konflikt!)
$ cd my-calc-branch $ svn propget svn:mergeinfo . /trunk:341-349,355 # Beachten Sie, dass r355 nicht als Zusammenführungs-Kandidat aufgeführt wird # da es bereits zusammengeführt wurde. $ svn mergeinfo http://svn.example.com/repos/calc/trunk --show-revs eligible r350 r351 r352 r353 r354 r356 r357 r358 r359 r360 $ svn merge http://svn.example.com/repos/calc/trunk --- Zusammenführen von r350 bis r354 in ».«: U . U integer.c U Makefile --- Zusammenführen von r356 bis r360 in ».«: U . U integer.c U button.c
Dieser Anwendungsfall des Abgleichens (oder Nachziehens) von Fehlerbehebungen von einem Zweig zu einem anderen ist vielleicht der gängigste Grund für Änderungen, die Rosinen herauszupicken; es kommt ständig vor, beispielsweise, wenn ein Team einen „Software-Release-Zweig“ verwendet. (Wir erörtern dieses Muster in „Release-Zweige“.)
Haben Sie bemerkt, wie im letzten Beispiel der Aufruf von svn merge dazu geführt hat, zwei unterschiedliche Abgleichsintervalle anzuwenden? Der Befehl führte zwei unabhängige Patches auf Ihrer Arbeitskopie aus, um die Änderungsmenge 355 zu überspringen, die Ihr Zweig bereits beinhaltete. An und für sich ist daran nichts falsch, bis auf die Tatsache, dass die Möglichkeit besteht, eine Konfliktauflösung komplizierter zu machen. Falls das erste Änderungsintervall Konflikte erzeugt, müssen Sie diese interaktiv auflösen, um die Zusammenführung fortzusetzen und das zweite Änderungsintervall anzuwenden. Wenn Sie die Konfliktauflösung der ersten Phase aufschieben, wird der komplette Zusammenführungsbefehl mit einer Fehlermeldung abbrechen. [22]
Ein Wort zur Warnung: Während svn diff und svn merge vom Konzept her sehr ähnlich sind, haben sie in vielen Fällen eine unterschiedliche Syntax. Gehen Sie sicher, dass Sie Details hierzu in Kapitel 9, Subversion Complete Reference nachlesen oder svn help fragen. Zum Beispiel benötigt svn merge einen Pfad in der Arbeitskopie als Ziel, d.h., einen Ort, an dem es den erzeugten Patch anwenden kann. Falls das Ziel nicht angegeben wird, nimmt es an, dass Sie eine der folgenden häufigen Operationen durchführen möchten:
Sie möchten Verzeichnisänderungen auf Ihr aktuelles Arbeitsverzeichnis abgleichen.
Sie möchten die Änderungen in einer bestimmten Datei mit einer Datei gleichen Namens in Ihrem aktuellen Arbeitsverzeichnis zusammenführen.
Falls Sie ein Verzeichnis zusammenführen und keinen Zielpfad angegeben haben, nimmt svn merge den ersten Fall an und versucht, die Änderungen auf Ihr aktuelles Arbeitsverzeichnis anzuwenden. Falls Sie eine Datei zusammenführen und diese Datei (oder eine gleichnamige Datei) in Ihrem aktuellen Arbeitsverzeichnis existiert, nimmt svn merge den zweiten Fall an und wendet die Änderungen auf eine lokale Datei gleichen Namens an.
Sie haben nun einige Beispiele zum Befehl svn merge gesehen und werden bald einige mehr sehen. Falls Sie verwirrt darüber sind, wie das Zusammenführen genau funktioniert, sind Sie nicht alleine. Viele Anwender (besonders diejenigen, für die Versionskontrolle etwas Neues ist) sind anfangs verwirrt darüber, wie die korrekte Syntax des Befehls lautet und wann das Feature verwendet werden soll. Aber, keine Angst, dieser Befehl ist tatsächlich viel einfacher als Sie denken! Es gibt eine einfache Technik, die verstehen hilft, wie sich svn merge genau verhält.
Die Hauptquelle der Verwirrung ist der Name des Befehls. Der Begriff „merge“ (Zusammenführung, Mischung) deutet irgendwie an, dass Zweige miteinander verschmolzen werden, oder dass irgendeine geheimnisvolle Mischung der Daten erfolgt. Das ist nicht der Fall. Ein besserer Name für den Befehl wäre vielleicht svn ermittele-die-Unterschiede-und-wende-sie-an gewesen, da das alles ist, was passiert: Die Bäume im Repository werden verglichen und die Unterschiede in eine Arbeitskopie eingearbeitet.
Falls Sie svn merge benutzen, um einfache Kopien von Änderungen zwischen Zweigen vorzunehmen, wird es üblicherweise automatisch das Richtige machen. Beispielsweise wird ein Befehl wie der folgende:
$ svn merge http://svn.example.com/repos/calc/some-branch
versuchen, alle Änderungen, die auf
some-branch
gemacht worden sind, in Ihr
aktuelles Arbeitsverzeichnis zu kopieren, welches vermutlich
eine Arbeitskopie ist, die mit dem Zweig irgendeine
historische Verbindung teilt. Der Befehl ist klug genug, nur
die Änderungen zu kopieren, die Ihre Arbeitskopie noch nicht
hat. Wenn Sie diesen Befehl einmal die Woche wiederholen, wird
er nur die „neuesten“ Änderungen vom Zweig
kopieren, die seit Ihrem letzten Zusammenführen
stattfanden.
Wenn Sie den Befehl svn merge in seiner ganzen Pracht wählen, indem Sie ihm bestimmte Revisionsintervalle zum kopieren übergeben, benötigt der Befehl drei Hauptargumente:
Einen Anfangsbaum im Repository (häufig linke Seite des Vergleichs genannt)
Einen Endbaum im Repository (häufig rechte Seite des Vergleichs genannt)
Eine Arbeitskopie, die die Unterschiede als lokale Änderungen aufnimmt (häufig Ziel der Zusammenführung genannt)
Sobald diese drei Argumente angegeben sind, werden die zwei Bäume miteinander verglichen und die Unterschiede als lokale Änderungen auf die Ziel-Arbeitskopie angewendet. Wenn der Befehl fertig ist, sieht das Ergebnis so aus, als hätten Sie die Dateien manuell editiert oder verschiedene svn add- oder svn delete-Befehle ausgeführt. Wenn Ihnen das Ergebnis gefällt, können Sie es übergeben. Falls nicht, können Sie einfach mit svn revert alle Änderungen rückgängig machen.
Die Syntax von svn merge erlaubt Ihnen, die drei notwendigen Argumente auf eine recht flexible Weise anzugeben. Hier sind einige Beispiele:
$ svn merge http://svn.example.com/repos/branch1@150 \ http://svn.example.com/repos/branch2@212 \ my-working-copy $ svn merge -r 100:200 http://svn.example.com/repos/trunk my-working-copy $ svn merge -r 100:200 http://svn.example.com/repos/trunk
Die erste Syntax führt alle drei Argumente explizit auf, indem jeder Baum mit dem Format URL@REV bezeichnet und die Ziel-Arbeitskopie angegeben wird. Die zweite Syntax kann als Kurzform verwendet werden, wenn Sie zwei unterschiedliche Revisionen desselben URL vergleichen. Die letzte Syntax zeigt, dass das Arbeitskopie-Argument optional ist; entfällt es, wird das aktuelle Verzeichnis genommen.
Obwohl das erste Beispiel die „vollständige“
Syntax von svn merge zeigt, muss sie sehr
sorgfältig verwendet werden; es können hierbei
Zusammenführungen entstehen, bei denen keinerlei
svn:mergeinfo
Metadaten aufgezeichnet
werden. Der nächste Abschnitt geht näher darauf ein.
Subversion versucht immer wenn es kann, Metadaten über das
Zusammenführen zu erzeugen, um spätere Aufrufe von
svn merge schlauer zu machen. Trotzdem
gibt es Situationen, in denen
svn:mergeinfo
-Daten nicht erzeugt oder
geändert werden. Denken Sie daran, vor diesen Szenarien auf
der Hut zu sein:
Falls Sie svn merge dazu auffordern, zwei URLs zu vergleichen, die nicht miteinander in Beziehung stehen, wird trotzdem ein Patch erzeugt und auf die Arbeitskopie angewendet, allerdings werden keine Metadaten erzeugt. Es gibt keine gemeinsame Geschichte der zwei Quellen, und spätere „schlaue“ Zusammenführungen hängen von dieser gemeinsamen Geschichte ab.
Obwohl es möglich ist, einen Befehl wie svn
merge -r 100:200
auszuführen, wird auch dieser resultierende Patch keine
historischen Metadaten über die Zusammenführung haben.
Zum gegenwärtigen Zeitpunkt hat Subversion keine
Möglichkeit, unterschiedliche Repository-URLs innerhalb
des http://svn.foreignproject.com/repos/trunk
svn:mergeinfo
-Propertys zu
repräsentieren.
--ignore-ancestry
Wenn diese Option an svn merge übergeben wird, veranlasst das die Zusammenführungs-Logik, ohne nachzudenken Unterschiede auf dieselbe Art zu erzeugen, wie es svn diff macht, und ignoriert dabei irgendwelche historischen Verbindungen. Wir werden das später in diesem Kapitel in „Die Abstammung berücksichtigen oder ignorieren“ erörtern.
Weiter oben in diesem Kapitel
(„Änderungen rückgängig machen“)
haben wir darüber gesprochen, wie man mit svn
merge einen „Rückwärts-Patch“
verwendet, um Änderungen rückgängig zu machen. Wenn
diese Technik dazu verwendet wird, um eine Änderung in
der Geschichte eines Objektes zurückzunehmen (z.B. r5
an den Stamm übergeben, und dann sofort r5 mit
svn merge . -c -5
rückgängig
machen), hat dies keine Auswirkungen auf die
aufgezeichneten Metadaten.
[23]
Wie der Befehl svn update wendet auch svn merge Änderungen auf Ihre Arbeitskopie an. Und deshalb kann er auch Konflikte erzeugen. Die von svn merge hervorgerufenen Konflikte sind jedoch manchmal anders geartet, und dieser Abschnitt erklärt diese Unterschiede.
Zunächst gehen wir davon aus, dass Ihre Arbeitskopie keine lokalen Änderungen enthält. Wenn Sie mit svn update auf eine bestimmte Revision aktualisieren, werden die vom Server gesendeten Änderungen immer „sauber“ auf Ihre Arbeitskopie angewendet. Der Server erzeugt das Delta, indem er zwei Bäume vergleicht: eine virtuelle Momentaufnahme Ihrer Arbeitskopie und der Revisionsbaum, an dem Sie interessiert sind. Da die linke Seite des Vergleichs völlig gleich zu dem ist, was Sie bereits haben, wird das Delta garantiert Ihre Arbeitskopie korrekt in den rechten Baum überführen.
svn merge jedoch kann das nicht gewährleisten und kann viel chaotischer sein: Der fortgeschrittene Benutzer kann den Server auffordern, irgendwelche zwei Bäume miteinander zu vergleichen, sogar solche, die nicht mit der Arbeitskopie in Beziehung stehen! Das bedeutet, dass ein hohes Potenzial für menschliche Fehler besteht. Benutzer werden manchmal die falschen zwei Bäume miteinander vergleichen, so dass ein Delta erzeugt wird, das sich nicht sauber anwenden lässt. svn merge wird sein Bestes geben, um soviel wie möglich vom Delta anzuwenden, doch bei einigen Teilen kann das unmöglich sein. So wie der Unix-Befehl patch sich manchmal über „failed hunks“ beschwert, wird sich svn merge ähnlich über „skipped targets“ beschweren:
$ svn merge -r 1288:1351 http://svn.example.com/repos/branch U foo.c U bar.c Fehlendes Ziel: »baz.c« übersprungen. U glub.c U sputter.h Konflikt in »glorb.h« entdeckt. Auswahl: (p) zurückstellen, (df) voller Diff, (e) editieren, (h) Hilfe für weitere Optionen:
Im vorangegangenen Beispiel kann es der Fall gewesen sein,
dass baz.c
in beiden Momentaufnahmen des
Zweiges vorkommt, die verglichen werden, und das resultierende
Delta den Inhalt der Datei verändern will, die in der
Arbeitskopie aber nicht vorhanden ist. Wie auch immer, die
„skipped“-Nachricht bedeutet, dass der Benutzer
höchstwahrscheinlich die falschen Bäume miteinander
vergleicht; es ist das klassische Zeichen für einen
Anwenderfehler. Falls dies passiert, ist es einfach, alle
durch das Zusammenführen hervorgerufenen Änderungen rekursiv
rückgängig zu machen (svn revert .
--recursive
), alle unversionierten Dateien oder
Verzeichnisse zu löschen, die nach dem Rückgängigmachen
zurückgeblieben sind, und svn merge noch
einmal mit unterschiedlichen Argumenten aufzurufen.
Beachten Sie auch, dass das vorangegangene Beispiel einen
Konflikt in glorb.h
anzeigt. Wir
bemerkten bereits, dass die Arbeitskopie keine lokalen
Änderungen besitzt: Wie kann da ein Konflikt entstehen? Noch
einmal: Weil der Benutzer svn merge dazu
verwenden kann, ein altes Delta zu definieren und auf die
Arbeitskopie anzuwenden, kann es sein, dass dieses alte Delta
textuelle Änderungen enthält, die nicht sauber in eine
Arbeitsdatei eingearbeitet werden können, selbst dann nicht,
wenn die Datei keine lokalen Änderungen vorzuweisen
hat.
Ein weiterer kleiner Unterschied zwischen svn
update und svn merge sind die
Namen der erzeugten Textdateien, falls ein Konflikt entsteht.
In „Konflikte auflösen (Änderungen anderer einarbeiten)“ sahen wir, dass
bei einer Aktualisierung die Dateien namens
filename.mine
,
filename.rOLDREV
und
filename.rNEWREV
erzeugt werden. Falls
svn merge einen Konflikt hervorruft,
erstellt es jedoch drei Dateien namens
filename.working
,
filename.left
und
filename.right
. In diesem Fall
beschreiben die Begriffe „left“ (links) und
„right“ (rechts) von welcher Seite des Vergleichs
zwischen den beiden Bäumen die Datei hergeleitet wurde. Auf
alle Fälle werden Ihnen diese unterschiedlichen Namen dabei
helfen, zwischen Konflikten zu unterscheiden, die durch eine
Aktualisierung entstanden, und solchen die durch eine
Zusammenführung hervorgerufen wurden .
Manchmal gibt es eine bestimmte Änderungsmenge, die Sie
nicht automatisch zusammengeführt haben wollen. Beispielsweise
ist vielleicht die Vorgehensweise Ihres Teams dergestalt, dass
Neuentwicklungen auf /trunk
gemacht
werden, aber konservativer, wenn es darum geht, Änderungen auf
einen stabilen Zweig zurückzuportieren, den sie zur
Veröffentlichung benutzen. Auf der einen Seite können Sie
die Rosinen in Form von einzelnen Änderungsmengen manuell aus
dem Stamm herauspicken und in den Zweig einpflegen – nur
die Änderungen, die stabil genug sind, um die Qualitätsprüfung
zu bestehen. Vielleicht ist es ja auch nicht ganz so streng,
und Sie möchten normalerweise, dass svn
merge die meisten Änderungen vom Stamm automatisch
mit dem Zweig zusammenführt. In diesem Fall könnten Sie ein
Verfahren gebrauchen, dass es Ihnen erlaubt, einige bestimmte
Änderungen auszulassen, d.h. zu vermeiden, dass sie
automatisch in den Zweig eingebracht werden.
Die einzige Möglichkeit, mit Subversion 1.5 eine
Änderungsmenge zu blockieren, besteht darin, dem System
vorzugaukeln, dass die Änderung bereits
eingearbeitet wurde. Dazu können Sie den Befehl mit der Option
--record-only
aufrufen:
$ cd my-calc-branch $ svn propget svn:mergeinfo . /trunk:1680-3305 # In den Metadaten r3328 als bereits zusammengeführt vermerken. $ svn merge -c 3328 --record-only http://svn.example.com/repos/calc/trunk $ svn status M . $ svn propget svn:mergeinfo . /trunk:1680-3305,3328 $ svn commit -m "Das Zusammenführen von r3328 mit dem Zweig verhindern." …
Diese Technik funktioniert zwar, sie ist allerdings auch ein wenig gefährlich. Das Hauptproblem ist, dass wir nicht klar unterscheiden zwischen „ich habe diese Änderung bereits“ und „ich habe diese Änderung nicht“. Wir belügen das System gewissermaßen, indem wir es glauben lassen, dass die Änderung schon eingearbeitet sei. Das schiebt die Verantwortung, sich daran zu erinnern, dass die Änderung tatsächlich gar nicht übernommen wurde sondern nicht gewünscht war, auf Sie – den Benutzer. Es gibt keine Möglichkeit, Subversion nach einer Liste „blockierter Änderungen“ zu fragen. Wenn Sie sie verfolgen möchten (so dass Sie eines Tages die Blockierung aufheben können) müssen Sie sie irgendwo in eine Textdatei schreiben oder in einem erfundenen Property festhalten. Leider ist das in Subversion 1.5 die einzige Möglichkeit mit blockierten Revisionen umzugehen; ein besseres Interface dafür ist für künftige Versionen geplant.
Ein Hauptmerkmal jedes Versionskontrollsystems ist es, darüber Buch zu führen, wer was wann geändert hat. Die Befehle svn log und svn blame sind die geeigneten Werkzeuge hierfür: Wenn sie auf individuelle Dateien angewendet werden, zeigen sie nicht nur die Geschichte der Änderungsmengen, die in diese Datei hineinflossen, sondern auch, welcher Benutzer wann welche Zeile im Quelltext geschrieben hat.
Wenn jedoch Änderungen über Zweige hinweg dupliziert werden, wird es schnell kompliziert. Wenn Sie z.B. svn log nach der Geschichte Ihres Zweigs fragen, wird es Ihnen exakt jede Revision anzeigen, die je in den Zweig hineingeflossen ist:
$ cd my-calc-branch $ svn log -q ------------------------------------------------------------------------ r390 | user | 2002-11-22 11:01:57 -0600 (Fr, 22. Nov 2002) | 1 line ------------------------------------------------------------------------ r388 | user | 2002-11-21 05:20:00 -0600 (Do, 21. Nov 2002) | 2 lines ------------------------------------------------------------------------ r381 | user | 2002-11-20 15:07:06 -0600 (Mi, 20. Nov 2002) | 2 lines ------------------------------------------------------------------------ r359 | user | 2002-11-19 19:19:20 -0600 (Di, 19. Nov 2002) | 2 lines ------------------------------------------------------------------------ r357 | user | 2002-11-15 14:29:52 -0600 (Fr, 15. Nov 2002) | 2 lines ------------------------------------------------------------------------ r343 | user | 2002-11-07 13:50:10 -0600 (Do, 07. Nov 2002) | 2 lines ------------------------------------------------------------------------ r341 | user | 2002-11-03 07:17:16 -0600 (So, 03. Nov 2002) | 2 lines ------------------------------------------------------------------------ r303 | sally | 2002-10-29 21:14:35 -0600 (Di, 29. Oct 2002) | 2 lines ------------------------------------------------------------------------ r98 | sally | 2002-02-22 15:35:29 -0600 (Fr, 22. Feb 2002) | 2 lines ------------------------------------------------------------------------
Aber ist das wirklich eine genaue Wiedergabe aller Änderungen, die auf dem Zweig stattgefunden haben? Was hier ausgelassen wird, ist, dass die Revisionen 390, 381 und 357 tatsächlich Ergebnisse des Zusammenführens von Änderungen aus dem Stamm waren. Wenn Sie sich eins dieser Protokolle im Detail anschauen, können Sie die verschiedenen Änderungsmengen vom Stamm, die die Änderungen auf dem Zweig ausmachen, nirgendwo sehen:
$ svn log -v -r 390 ------------------------------------------------------------------------ r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line Geänderte Pfade: M /branches/my-calc-branch/button.c M /branches/my-calc-branch/README Letzte Zusammenführung der Änderungen von trunk changes in my-calc-branch.
Wir wissen, dass diese Zusammenführung in den Zweig nichts
anderes war als eine Zusammenführung von Änderungen vom Stamm.
Wie können wir zusätzlich diese Änderungen sehen? Die Antwort
lautet, die Option --use-merge-history
(-g
) zu verwenden. Diese Option expandiert
diejenigen „Teil“-Änderungen, aus denen die
Zusammenführung bestand.
$ svn log -v -r 390 -g ------------------------------------------------------------------------ r390 | user | 2002-11-22 11:01:57 -0600 (Fri, 22 Nov 2002) | 1 line Geänderte Pfade: M /branches/my-calc-branch/button.c M /branches/my-calc-branch/README Letzte Zusammenführung der Änderungen von trunk changes in my-calc-branch. ------------------------------------------------------------------------ r383 | sally | 2002-11-21 03:19:00 -0600 (Thu, 21 Nov 2002) | 2 lines Geänderte Pfade: M /branches/my-calc-branch/button.c Zusammengeführt mittels: r390 Inverse Grafik auf Knopf behoben. ------------------------------------------------------------------------ r382 | sally | 2002-11-20 16:57:06 -0600 (Wed, 20 Nov 2002) | 2 lines Geänderte Pfade: M /branches/my-calc-branch/README Zusammengeführt mittels: r390 Meine letzte Änderung in README dokumentiert.
Dadurch, dass wir die Protokoll-Operation aufgefordert haben, die Geschichte der Zusammenführungen zu verwenden, sehen wir nicht nur die Revision, die wir abgefragt haben (r390), sondern auch die zwei Revisionen, die hier mitkamen – ein paar Änderungen, die Sally auf dem Stamm gemacht hat. Das ist ein wesentlich vollständigeres Bild der Geschichte!
Auch der svn blame-Befehl versteht die
Option --use-merge-history
(-g
). Falls diese Option vergessen wird,
könnte jemand, der sich die zeilenweisen Anmerkungen von
button.c
ansieht, fälschlicherweise davon
ausgehen, dass Sie für die Zeilen verantwortlich sind, die
einen bestimmten Fehler beseitigt haben:
$ svn blame button.c … 390 user retval = inverse_func(button, path); 390 user return retval; 390 user } …
Obwohl es zutrifft, dass Sie diese drei Zeilen in Revision 390 übergeben haben, sind zwei davon tatsächlich von Sally in Revision 383 geschrieben worden:
$ svn blame button.c -g … G 383 sally retval = inverse_func(button, path); G 383 sally return retval; 390 user } …
Nun wissen wir, wer wirklich für die zwei Zeilen Quelltext verantwortlich ist!
Wenn Sie sich mit einem Subversion-Entwickler unterhalten, wird wahrscheinlich auch der Begriff Abstammung erwähnt. Dieses Wort wird verwendet, um die Beziehung zwischen zwei Objekten im Repository zu beschreiben: Wenn sie in Beziehung zueinander stehen, heißt es, dass ein Objekt vom anderen abstammt.
Nehmen wir an, Sie übergeben Revision 100, die eine
Änderung an der Datei foo.c
beinhaltet.
Dann ist foo.c@99
ein
„Vorfahre“ von foo.c@100
.
Wenn Sie dagegen in Revision 101 die Löschung von
foo.c
übergeben und in Revision 102 eine
neue Datei mit demselben Namen hinzufügen, hat es zwar den
Anschein, dass foo.c@99
und
foo.c@102
in Beziehung zueinander stehen
(sie haben denselben Pfad), es handelt sich allerdings um
völlig unterschiedliche Objekte im Repository. Sie haben weder
eine gemeinsame Geschichte noch
„Abstammung“.
Wir erwähnen das, um auf einen wichtigen Unterschied
zwischen den Befehlen svn diff und
svn merge hinzuweisen. Der erstere Befehl
ignoriert die Abstammung, wohingegen letzterer diese beachtet.
Wenn Sie beispielsweise mit svn diff die
Revisionen 99 und 102 von foo.c
vergleichen, werden Sie zeilenbasierte Unterschiede sehen; der
Befehl diff vergleicht blind zwei Pfade.
Wenn Sie aber dieselben Objekte mit svn
merge vergleichen, wird es feststellen, dass sie
nicht in Beziehung stehen und versuchen, die alte Datei zu
löschen und dann die neue hinzuzufügen; die Ausgabe wird eine
Löschung gefolgt von einer Hinzufügung anzeigen:
D foo.c A foo.c
Die meisten Zusammenführungen vergleichen Bäume, die von
der Abstammung her miteinander in Beziehung stehen, deshalb
verhält sich svn merge auf diese Weise.
Gelegentlich möchten Sie jedoch mit dem
merge-Befehl zwei Bäume vergleichen, die
nicht miteinander in Beziehung stehen. Es kann z.B. sein, dass
Sie zwei Quelltext-Bäume importiert haben, die unterschiedliche
Lieferantenstände eines Software-Projektes repräsentieren
(siehe „Lieferanten-Zweige“). Falls Sie
svn merge dazu aufforderten, die beiden Bäume
miteinander zu vergleichen, würden Sie sehen, dass der
vollständige erste Baum gelöscht und anschließend der
vollständige zweite Baum hinzugefügt würde! In diesen
Situationen möchten Sie, dass svn merge
lediglich einen pfadbasierten Vergleich vornimmt und
Beziehungen zwischen Dateien und Verzeichnissen außer Acht
lässt. Fügen Sie die Option --ignore-ancestry
dem merge-Befehl hinzu, und er wird sich
verhalten wie svn diff. (Auf der anderen
Seite wird die Option --notice-ancestry
den
Befehl svn diff dazu veranlassen, sich wie
svn merge zu verhalten.
Es ist ein verbreiteter Wunsch, Software zu refaktorieren, besonders in Java-basierten Software-Projekten. Dateien und Verzeichnisse werden hin und her geschoben und umbenannt, was häufig zu erheblichen Beeinträchtigungen für alle Projektmitarbeiter führt. Das hört sich an, als sei das der klassische Fall, um nach einem Zweig zu greifen, nicht wahr? Sie erzeugen einfach einen Zweig, schieben das Zeug herum und führen anschließend den Zweig mit dem Stamm zusammen.
Leider funktioniert dieses Szenario im Augenblick noch nicht so richtig und gilt als einer der Schwachpunkte von Subversion. Das Problem ist, das der Subversion-Befehl svn update nicht so stabil ist, wie er sein sollte, besonders wenn es um Kopier- und Verschiebeoperationen geht.
Wenn Sie svn copy zum Duplizieren einer Datei verwenden, merkt sich das Repository, woher die neue Datei kam, versäumt aber, diese Information an den Client zu senden, der svn update oder svn merge ausführt. Statt dem Client mitzuteilen: „Kopiere die Datei, die du bereits hast an diesen neuen Ort“, sendet es eine völlig neue Datei. Das kann zu Problemen führen, besonders, weil dasselbe mit umbenannten Dateien passiert. Eine weniger bekannte Tatsache über Subversion ist, dass es keine „echten Umbenennungen“ hat – der Befehl svn move ist weiter nichts als eine Verbindung von svn copy und svn delete.
Nehmen wir beispielsweise an, dass Sie während Ihrer
Arbeit auf Ihrem privaten Zweig integer.c
in whole.c
umbenennen. Tatsächlich haben
Sie eine neue Datei auf Ihrem Zweig erzeugt, die eine Kopie
der ursprünglichen Datei ist, und letztere gelöscht.
Zwischenzeitlich hat Sally einige Verbesserungen an
integer.c
in trunk
übergeben. Nun entscheiden Sie sich, Ihren Zweig mit dem Stamm
zusammenzuführen:
$ cd calc/trunk $ svn merge --reintegrate http://svn.example.com/repos/calc/branches/my-calc-branch -- Zusammenführen der Unterschiede zwischen Projektarchiv-URLs in ».«: D integer.c A whole.c U .
Auf den ersten Blick sieht es gar nicht schlecht aus,
jedoch ist es nicht das, was Sie und Sally erwartet hätten.
Die Zusammenführung hat die letzte Version der Datei
integer.c
gelöscht (diejenige, die Sallys
Änderungen beinhaltet) und blindlings Ihre neue Datei
whole.c
hinzugefügt – die ein
Duplikat der älteren Version von
integer.c
ist. Das Endergebnis ist, dass
durch die Zusammenführung Ihrer „Umbenennung“ auf
dem Zweig mit dem Stamm Sallys jüngste Änderungen aus der
letzten Revision entfernt wurden.
Es ist kein echter Datenverlust. Sallys Änderungen befinden sich noch immer in der Geschichte des Repositorys, allerdings mag es nicht sofort ersichtlich sein, dass es passiert ist. Die Lehre, die es aus dieser Geschichte zu ziehen gilt, lautet, dass Sie sehr vorsichtig mit dem Zusammenführen von Kopien und Umbenennungen zwischen Zweigen sein sollten, solange sich Subversion an dieser Stelle nicht verbessert hat.
Wenn Sie gerade Ihren Server auf Subversion 1.5 oder
größer umgestellt haben, besteht ein signifikantes Risiko,
dass Subversion-Clients einer kleineren Version als 1.5 Ihre
automatische Zusammenführungs-Verfolgung durcheinander bringen
können. Warum? Wenn ein älterer Subversion-Client svn
merge ausführt, modifiziert er nicht den Wert des
Propertys svn:mergeinfo
. Obwohl die
anschließende Übergabe das Ergebnis einer Zusammenführung ist,
wird dem Repository nichts über die duplizierten Änderungen
mitgeteilt – diese Information ist verloren. Wenn später
Clients, die Zusammenführungsinformationen auswerten,
automatische Zusammenführungen versuchen, werden Sie
wahrscheinlich in alle möglichen Konflikte laufen, die durch
wiederholte Zusammenführungen hervorgerufen wurden.
Wenn Sie und Ihr Team auf die Zusammenführungs-Verfolgung
von Subversion angewiesen sind, sollten Sie Ihr Repository
dergestalt konfigurieren, dass ältere Clients daran gehindert
werden, Änderungen zu übergeben. Die einfache Methode hierfür
ist es, den „Fähigkeiten“-Parameter im
start-commit
Hook-Skript zu untersuchen.
Wenn der Client meldet, dass er mit
mergeinfo
umgehen kann, kann das Skript den
Beginn der Übergabe erlauben. Wenn der Client diese Fähigkeit
nicht meldet, wird die Übergabe abgelehnt. Wir werden mehr
über Hook-Skripte im nächsten Kapitel erfahren; siehe „Erstellen von Repository-Hooks“ und start-commit für
Details.
Unter dem Strich bedeutet das, dass die Fähigkeit von
Subversion zur Zusammenführungs-Verfolgung eine höchst
komplexe interne Implementierung besitzt und das Property
svn:mergeinfo
das einzige Fenster zu diesem
Räderwerk ist. Da diese Fähigkeit relativ neu ist, kann eine
Anzahl von Randfällen und mögliche unerwartete
Verhaltensweisen auftauchen.
So kann zum Beispiel Mergeinfo manchmal durch einen einfachen svn copy- oder svn move-Befehl erzeugt werden. Manchmal wird Mergeinfo an Dateien auftauchen, von denen Sie nicht erwartet hätten, dass sie durch die Operation berührt worden wären. Manchmal wird Mergeinfo überhaupt nicht erzeugt, obwohl Sie es erwartet hätten. Darüberhinaus umgibt die Verwaltung der Mergeinfo-Metadaten eine ganze Menge von Systematiken und Verhalten, wie „explizite“ gegenüber „implizite“ Mergeinfo, „operative“ gegenüber „inoperativen“ Revisionen, besondere Mechanismen von Mergeinfo-„Auslassung“ und sogar „Vererbung“ von Eltern- zu Kindverzeichnissen.
Wir haben uns entschieden, diese detaillierten Themen aus einer Reihe von Gründen nicht in diesem Buch zu behandeln. Erstens ist der Detaillierungsgrad für einen normalen Benutzer absolut erdrückend. Zweitens glauben wir, dass das Verständnis diese Konzepte für einen typischen Benutzer nicht unbedingt erforderlich sein sollte während Subversion sich verbessert; letztendlich werden sie als nervige Implementierugsdetails in den Hintergrund treten. Wenn Sie, nachdem dies gesagt ist, diese Dinge mögen, können Sie einen fantastischen Überblick in einer Arbeit nachlesen, die auf der Webseite von CollabNet veröffentlicht ist:http://www.collab.net/community/subversion/articles/merge-info.html.
Fürs Erste empfiehlt CollabNet, sich an die folgenden bewährten Praktiken zu halten, wenn Sie Fehler und merkwürdiges Verhalten bei automatischen Zusammenführungen vermeiden wollen:
Wenden Sie für kurzlebige Arbeitszweige das Verfahren an, das in „Grundlegendes Zusammenführen“ beschrieben wird.
Machen Sie Zusammenführungen langlebiger Release-Zweige (wie in „Verbreitete Verzweigungsmuster“ beschrieben) nur im Wurzelverzeichnis des Zweigs und nicht in Unterverzeichnissen.
Machen Sie Zusammenführungen in Arbeitsverzeichnisse niemals mit einer Mischung aus Arbeitsrevisionsnummern oder „umgeschalteten“ Unterverzeichnissen (wie als Nächstes in „Zweige durchlaufen“ beschrieben). Das Ziel einer Zusammenführung sollte eine Arbeitskopie sein, die einen einzigen Ort zu einem einzelnen Zeitpunkt im Repository repräsentiert.
Editieren Sie niemals direkt das Property
svn:mergeinfo
; verwenden Sie
svn merge mit der Option
--record-only
, um eine gewünschte
Änderung an den Metadaten zu bewirken (wie in „Änderungen blockieren“
gezeigt).
Stellen Sie jederzeit sicher, dass Sie vollständigen Lesezugriff auf die Quellen für die Zusammenführung haben und dass Ihre Ziel-Arbeitskopie keine dünn besetzten Verzeichnisse besitzt.
Der Befehl svn switch überführt eine
bestehende Arbeitskopie, so dass sie einen anderen Zweig
repräsentiert. Obwohl dieser Befehl strenggenommen für die
Arbeit mit Zweigen nicht notwendig ist, stellt er eine nette
Abkürzung dar. In unserem früheren Beispiel haben Sie nach dem
Anlegen Ihres eigenen privaten Zweigs eine frische Arbeitskopie
des neuen Repository-Verzeichnisses ausgecheckt. Stattdessen
können Sie Subversion einfach mitteilen, dass es Ihre
Arbeitskopie von /calc/trunk
ändern soll,
um den neuen Ort des Zweigs widerzuspiegeln:
$ cd calc $ svn info | grep URL URL: http://svn.example.com/repos/calc/trunk $ svn switch http://svn.example.com/repos/calc/branches/my-calc-branch U integer.c U button.c U Makefile Aktualisiert zu Revision 341. $ svn info | grep URL URL: http://svn.example.com/repos/calc/branches/my-calc-branch
„Das Umschalten“ einer Arbeitskopie ohne lokale Änderungen auf einen anderen Zweig hat zur Folge, dass die Arbeitskopie genau so aussieht, als sei das Verzeichnis frisch ausgecheckt worden. Es ist gewöhnlicherweise effizienter, diesen Befehl zu verwenden, da sich Zweige oftmals nur in kleinen Teilen unterscheiden. Der Server sendet nur die minimale Menge von Änderungen, die notwendig sind, damit Ihre Arbeitskopie den Inhalt des Zweig-Verzeichnisses wiedergibt.
Der Befehl svn switch versteht auch die
Option --revision
(-r
), so
dass Sie nicht immer gezwungen sind, Ihre Arbeitskopie auf den
HEAD
des Zweigs zu setzen.
Natürlich sind die meisten Projekte komplizierter als unser
calc
-Beispiel und enthalten mehrere
Unterverzeichnisse. Subversion-Benutzer wenden bei der
Verwendung von Zweigen häufig einen bestimmten Algorithmus
an:
Kopiere den vollständigen „Stamm“ des Projektes in ein neues Zweig-Verzeichnis.
Schalte nur einen Teil der Arbeitskopie vom Stamm auf den Zweig um.
In anderen Worten: Wenn ein Benutzer weiß, dass die Arbeit auf dem Zweig nur in einem bestimmten Unterverzeichnis stattfinden muss, verwendet er svn switch lediglich, um dieses Unterverzeichnis auf den Zweig zu bringen. (Manchmal schalten Benutzer sogar nur eine einzelne Datei auf den Zweig um!) Auf diese Art kann ein Benutzer für einen großen Teil der Arbeitskopie weiterhin normale Aktualisierungen auf dem „Stamm“ erhalten, wohingegen die umgeschalteten Teile unberührt bleiben (es sei denn, jemand übergibt etwas an den Zweig). Diese Möglichkeit fügt dem Konzept einer „gemischten Arbeitskopie“ eine völlig neue Dimension hinzu – Arbeitskopien können nicht nur eine Mischung unterschiedlicher Revisionen enthalten, sondern auch eine Mischung unterschiedlicher Repository-Orte.
Falls Ihre Arbeitskopie eine Anzahl umgeschalteter Unterverzeichnisse aus unterschiedlichen Repository-Orten enthält, funktioniert sie immer noch normal. Wenn Sie aktualisieren, erhalten Sie entsprechende Patches für jeden Unterbaum. Wenn Sie übergeben, werden Ihre lokalen Änderungen nach wie vor als eine einzelne atomare Änderung auf das Repository angewendet.
Während es normal ist, das eine Arbeitskopie eine Mischung unterschiedlicher Repository-Orte repräsentiert, ist darauf zu achten, dass all diese Orte sich innerhalb desselben Repositorys befinden. Subversion-Repositorys können noch nicht miteinander kommunizieren; diese Möglichkeit ist für die Zukunft geplant. [24]
Da svn switch eigentlich eine Variante von svn update ist, teilt es dasselbe Verhalten; irgendwelche lokalen Änderungen Ihrer Arbeitskopie bleiben erhalten, wenn neue Daten aus dem Repository ankommen.
Haben Sie sich jemals dabei ertappt, dass Sie (in Ihrer
/trunk
-Arbeitskopie) komplexe
Änderungen gemacht haben und plötzlich feststellen:
„Verdammt, diese Änderungen sollten auf einen eigenen
Zweig!“ Eine gute Technik, um das zu bewerkstelligen,
lässt sich in zwei Schritten zusammenfassen:
$ svn copy http://svn.example.com/repos/calc/trunk \ http://svn.example.com/repos/calc/branches/newbranch \ -m "Zweig 'newbranch' angelegt." Revision 353 übertragen. $ svn switch http://svn.example.com/repos/calc/branches/newbranch Revision 353.
Der Befehl svn switch bewahrt wie svn update Ihre lokalen Änderungen. An dieser Stelle spiegelt Ihre Arbeitskopie den neu erzeugten Zweig wieder, und Ihr nächster Aufruf von svn commit wird Ihre Änderungen dorthin senden.
Ein weiterer verbreiteter Begriff in der Versionskontrolle ist ein Tag. Ein Tag ist lediglich eine „Momentaufnahme“ eines Projekts. In Subversion scheint dieses Konzept bereits überall vorhanden zu sein. Jede Revision im Repository ist genau das – eine Momentaufnahme des Dateisystems nach einer Übergabe.
Allerdings möchten Menschen häufig sprechendere Namen für
Tags vergeben, wie etwa release-1.0
. Und sie
möchten Momentaufnahmen kleinerer Unterverzeichnisse des
Dateisystems erstellen. Schließlich ist es nicht gerade einfach,
sich daran zu erinnern, dass Release 1.0 einer Software ein
bestimmtes Unterverzeichnis der Revision 4822 ist.
Wieder einmal hilft Ihnen svn copy bei
der Arbeit. Wenn Sie eine Momentaufnahme von
/calc/trunk
machen wollen, genau so, wie
es in der Revision HEAD
aussieht, machen
Sie davon eine Kopie:
$ svn copy http://svn.example.com/repos/calc/trunk \ http://svn.example.com/repos/calc/tags/release-1.0 \ -m "Ein Tag für die Ausgabe 1.0 des 'calc' Projektes anlegen." Revision 902 übertragen.
Dieses Beispiel geht davon aus, dass ein Verzeichnis
/calc/tags
bereits besteht. (Falls nicht,
können Sie es mit svn mkdir erstellen.)
Nach Abschluss der Kopie ist das neue Verzeichnis
release-1.0
für immer eine Momentaufnahme
des Verzeichnisses /trunk
in der Revision
HEAD
zum Zeitpunkt, an dem Sie die Kopie
erstellt haben. Natürlich können Sie auch angeben, welche
Revision Sie genau kopieren möchten, für den Fall, dass jemand
anderes Änderungen an das Projekt übergeben haben könnte,
während Sie nicht hingeschaut haben. Wenn Sie also wissen,
dass Revision 901 von /calc/trunk
genau
die Momentaufnahme ist, die Sie möchten, können Sie sie mit
der Option -r 901
an den Befehl svn
copy übergeben.
Moment mal: ist die Erstellung eines Tags nicht dasselbe Vorgehen wie bei der Erstellung eines Zweigs? Ja, es ist es tatsächlich. In Subversion gibt es keinen Unterschied zwischen einem Tag und einem Zweig. Beides sind gewöhnliche Verzeichnisse, die durch Kopieren erzeugt werden. Genauso wie bei Zweigen, ist der einzige Grund warum ein kopiertes Verzeichnis ein „Tag“ ist, weil Menschen sich entschieden haben, es so zu betrachten: Solange niemand etwas an das Verzeichnis übergibt, bleibt es für immer eine Momentaufnahme. Wenn jemand damit beginnt, etwas dorthin zu übergeben, wird es ein Zweig.
Wenn Sie ein Repository verwalten, gibt es zwei Ansätze für den Umgang mit Tags. Der erste Ansatz ist „Hände weg“: Als Vereinbarung im Projekt entscheiden Sie, wohin Sie Ihre Tags kopieren möchten; stellen Sie sicher, dass alle Benutzer wissen, wie sie ihre zu kopierenden Verzeichnisse behandeln sollen, d.h., stellen Sie sicher, dass sie nichts dorthin übergeben. Der zweite Ansatz ist etwas paranoider: Sie können eins der Zugriffskontrollskripte verwenden, die mit Subversion ausgeliefert werden, um zu verhindern, dass irgendjemand etwas anderes im Tag-Bereich macht, als dort neue Kopien zu erzeugen (siehe Kapitel 6, Die Administration eines Subversion-Servers). Der paranoide Ansatz ist normalerweise nicht notwendig. Falls ein Benutzer versehentlich eine Änderung an ein Tag-Verzeichnis übergeben hat, können Sie die Änderung einfach rückgängig machen, wie im vorhergehenden Abschnitt beschrieben. Schließlich handelt es sich um Versionskontrolle!
Manchmal möchten Sie vielleicht eine „Momentaufnahme“ machen, die komplizierter ist als ein einzelnes Verzeichnis mit einer einzigen Revision.
Stellen Sie sich beispielsweise vor, Ihr Projekt sei viel
größer als unser calc
Beispiel: Nehmen
wir an, es enthalte eine große Zahl von Unterverzeichnissen
und viel mehr Dateien. Während Ihrer Arbeit könnte es sein,
dass Sie sich entscheiden, eine Arbeitskopie anzulegen, die
bestimmte Merkmale und Fehlerbehebungen beinhaltet. Sie können
dies hinbekommen, indem Sie selektiv Dateien oder
Verzeichnisse auf bestimmte Revisionen zurückdatieren (unter
Verwendung von svn update mit der Option
-r
), indem Sie Dateien und Verzeichnisse auf
bestimmte Zweige umschalten (mit svn
switch) oder sogar, indem Sie ein paar lokale
Änderungen vornehmen. Wenn Sie fertig sind, ist Ihre
Arbeitskopie ein Mischmasch aus Repository-Quellen
verschiedener Revisionen. Nach dem Testen wissen Sie jedoch,
dass das genau die Kombination ist, die Sie mit einem Tag
versehen möchten.
Nun ist es an der Zeit, eine Momentaufnahme zu machen. Einen URL auf einen anderen zu kopieren hilft hier nicht weiter. In diesem Fall möchten Sie eine Momentaufnahme der exakten Anordnung Ihrer Arbeitskopie machen und sie im Repository speichern. Glücklicherweise besitzt svn copy vier verschiedene Anwendungsfälle (über die Sie in Kapitel 9, Subversion Complete Reference nachlesen können), zu denen auch die Fähigkeit gehört, einen Arbeitskopie-Baum ins Repository zu kopieren:
$ ls my-working-copy/ $ svn copy my-working-copy \ http://svn.example.com/repos/calc/tags/mytag \ -m "Ein Tag für den Zustand meines Arbeitsverzeichnisses anlegen." Revision 940 übertragen.
Nun gibt es ein neues Verzeichnis im Repository,
/calc/tags/mytag
, das eine exakte
Momentaufnahme Ihrer Arbeitskopie ist – gemischte
Revisionen, URLs, lokale Änderungen, usw.
Andere Benutzer haben interessante Anwendungsfälle für diese Fähigkeit von Subversion gefunden. Manchmal gibt es Situationen, in denen Sie ein paar lokale Änderungen in Ihrer Arbeitskopie gemacht haben, die ein Mitarbeiter sehen soll. Statt svn diff aufzurufen und eine Patch-Datei zu versenden (die allerdings weder Änderungen an Verzeichnissen, symbolischen Links oder Propertys beinhaltet), können Sie svn copy verwenden, um Ihre Arbeitskopie in einen privaten Bereich des Repositorys „abzulegen“. Ihr Mitarbeiter kann dann entweder eine exakte Kopie Ihrer Arbeitskopie auschecken oder svn merge verwenden, um genau Ihre Änderungen zu empfangen.
Obwohl dies eine nette Methode ist, schnell eine Momentaufnahme Ihrer Arbeitskopie anzulegen, sollten Sie beachten, dass es keine gute Vorgehensweise ist, einen Zweig zu erstellen. Die Erzeugung eines Zweigs sollte ein Ereignis für sich sein, wohingegen diese Methode die Erzeugung eines Zweigs mit zusätzlichen Änderungen an Dateien innerhalb einer einzelnen Revision verbindet. Das macht es später sehr schwer, eine einzelne Revisionsnummer als Verzweigungspunkt zu identifizieren.
Sie haben mittlerweile vielleicht festgestellt, dass Subversion äußerst flexibel ist. Da Zweigen und Tags derselbe Mechanismus zugrundeliegt (Verzeichniskopien) und weil Zweige und Tags im normalen Dateisystem auftauchen, finden viele Leute Subversion einschüchternd. Es ist beinahe zu flexibel. In diesem Abschnitt machen wir einige Vorschläge, wie Sie Ihre Daten im Laufe der Zeit organisieren und verwalten können.
Es gibt einige empfohlene Standards, ein Repository zu
organisieren. Die meisten Leute erzeugen ein
trunk
-Verzeichnis, um die Hauptlinie der
Entwicklung aufzunehmen, ein
branches
-Verzeichnis für Zweig-Kopien und
ein tags
-Verzeichnis für Tag-Kopien.
Falls ein Repository nur ein Projekt beinhaltet, werden oft
diese Verzeichnisse auf der obersten Ebene angelegt:
/trunk /branches /tags
Falls ein Repository mehrere Projekte enthält, teilen Administratoren das Repository üblicherweise nach den Projekten ein (lesen Sie in „Planung der Organisation Ihres Repositorys“ mehr über „Projekt-Wurzelverzeichnisse“):
/paint/trunk /paint/branches /paint/tags /calc/trunk /calc/branches /calc/tags
Natürlich ist es Ihnen freigestellt, diese verbreiteten Strukturen zu ignorieren. Sie können alle möglichen Variationen erzeugen, die am besten für Sie oder Ihr Team funktionieren. Denken Sie daran, dass es, wie auch immer Sie sich entscheiden, nicht für die Ewigkeit sein muss. Sie können jederzeit Ihr Repository umorganisieren. Da Zweige und Tags gewöhnliche Verzeichnisse sind, kann der Befehl svn move sie nach Belieben verschieben oder umbenennen. Die Umstrukturierung ist einfach eine Sache von serverseitigen Verschiebebefehlen. Wenn Ihnen der Aufbau des Repositorys nicht zusagt, jonglieren Sie einfach mit den Verzeichnissen herum.
Obwohl es einfach ist, Verzeichnisse zu verschieben, sollten Sie Rücksicht auf Ihre Benutzer nehmen. Ihr Jonglieren kann verwirrend für Benutzer mit bestehenden Arbeitskopien sein. Falls ein Benutzer eine Arbeitskopie eines bestimmten Repository-Verzeichnisses hat, könnte Ihre svn move-Operation den Pfad von der letzten Revision entfernen. Wenn der Benutzer beim nächsten Mal svn update aufruft, wird ihm mitgeteilt, dass die Arbeitskopie einen Pfad repräsentiere, der nicht mehr bestehe, so dass er gezwungen ist, mit svn switch auf den neuen Ort umzuschalten.
Eine weitere nette Eigenschaft des Subversion-Modells ist
die Möglichkeit, Zweigen und Tags eine begrenzte Lebensdauer
zu geben, so wie jedem anderen versionierten Objekt. Nehmen
wir beispielsweise an, dass Sie letztendlich Ihre Arbeit auf
dem persönlichen Zweig des calc
-Projektes
abschließen. Nachdem Sie all Ihre Änderungen zurück nach
/calc/trunk
gebracht haben, braucht Ihr
privater Zweig nicht mehr herumzuliegen:
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \ -m "Veralteten Zweig des Projekts calc gelöscht." Revision 375 übertragen.
Nun ist Ihr Zweig verschwunden. Selbstverständlich ist er
nicht wirklich verschwunden: das Verzeichnis fehlt einfach in
der HEAD
-Revision, so dass es niemanden
mehr ablenken kann. Wenn Sie svn checkout,
svn switch oder svn list
verwenden, um sich eine frühere Revision anzusehen, werden Sie
immer noch Ihren alten Zweig sehen.
Falls es nicht ausreichen sollte, im gelöschten
Verzeichnis zu stöbern, können Sie es jederzeit wieder
zurückholen. Das Wiederbeleben von Daten in Subversion ist
sehr einfach. Falls ein gelöschtes Verzeichnis (oder eine
gelöschte Datei) wieder nach HEAD
gebracht
werden soll, verwenden Sie einfach svn copy
zum Kopieren aus der alten Revision:
$ svn copy http://svn.example.com/repos/calc/branches/my-calc-branch@374 \ http://svn.example.com/repos/calc/branches/my-calc-branch \ -m "my-calc-branch wiederhergestellt." Revision 376 übertragen.
In unserem Beispiel hatte Ihr persönlicher Zweig eine
relativ kurze Lebensdauer: Sie haben ihn vielleicht angelegt,
um einen Fehler zu beseitigen oder eine neue Funktion
einzubauen. Wenn Ihr Arbeitspaket abgeschlossen ist, kann auch
der Zweig geschlossen werden. In der Softwareentwicklung ist
es allerdings auch üblich, zwei „Haupt“-Zweige zu
haben, die für lange Zeit nebeneinander bestehen. Es ist zum
Beispiel an der Zeit, eine stabile Version des
calc
-Projektes zu veröffentlichen, und
Sie wissen, dass es wohl noch ein paar Monate dauern wird, um
Fehler aus der Software zu entfernen. Sie wollen weder, dass
dem Projekt neue Funktionen hinzugefügt werden, noch möchten
Sie alle Entwicklern auffordern, das Programmieren
einzustellen. Stattdessen erstellen Sie einen
„stabilen“ Zweig der Software, auf dem sich nicht
viel verändern wird:
$ svn copy http://svn.example.com/repos/calc/trunk \ http://svn.example.com/repos/calc/branches/stable-1.0 \ -m "Stabilen Zweig für Projekt calc angelegt." Revision 377 übertragen.
Nun können Entwickler die neuesten (oder experimentellen)
Funktionen /calc/trunk
hinzufügen,
während Sie zum Grundsatz erklären, dass ausschließlich
Fehlerbehebungen an
/calc/branches/stable-1.0
übergeben
werden. Das heißt, während auf dem Stamm weitergearbeitet
wird, überträgt jemand selektiv Fehlerbehebungen auf den
stabilen Zweig. Selbst wenn die Software von hier bereits
ausgeliefert worden ist, werden Sie diesen Zweig
wahrscheinlich noch für eine lange Zeit pflegen – das
heißt, so lange, wie Sie diese Auslieferung beim Kunden
unterstützen werden. Wir werden das im nächsten Abschnitt
näher erörtern.
Es gibt zahlreiche unterschiedliche Anwendungsfälle für das Verzweigen und svn merge; dieser Abschnitt beschreibt die verbreitetesten.
Am häufigsten wird Versionskontrolle in der Softwareentwicklung verwendet, so dass wir an dieser Stelle kurz zwei der gebräuchlichsten Verzweigungs- und Zusammenführungsmuster vorstellen, die von Entwicklerteams benutzt werden. Falls Sie Subversion nicht in der Softwareentwicklung verwenden, können Sie den Abschnitt getrost überspringen. Falls Sie ein Softwareentwickler sind, der Versionskontrolle das erste Mal verwendet, sollten Sie gut aufpassen, da es sich bei diesen Mustern um bewährte Vorgehensweisen handelt, die von erfahrenen Menschen empfohlen werden. Diese Prozesse sind nicht spezifisch für Subversion; sie sind anwendbar auf alle Versionskontrollsysteme. Trotzdem mag es hilfreich sein, wenn sie anhand von Subversion erklärt werden.
Die meiste Software hat einen typischen Lebenszyklus: Erstellung, Test, Freigabe und wieder von vorne. Bei diesem Prozess gibt es zwei Probleme. Erstens müssen Entwickler neue Funktionen schreiben, während das Qualitätssicherungsteam sich Zeit zum Testen der vermeintlich stabilen Software nimmt. Die Arbeit kann allerdings nicht liegenbleiben während die Software getestet wird. Zweitens muss das Team fast immer ältere, bereits an den Kunden herausgegebene Software unterstützen; falls im neuesten Quelltext ein Fehler entdeckt wird, besteht der Fehler wahrscheinlich auch in der herausgegebenen Version. Die Kunden möchten dann eine Fehlerbehebung, ohne auf ein größeres, neues Release zu warten.
Hier kann Versionskontrolle helfen. Die typische Vorgehensweise ist wie folgt:
Entwickler übergeben alles Neue an den
Stamm.
Tägliche Änderungen werden an /trunk
übergeben: neue Funktionen, Fehlerbehebungen usw.
Der Stamm wird in einen
„Release“-Zweig kopiert.
Wenn das Team der Auffassung ist, dass die Software reif
für eine Freigabe ist (z.B. Release 1.0 ), kann
/trunk
nach
/branches/1.0
kopiert werden.
Die Teams arbeiten parallel.
Ein Team beginnt, den Release-Zweig sorgfältig zu testen,
während ein anderes Team mit der Arbeit (z.B. für Release
2.0) in /trunk
fortfährt. Falls hier
oder dort Fehler entdeckt werden sollten, werden die
Fehlerbehebungen nach Bedarf hin oder her kopiert. Zu
einem gegebenen Zeitpunkt hört jedoch sogar dieser Prozess
auf. Der Zweig wird für die Abschlusstests vor der
Freigabe „eingefroren“.
Der Zweig wird markiert und freigegeben.
Nach dem Abschluss der Tests wird
/branches/1.0
als Momentaufnahme nach
/tags/1.0.0
kopiert. Das Tag wird
paketiert und an den Kunden ausgeliefert.
Der Zweig wird gepflegt.
Während die Arbeit für Version 2.0 in
/trunk
weitergeht, werden weiterhin
Fehlerbehebungen von /trunk
nach
/branches/1.0
portiert. Wenn sich
ausreichend Fehlerbehebungen angesammelt haben, könnte
sich das Management entschließen, ein Release 1.0.1
herauszugeben: /branches/1.0
wird
nach /tags/1.0.1
kopiert, und das Tag
wird paketiert und freigegeben.
Der gesamte Prozess wiederholt sich während die Software reift: Wenn die Arbeit an 2.0 fertig ist, wird ein neuer 2.0 Release-Zweig erstellt, getestet, markiert und schließlich freigegeben. Nach einigen Jahren füllt sich das Repository mit einer Anzahl von Release-Zweigen, die weiterhin „gepflegt“ werden, und einer Zahl von Tags, die den endgültigen, ausgelieferten Versionen entsprechen.
Ein Funktions-Zweig ist die Art von
Zweig, wie er im Hauptbeispiel dieses Kapitels vorkam (der
Zweig, auf dem Sie gearbeitet haben, während Sally auf
/trunk
arbeitete). Es ist ein
vorübergehender Zweig, der angelegt wird, um an einer
komplexen Änderung zu arbeiten, ohne
/trunk
zu stören. Anders als
Release-Zweige (die vielleicht ewig gepflegt werden müssen),
werden Funktions-Zweige erstellt, eine Zeit lang genutzt,
zurück in den Stamm integriert und schließlich gelöscht. Sie
haben einen zeitlich begrenzten Nutzen.
In Projekten gehen die Meinungen oft auseinander, wann der
richtige Zeitpunkt zum Anlegen eines Funktions-Zweiges
gekommen ist. Manche Projekte benutzen nie Funktions-Zweige:
jeder darf Änderungen in /trunk
übergeben. Der Vorteil hier ist, dass es einfach ist –
niemand benötigt eine Schulung im Verzweigen und
Zusammenführen. Der Nachteil ist, dass der Code oft instabil
oder nicht nutzbar ist. Andere Projekte verwenden
ausschließlich Zweige: Eine Änderung darf
niemals direkt in
/trunk
übergeben werden. Selbst die
trivialsten Änderungen werden auf einem kurzlebigen Zweig
durchgeführt, sorgfältig geprüft und in den Stamm
zurückgeführt. Danach wird der Zweig gelöscht. Dieses Vorgehen
garantiert einen außerordentlich stabilen und nutzbaren Stamm,
jedoch zum Preis eines erheblichen Prozessaufwands.
Die meisten Projekte bewegen sich irgendwo dazwischen.
Gewöhnlich bestehen sie darauf, dass
/trunk
stets compilierfähig bleibt und
Regressionstests besteht. Ein Funktions-Zweig wird nur dann
benötigt, falls eine Änderung eine große Anzahl
destabilisierender Übergaben erfordert. Eine gute Faustregel
ist, diese Frage zu stellen: Wäre, falls ein Entwickler nach Tagen
isolierter Entwicklung die große Änderung auf einmal übergäbe
(so dass /trunk
nie instabil würde), die
Änderung zu umfangreich zum Überprüfen? Falls die Antwort auf
diese Frage „ja“ lautet, sollte die Änderung auf
einem Funktions-Zweig durchgeführt werden. Während der
Entwickler schrittweise Änderungen in den Zweig übergibt,
können sie auf einfache Weise von den Kollegen geprüft
werden.
Schließlich stellt sich die Frage, wie ein Funktions-Zweig am besten mit dem Stamm „synchron“ gehalten werden kann während die Arbeit weitergeht. Wie wir vorher bereits bemerkten, besteht ein großes Risiko, wenn wochen- oder monatelang auf dem Zweig gearbeitet wird; währenddessen ändert sich auch der Stamm, so dass ein Punkt erreicht werden kann, an dem sich die beiden Entwicklungslinien so sehr unterscheiden, dass es zu einem Albtraum ausarten kann, den Zweig zurück auf den Stamm zu führen.
Diese Situation wird am besten vermieden, indem regelmäßig Änderungen vom Stamm in den Zweig eingearbeitet werden. Machen Sie es zur Gewohnheit: Arbeiten Sie wöchentlich die Änderungen der vergangenen Woche vom Stamm in den Zweig ein.
Irgendwann werden Sie dann bereit sein, den
„synchronisierten“ Funktions-Zweig zurück in den
Stamm zu führen. Hierzu arbeiten Sie ein letztes Mal die
jüngsten Änderungen vom Stamm in den Zweig ein. Danach werden
die letzten Versionen auf dem Stamm und dem Zweig, bis auf Ihre
Änderungen auf dem Zweig, absolut gleich sein. Dann werden Sie
den Zweig mit der Option --reintegrate
wieder
mit dem Stamm zusammenführen:
$ cd trunk-working-copy $ svn update Revision 1910. $ svn merge --reintegrate http://svn.example.com/repos/calc/branches/mybranch -- Zusammenführen der Unterschiede zwischen Projektarchiv-URLs in ».«: U real.c U integer.c A newdirectory A newdirectory/newfile U . …
Aus einem anderen Winkel betrachtet ist dieser wöchentliche Abgleich vom Stamm auf den Zweig analog zum Ausführen von svn update in einer Arbeitskopie, wobei das finale Zusammenführen svn commit in einer Arbeitskopie entspricht. Ist denn letztendlich eine Arbeitskopie nicht ein sehr flacher privater Zweig? Es ist ein Zweig, der nur eine Änderung gleichzeitig aufnehmen kann.
Besonders in der Softwareentwicklung haben die von Ihnen versionsverwalteten Daten oft einen engen Bezug zu Daten von anderen, oder sind vielleicht abhängig davon. Allgemein wird der Bedarf ihres Projektes erfordern, dass Sie bezüglich der externen Datenquelle so aktuell wie möglich bleiben, ohne dabei die Stabilität Ihres Projektes zu opfern. Dieses Szenario entfaltet sich immer dort, wo die von einer Gruppe erzeugten Informationen direkte Auswirkungen auf diejenigen Informationen hat, die von einer anderen Gruppe erstellt werden.
So könnte es sein, dass Softwareentwickler beispielsweise an einer Anwendung arbeiten, die die Bibliothek eines Drittanbieters benötigt. Subversion hat eine solche Abhängigkeit von der Bibliothek Apache Portable Runtime (APR) (siehe „The Apache Portable Runtime Library“). Der Quelltext von Subversion hängt zur Gewährleistung der Portabilität von der APR-Bibliothek ab. In der frühen Phase der Entwicklung von Subversion hing das Projekt ziemlich nah am wechselnden API der APR, indem es immer die neueste Version des Quelltextes verwendete. Nun, da sowohl APR und Subversion gereift sind, versucht sich Subversion nur zu wohldefinierten Zeitpunkten mit dem APR-API zu synchronisieren, nämlich wenn dieses ausreichend getestet und stabil ist.
Falls nun Ihr Projekt von den Informationen anderer abhängt, können Sie diese Informationen auf mehrere Arten mit Ihren synchronisieren. Am umständlichsten ist es, wenn Sie mündliche oder schriftliche Anweisungen an alle Projektmitarbeiter ausgeben, dass sie sicherzustellen haben, stets über die für Ihr Projekt benötigten Versionen der Drittanbieter zu verfügen. Falls die Daten des Drittanbieters sich in einem Subversion-Repository befinden, können Sie auch mithilfe der Subversion-Externals-Definition bestimmte Versionen dieser Daten mit Ihrer eigenen Arbeitskopie verbinden (siehe „Externals Definitions“).
Allerdings möchten Sie von Zeit zu Zeit spezielle Anpassungen des Drittanbieter-Codes in Ihrem eigenen Versionskontrollsystem verwalten. Um auf unser Beispiel aus der Softwareentwicklung zurückzukommen, müssen Entwickler manchmal die Bibliothek der Drittanbieter für ihre Zwecke verändern. Diese Änderungen können neue Funktionalitäten oder Fehlerbehebungen beinhalten und werden nur solange intern verwaltet, bis sie eines Tages Teil einer offiziellen Auslieferung der Bibliothek werden. Es kann aber auch sein, dass diese Änderungen niemals an die Entwickler der Bibliothek zurückgegeben werden, sondern lediglich als spezielle Anpassungen bestehen, um die Bibliothek für Bedürfnisse der Softwareentwickler geeigneter zu machen.
Nun sind Sie in einer interessanten Situation: Ihr Projekt könnte seine Änderungen an den Daten von Drittanbietern auf getrennte Art und Weise verwalten, etwa in Form von Patch-Dateien oder als vollständig alternative Versionen. Jedoch wird so etwas schnell zu einem Albtraum, wenn es um die Pflege geht, da es ein Mechanismus benötigt wird, um diese Änderungen auf den Code des Drittanbieters anzuwenden und diese Anpassung bei jeder Folgelieferung zu wiederholen.
Die Lösung dieses Problems besteht in der Verwendung von Lieferanten-Zweigen. Ein Lieferanten-Zweig ist ein Verzeichnisbaum in Ihrem eigenen Versionskontrollsystem, der Informationen enthält, die von einem Drittanbieter – oder Lieferanten – bereitgestellt wird. Jede Version der Lieferantendaten, die Sie in Ihr Projekt aufnehmen wollen, wird Zulieferung genannt.
Lieferanten-Zweige bieten zwei Vorteile. Erstens, wird durch das Vorhalten der aktuellen Zulieferung in Ihrem eigenen Versionskontrollsystem sichergestellt, dass für Ihre Projektmitarbeiter stets die richtige Version der Lieferantendaten verfügbar ist. Sie erhalten die richtige Version automatisch beim Aktualisieren ihrer Arbeitskopien. Zweitens, da die Daten in Ihrem eigenen Subversion-Repository vorgehalten werden, können Sie dort auch Ihren Anpassungen speichern – es besteht keine Notwendigkeit mehr, Ihre Änderungen automatisch (oder schlimmer noch, manuell) in die Zulieferungen einzuarbeiten.
Die Verwaltung von Lieferanten-Zweigen funktioniert im
Allgemeinen so: Zunächst erzeugen Sie ein übergeordnetes
Hauptverzeichnis (etwa /vendor
), um
Lieferanten-Zweige aufzunehmen. Dann importieren Sie den Code
des Drittanbieters in ein Unterverzeichnis des
Hauptverzeichnisses. Anschließend kopieren Sie dieses
Unterverzeichnis an die passende Stelle Ihres
Hauptentwicklungszweigs (z.B. /trunk
).
Ihre lokalen Änderungen nehmen Sie stets im
Hauptentwicklungszweig vor. Jede erneut veröffentlichte
Version des von Ihnen verfolgten Codes pflegen Sie in den
Lieferanten-Zweig ein und überführen die Änderungen nach
/trunk
, wobei eventuelle Konflikte
zwischen Ihren lokalen Änderungen und dem Code des Zulieferers
aufgelöst werden.
Ein Beispiel hilft, um dieses Vorgehen zu erklären. Wir
gehen von einem Szenario aus, in dem Ihr Entwicklerteam ein
Taschenrechner-Programm entwickelt, dass mit einer Bibliothek
eines Drittanbieters für die Arithmetik mit komplexen Zahlen,
namens libcomplex, verlinkt wird. Wir beginnen mit dem Anlegen
des Lieferanten-Zweiges und dem Import der ersten Zulieferung.
Wir nennen unser Verzeichnis für den Lieferanten-Zweig
libcomplex
, und die Lieferungen werden in
einem Unterverzeichnis namens current
abgelegt. Da svn import alle dazwischen
liegenden Elternverzeichnisse erzeugt, können wir all diese
Schritte mit einem einzigen Befehl bewerkstelligen:
$ svn import /path/to/libcomplex-1.0 \ http://svn.example.com/repos/vendor/libcomplex/current \ -m 'Importing der ersten 1.0 Zulieferung' …
Nun haben wir die aktuelle Version des Quelltextes von
libcomplex in /vendor/libcomplex/current
.
Jetzt erzeugen wir ein Tag aus dieser Version (siehe „Tags“) und kopieren sie dann in
den Hauptentwicklungszweig. Unsere Kopie erzeugt ein neues
Verzeichnis libcomplex
im bestehenden
calc
Projektverzeichnis. In dieser
kopierten Version der Lieferantendaten werden wir unsere
Anpassungen vornehmen:
$ svn copy http://svn.example.com/repos/vendor/libcomplex/current \ http://svn.example.com/repos/vendor/libcomplex/1.0 \ -m 'Tag libcomplex-1.0' … $ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0 \ http://svn.example.com/repos/calc/libcomplex \ -m 'libcomplex-1.0 in den Huptzweig bringen' …
Wir checken nun den Hauptzweig unseres Projektes aus – der nun eine Kopie der ersten Zulieferung enthält – und fangen damit an, den Quelltext von libcomplex anzupassen. Ehe wir uns versehen, ist unsere angepasste Version von libcomplex vollständig in unser Taschenrechner-Programm integriert. [25]
Ein paar Wochen später veröffentlichen die Entwickler von libcomplex eine neue Version ihrer Bibliothek – Version 1.1 – die die Funktionalität enthält, die wir dringend benötigen. Wir möchten die neue Version verwenden, ohne jedoch unsere Anpassungen zu verlieren, die wir in der bestehenden Version vorgenommen haben. Unterm Strich möchten wir die bestehende Baseline-Version libcomplex 1.0 durch eine Kopie von libcomplex 1.1 ersetzen und die vorher gemachten Anpassungen an dieser Bibliothek erneut auf die neue Version anwenden. Tatsächlich gehen wir das Problem allerdings aus der anderen Richtung an, indem wir die Änderungen an libcomplex zwischen Version 1.0 und 1.1 in unsere angepasste Kopie einpflegen.
Um diesen Wechsel auf die neue Version durchzuführen,
checken wir eine Kopie des Lieferanten-Zweigs aus und ersetzen
den Code im Verzeichnis current
mit dem
neuen Quelltext von libcomplex 1.1. Wir kopieren im wahrsten
Sinne des Wortes die neuen Dateien über die bestehenden, indem
wir etwa das Archiv von libcomplex 1.1 in das bestehende
Verzeichnis entpacken. Das Ziel ist, dass das Verzeichnis
current
nur den Code von libcomplex 1.1
enthält, und dass dieser Code unter Versionskontrolle steht.
Oh, und wir wollen, dass das alles mit der geringsten Störung
an der Versionskontroll-Historie passiert.
Nachdem wir den 1.0 Code mit dem 1.1 Code ersetzt haben,
wird uns svn status sowohl Dateien mit
lokalen Änderungen als auch einige unversionierte Dateien
anzeigen. Wenn wir das getan haben, was wir tun sollten, sind
die unversionierten Dateien nur die mit Version 1.1 von
libcomplex hinzugekommenen neuen Dateien – wir rufen für
diese svn add auf, um sie unter
Versionskontrolle zu bringen. Falls der Code von 1.1 bestimmte
Dateien nicht mehr beinhaltet, die noch im Baum von 1.0
vorhanden waren, kann es schwierig sein, sie zu
identifizieren; Sie müssten die beiden Bäume mit einem
externen Werkzeug vergleichen und dann mit svn
delete Dateien entfernen, die in 1.0 jedoch nicht in
1.1 vorhanden sind. (Es könnte ebenso in Ordnung sein, diese
Dateien ungenutzt beizubehalten!) Sobald letztendlich unsere
Arbeitskopie von current
nur den Code von
libcomplex 1.1 enthält, übergeben wir die Änderungen, die uns
hierher gebracht haben.
Unser current
-Zweig enthält nun die
neue Zulieferung. Wir erzeugen nun ein Tag 1.1 (genauso, wie
wie es mit der Zulieferung 1.0 gemacht haben) und arbeiten
dann die Unterschiede zwischen dem Tag der vorherigen Version
und der neuen aktuellen Version in unseren
Hauptentwicklungszweig ein:
$ cd working-copies/calc $ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0 \ http://svn.example.com/repos/vendor/libcomplex/current \ libcomplex … # alle Konflikte zwischen ihren und unseren Änderungen auflösen $ svn commit -m 'merging libcomplex-1.1 into the main branch' …
Im trivialen Fall würde die neue Version der Drittanbieter-Bibliothek aus der Datei- und Verzeichnisperspektive genau so aussehen wie die vorherige Version. Keine der libcomplex Dateien wäre gelöscht, umbenannt oder an einen anderen Ort verschoben worden – die neue Version würde gegenüber der vorherigen lediglich textuelle Änderungen enthalten. In einer vollkommenen Welt würden sich unsere Anpassungen sauber in die neue Version einfügen, ganz ohne Komplikationen oder Konflikte.
Allerdings gestalten sich die Dinge nicht immer so einfach, und tatsächlich ist es normal, dass sich Quelltext-Dateien zwischen Software-Veröffentlichungen verschieben. Das verkompliziert das Vorgehen, um sicherzustellen, dass unsere Anpassungen für die neue Version immer noch gültig sind, und es kann schnell passieren, dass wir in eine Situation gelangen, in der wir unsere Anpassungen manuell in die neue Version einpflegen müssen. Sobald Subversion die Geschichte einer gegebenen Quelltext-Datei kennt – inklusive aller früheren Orte – ist das Vorgehen des Einpflegens in eine neue Version der Bibliothek recht einfach. Allerdings sind wir dafür verantwortlich, Subversion mitzuteilen, wie sich die Organisation des Quelltextes zwischen den Zulieferungen geändert hat.
Zulieferungen, die mehr als ein paar Löschungen, Hinzufügungen und Verschiebungen beinhalten, verkomplizieren das Vorgehen bei der Aktualisierung auf neuere Versionen der Drittanbieter-Daten. Aus diesem Grund stellt Subversion das Skript svn_load_dirs.pl zur Verfügung, das Sie dabei unterstützt. Dieses Skript automatisiert die zum Importieren notwendigen Schritte, die wir beim Vorgehen zur allgemeinen Verwaltung von Lieferanten-Zweigen erwähnten, um zu gewährleisten, dass es dabei zu möglichst wenig Fehlern kommt. Sie werden zwar immer noch dafür verantwortlich sein, mit den Zusammenführungs-Befehlen die neuen Versionen der Drittanbieter-Daten in Ihren Hauptentwicklungszweig einzupflegen, jedoch kann Ihnen svn_load_dirs.pl dabei helfen, diesen Punkt schneller und leichter zu erreichen.
Kurz gesagt ist svn_load_dirs.pl eine Verbesserung von svn import mit folgenden wichtigen Eigenschaften:
Es kann jederzeit aufgerufen werden, um ein bestehendes Verzeichnis im Repository exakt mit einem externen Verzeichnis abzugleichen, wobei alle notwendigen Hinzufügungen und Löschungen ausgeführt werden und darüberhinaus noch optionale Verschiebungen.
Es kümmert sich um komplizierte Abfolgen von Operationen zwischen denen Subversion eine eingeschobene Übergabe erforderlich macht – etwa vor dem zweifachen Umbenennen einer Datei oder eines Verzeichnisses.
Vom frisch importierten Verzeichnis wird optional ein Tag angelegt.
Es legt optional beliebige Propertys für Dateien und Verzeichnisse an, deren Name einem regulären Ausdruck entspricht.
svn_load_dirs.pl benötigt drei zwingend erforderliche Argumente. Das erste Argument ist der URL zum Basis-Subversion-Verzeichnis, in dem gearbeitet wird. Dieses Argument wird gefolgt von dem URL – relativ zum ersten Argument – wohin die aktuelle Zulieferung importiert werden soll. Schließlich gibt das dritte Argument an, aus welchem lokalen Verzeichnis importiert werden soll. In unserem vorigen Beispiel würde ein typischer Aufruf von svn_load_dirs.pl wie folgt aussehen:
$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \ current \ /path/to/libcomplex-1.1 …
Sie können svn_load_dirs.pl mitteilen,
dass Sie ein Tag von der neuen Zulieferung anlegen möchten,
indem Sie die Option -t
gefolgt von einem
Tag-Namen übergeben. Dieser Tag-Name ist auch ein URL relativ
zum ersten Argument des Programms.
$ svn_load_dirs.pl -t libcomplex-1.1 \ http://svn.example.com/repos/vendor/libcomplex \ current \ /path/to/libcomplex-1.1 …
Wenn Sie svn_load_dirs.pl aufrufen,
untersucht es den Inhalt Ihre existierenden Zulieferung
„current“ und vergleicht sie mit der
vorgeschlagenen neuen Zulieferung. Im trivialen Fall werden
keine Dateien ausschließlich in einer und nicht in der anderen
Zulieferung vorhanden sein, so dass das Skript den Import ohne
Probleme durchführt. Falls sich jedoch zwischen den Versionen
Unterschiede in der Dateistruktur ergeben sollten, fragt
svn_load_dirs.pl nach, wie die Unterschiede
aufgelöst werden sollen. So haben Sie zum Beispiel die
Möglichkeit, dem Skript mitzuteilen, dass die Datei
math.c
aus Version 1.0 von libcomplex in
der Version 1.1 von libcomplex in
arithmetic.c
umbenannt wurde. Alle
Diskrepanzen, die sich nicht durch Verschiebungen erklären
lassen, werden als normale Löschungen und Hinzufügungen
behandelt.
Das Skript akzeptiert auch eine gesonderte
Konfigurationsdatei, in der Propertys auf Dateien und
Verzeichnisse gesetzt werden können, deren Name einem
regulären Ausdruck entspricht und dem Repository
hinzugefügt werden. Diese
Konfigurationsdatei wird svn_load_dirs.pl
mit der Option -p
bekanntgegeben. Jede Zeile
der Konfigurationsdatei ist eine durch Leerraum begrenzte
Menge aus zwei oder vier Werten: ein regulärer Ausdruck wie in
Perl, zu dem der entsprechende Pfad passen muss, ein
Schlüsselwort zur Kontrolle (entweder break
oder cont
) und optional ein Property-Name
und ein Wert.
\.png$ break svn:mime-type image/png \.jpe?g$ break svn:mime-type image/jpeg \.m3u$ cont svn:mime-type audio/x-mpegurl \.m3u$ break svn:eol-style LF .* break svn:eol-style native
Für jeden hinzugefügten Pfad der dem regulären Ausdruck
einer Zeile entspricht, werden die Property-Änderungen der
Reihe nach durchgeführt, es sei denn, das
Kontroll-Schlüsselwort ist break
(was
bedeutet, dass keine weiteren Property-Änderungen für diesen
Pfad durchgeführt werden sollen). Falls das
Kontroll-Schlüsselwort cont
ist –
eine Abkürzung für continue
(fortfahren)
– wird mit der nächsten Zeile der Konfigurationsdatei
fortgefahren.
Jeglicher Leerraum im regulären Ausdruck, im Namen des
Propertys oder im Wert des Propertys muss entweder mit
einfachen oder doppelten Anführungszeichen umgeben werden.
Anführungszeichen, die nicht zum Umfassen von Leerraum
verwendet werden, können mit einem vorangestellten umgekehrten
Schrägstrich (\
) maskiert werden. Der
umgekehrte Schrägstrich maskiert nur Anführungszeichen beim
Lesen der Konfigurationsdatei, darum sollten Sie darüberhinaus
keine weiteren Zeichen maskieren.
Wir haben in diesem Kapitel sehr viel durchgenommen. Wir haben die Konzepte hinter Tags und Zweigen besprochen und gezeigt, wie Subversion diese Konzepte durch das Kopieren von Verzeichnissen mit dem Befehl svn copy umsetzt. Wir zeigten, wie mit svn merge Änderungen von einem Zweig in einen anderen überführt werden können oder fehlerhafte Änderungen rückgängig gemacht werden. Wir besprachen, wie mit svn switch Arbeitskopien aus verschiedenen Repository-Quellen erstellt werden können. Und wir sprachen darüber, wie Zweige in einem Repository verwaltet werden können.
Erinnern Sie sich an das Mantra von Subversion: Zweige und Tags sind billig. Scheuen Sie nicht, sie bei Bedarf zu nutzen!
Als eine hilfreiche Erinnerung an die besprochenen Operationen sei hier noch einmal eine Referenztabelle angeführt, die Sie benutzen können, während Sie damit beginnen, Zweige zu verwenden.
Tabelle 4.1. Befehle zum Verzweigen und Zusammenführen
Aktion | Befehl |
---|---|
Erstellung eines Zweigs oder eines Tags | svn copy |
Umschalten einer Arbeitskopie auf einen Zweig oder ein Tag | svn switch |
Synchronisierung eines Zweigs mit dem Stamm | svn merge |
Anzeige der Zusammenführungs-Geschichte oder in Frage kommender Änderungsmengen | svn mergeinfo target --from-source= |
Zurückführen des Zweigs in den Stamm | svn merge --reintegrate |
Einarbeiten einer bestimmten Änderung | svn merge -c |
Einarbeiten einer Serie von Änderungen | svn merge -r |
Eine Änderung für das automatische Zusammenführen blockieren | svn merge -c |
Vorschau einer Zusammenführung | svn merge |
Verwerfen des Ergebnisses einer Zusammenführung | svn revert -R . |
Etwas aus der Geschichte wiederbeleben | svn copy |
Eine übergebene Änderung rückgängig machen | svn merge -c - |
Anzeige der Geschichte unter Berücksichtigung von Zusammenführungen | svn log -g; svn blame -g |
Erzeugen eines Tags aus einer Arbeitskopie | svn copy . |
Einen Zweig oder ein Tag verschieben | svn mv |
Einen Zweig oder ein Tag löschen | svn rm |
[20] Subversion unterstützt nicht das Kopieren zwischen verschiedenen Repositorys. Wenn Sie mit svn copy oder svn move URLs verwenden, können Sie nur Objekte innerhalb desselben Repositorys kopieren oder verschieben.
[21] Allerdings gibt es im Subversion-Projekt Pläne, eines Tages einen Befehl zu implementieren, der die Aufgabe erledigen würde, Informationen dauerhaft zu löschen. Bis dahin, siehe „svndumpfilter“ für einen möglichen Notbehelf.
[22] Zumindest trifft das zur Zeit für Subversion 1.5 zu. Dieses Verhalten könnte sich in künftigen Versionen von Subversion verbessern.
[23] Interessanterweise werden wir nach dem
Zurücknehmen einer Revision auf diese Art nicht in der
Lage sein, diese Revision erneut mit svn
merge . -c 5
anzuwenden, da aus den
Metadaten hervorgeht, dass r5 bereits angewendet
wurde. Wir müssten die Option
--ignore-ancestry
verwenden, damit
der Befehl die bestehenden Metadaten ignoriert.
[24] Sie können jedoch svn
switch mit der Option --relocate
verwenden, falls sich der URL Ihres Servers geändert hat,
und Sie die bestehende Arbeitskopie nicht aufgeben wollen.
Siehe svn switch für weitere
Informationen und ein Beispiel.
[25] Und er ist natürlich völlig frei von Fehlern!
Inhaltsverzeichnis
Das Subversion-Repository ist die zentrale Lagerhalle für Ihre versionierten Daten. In dieser Rolle kann es sich aller Liebe und Zuneigung des Administrators gewiss sein. Obwohl das Repository an sich im Allgemeinen wenig Pflege erfordert, ist es wichtig, zu wissen, wie es angemessen konfiguriert und gepflegt wird, um etwaige Probleme zu vermeiden und bestehende Probleme sicher aufzulösen.
In diesem Kapitel werden wir erörtern, wie ein Subversion-Repository aufgesetzt und konfiguriert wird. Wir werden auch über die Repository-Pflege reden und Beispiele dafür geben, wann und wie die mit Subversion mitgelieferten Werkzeuge svnlook und svnadmin verwendet werden. Wir werden einige verbreitete Fragen und Fehler besprechen und Vorschläge unterbreiten, wie die Daten im Repository organisiert werden können.
Falls Sie vorhaben, das Repository lediglich in der Rolle eines Benutzers zu verwenden, der seine Daten unter Versionskontrolle stellen möchte (d.h. über einen Subversion-Client), können Sie dieses Kapitel vollständig überspringen. Wenn Sie jedoch ein Subversion-Repository-Administrator sind oder werden wollen, [26] dann ist dieses Kapitel für Sie gemacht.
Bevor wir uns in das weite Feld der Repository-Verwaltung begeben, wollen wir definieren, was ein Repository ist. Wie sieht es aus? Wie fühlt es sich an? Trinkt es seinen Tee heiß oder mit Eis, gesüßt oder mit Zitrone? Als Administrator wird von Ihnen erwartet, dass Sie den Aufbau eines Repositorys sowohl auf der physischen Betriebssystemebene verstehen – wie sich ein Subversion-Repository aussieht und wie es sich gegenüber Nicht-Subversion-Werkzeugen verhält – als auch aus einer logischen Perspektive – wie Daten innerhalb des Repositorys repräsentiert werden.
Mit den Augen eines typischen Dateibrowsers (wie Windows Explorer) oder von kommandozeilenorientierten Dateisystem-Navigationswerkzeugen ist das Subversion-Repository bloß ein weiteres gewöhnliches Verzeichnis voller Zeugs. Es gibt einige Unterverzeichnisse mit Konfigurationsdateien, die für Menschen lesbar sind, einige Unterverzeichnisse mit weniger lesbaren Datendateien usw. Wie in anderen Bereichen des Subversion-Designs, wird auch hier viel Wert auf Modularität gesetzt, und hierarchische Organisation wird vollgepfropftem Chaos vorgezogen. Ein flacher Blick in ein typisches Repository aus praxisbezogener Sicht reicht aus, um die grundlegenden Komponenten des Repositorys zu offenbaren.
$ ls repos conf/ dav/ db/ format hooks/ locks/ README.txt
Hier ist ein schneller, oberflächlicher Überblick über das, was Sie in diesem Verzeichnislisting sehen. (Verzetteln Sie sich nicht mit den Fachausdrücken – eine detaillierte Behandlung dieser Komponenten erfolgt an anderer Stelle in diesem und in anderen Kapiteln.)
Ein Verzeichnis, das Konfigurationsdateien enthält.
Ein Verzeichnis, das bereitgestellt wurde, damit
mod_dav_svn
seine privaten
Verwaltungsdaten dort ablegen kann
Der Datenspeicher für all Ihre versionierten Daten
Eine Datei, die eine einzelne Ganzzahl beinhaltet, die die Version der Repository-Struktur angibt
Ein Verzeichnis voller Hook-Script-Vorlagen (und den eigentlichen Hook-Scripten, sofern Sie welche installiert haben)
Ein Verzeichnis für die Sperrdateien des Subversion-Repositorys, die benutzt werden, um die Zugreifenden auf das Repository zu verfolgen
Eine Datei, deren Inhalt die Leser darüber informiert, dass sie in ein Subversion-Repository schauen
Selbstverständlich wird diese sonst so unauffällige Ansammlung aus Dateien und Verzeichnissen, wenn auf sie über die Subversion-Bibliotheken zugegriffen wird, eine Implementierung eines virtuellen, versionierten Dateisystems, vollständig mit anpassbaren Ereignis-Triggern. Dieses Dateisystem hat seine eigene Auffassung von Verzeichnissen und Dateien, sehr ähnlich den Auffassungen, die echte Dateisysteme (wie NTFS, FAT32, ext3 usw.) von solchen Dingen haben. Aber dies ist ein spezielles Dateisystem – es hängt diese Dateien und Verzeichnisse an Revisionen und hält alle Änderungen, die Sie daran vorgenommen haben, sicher abgespeichert und für immer abrufbereit. Hier lebt die Gesamtheit Ihrer versionierten Daten.
Größtenteils wegen der Einfachheit des Gesamtentwurfs des Subversion-Repositorys und der ihm zugrundeliegenden Technik, ist die Erstellung und Konfiguration eines Repositorys eine ziemlich unkomplizierte Aufgabe. Es gibt einige Entscheidungen, die Sie im Vorfeld treffen sollten, jedoch sind die eigentlichen Arbeitsschritte für die Einrichtung eines Subversion-Repositorys recht einfach und neigen zur stupiden Fleißarbeit, falls Sie mehrere davon aufzusetzen haben.
Einige Dinge, die Sie jedoch im Vorfeld sorgfältig prüfen sollten, sind:
Welche Art von Daten sollen in Ihrem Repository (oder Repositorys) abgelegt werden, und wie sind diese Daten organisiert?
Wo soll Ihr Repository untergebracht werden, und wie soll darauf zugegriffen werden?
Welche Art von Zugriffskontrolle und Ereignisbenachrichtigung benötigen Sie?
Welche der verfügbaren Datenspeicherungsarten möchten Sie verwenden?
In diesem Abschnitt werden wir versuchen, Ihnen beim Beantworten dieser Fragen zu helfen.
Obwohl Subversion Ihnen erlaubt, versionierte Dateien und Ordner ohne Informationsverlust hin und her zu verschieben und sogar Methoden anbietet, um versionierte Geschichte von einem Repository in ein anderes zu verschieben, kann das ziemlich den Arbeitsablauf derjenigen stören, die oft auf das Repository zugreifen und gewisse Dinge an bestimmten Orten erwarten. Bevor Sie ein neues Repository erstellen, sollten Sie also versuchen, ein wenig in die Zukunft zu schauen; planen Sie weitsichtig, bevor Sie Ihre Daten unter Versionskontrolle stellen. Durch die vorzeitige gewissenhafte „Anlage“ Ihres Repositorys oder mehrerer Repositorys können Sie viel künftigen Kopfschmerz vermeiden.
Nehmen wir an, Sie seien als Repository-Administrator für die Versionskontrollsysteme mehrerer Projekte zuständig. Ihre erste Entscheidung ist, ob Sie ein einzelnes Repository für mehrere Projekte verwenden, jedem Projekt sein eigenes Repository geben oder einen Kompromiss aus diesen beiden Lösungen haben wollen.
Ein einzelnes Repository für mehrere Projekte zu verwenden, hat einige Vorteile, am offensichtlichsten ist der vermiedene doppelte Verwaltungsaufwand. Ein einzelnes Repository bedeutet, dass es nur einen Satz Hook-Programme, ein Ding zum routinemäßigen Sichern, ein Ding für einen Auszug und zum anschließenden Laden nach einer inkompatiblen neuen Version von Subversion gibt usw. Sie können Daten auch einfach zwischen Projekten verschieben, ohne historische Versionierungsinformationen zu verlieren.
Der Nachteil bei der Verwendung eines einzelnen Repositorys ist, dass unterschiedliche Projekte auch unterschiedliche Anforderungen hinsichtlich der Repository-Ereignis-Trigger haben, wie etwa Benachrichtigungs-E-Mails bei Commits an unterschiedliche Verteiler, oder unterschiedliche Definitionen dazu, was eine berechtigte Übergabe ist und was nicht. Das sind natürlich keine unüberwindbaren Probleme – es bedeutet nur, dass all Ihre Hook-Skripte die Struktur Ihres Repositorys beachten müssen, anstatt davon auszugehen, dass das gesamte Repository von einer einzelnen Gruppe zugeordnet ist. Beachten Sie auch, dass Subversion Versionsnummern verwendet, die global für das gesamte Repository gelten. Obwohl diese Nummern keine Zauberkräfte haben, mögen manche Zeitgenossen es trotzdem nicht, dass, obwohl in letzter Zeit keine Änderungen in ihrem Projekt durchgeführt worden sind, die jüngste Versionsnummer im Repository ständig höher wird, weil andere Projekte fleißig neue Revisionen hinzufügen. [27]
Es kann auch eine Lösung in der Mitte gewählt werden. Beispielsweise können Projekte danach geordnet werden, wie stark sie miteinander verbunden sind. Sie könnten ein paar Repositorys haben, die jeweils eine handvoll Projekte beherbergen. Auf diese Art können Projekte, die wahrscheinlich gemeinsame Daten verwenden wollen, dies auch einfach bewerkstelligen, und wenn dem Repository neue Versionen hinzugefügt werden, wissen die Entwickler wenigstens, dass diese neuen Revisionen zumindest entfernt eine Beziehung zu jedem Benutzer dieses Repositorys haben.
Nachdem Sie entschieden haben, wie Sie Ihre Projekte in
Repositorys aufteilen, möchten Sie sich nun vielleicht
Gedanken darüber machen, welche Verzeichnishierarchien Sie im
Repository anlegen wollen. Da Subversion zum Verzweigen und
Taggen reguläre Verzeichniskopien verwendet (siehe Kapitel 4, Verzweigen und Zusammenführen), empfiehlt die
Subversion-Gemeinschaft, dass Sie einen Ort im Repository für
jedes Projekt-Wurzelverzeichnis wählen
– das oberste Verzeichnis, das Daten für Ihr Projekt
enthält – und hierunter dann drei Unterverzeichnisse
anlegen: trunk
, das Verzeichnis, in dem
die Hauptentwicklung stattfindet,
branches
, zur Aufnahme verschiedener
Zweige der Hauptentwicklungslinie und
tags
, als Sammlung von Momentaufnahmen
des Verzeichnisbaums, die erzeugt, vielleicht gelöscht, jedoch
nie verändert werden.
[28]
Ihr Repository könnte z.B. so aussehen:
/ calc/ trunk/ tags/ branches/ calendar/ trunk/ tags/ branches/ spreadsheet/ trunk/ tags/ branches/ …
Beachten Sie, dass es unerheblich ist, wo in Ihrem Repository sich das Wurzelverzeichnis Ihres Projektes befindet. Falls Sie nur ein Projekt pro Repository haben, ist der logische Ort für das Wurzelverzeichnis des Projektes das Wurzelverzeichnis des zum Projekt gehörenden Repositorys. Falls Sie mehrere Projekte haben, möchten Sie diese vielleicht innerhalb des Repositorys gruppieren, indem Sie Projekte ähnlichen Zwecks in demselben Unterverzeichnis unterbringen oder sie vielleicht nur alphabetisch gruppieren. Eine solche Anordnung könnte so aussehen:
/ utils/ calc/ trunk/ tags/ branches/ calendar/ trunk/ tags/ branches/ … office/ spreadsheet/ trunk/ tags/ branches/ …
Legen Sie Ihr Repository so an, wie es Ihnen am besten passt. Subversion erwartet oder erzwingt keine bestimmte Anordnung – für Subversion ist und bleibt ein Verzeichnis ein Verzeichnis. Letztendlich sollten Sie für ein Repository eine Struktur wählen, die den Bedürfnissen der Leute gerecht wird, die an den Projekten arbeiten, die dort untergebracht sind.
Der Vollständigkeit halber erwähnen wir noch eine weitere,
verbreitete Anordnung. Bei dieser Anordnung befinden sich die
Verzeichnisse trunk
,
tags
und branches
im
Wurzelverzeichnis des Repositorys und die Projekte in
Unterverzeichnissen davon:
/ trunk/ calc/ calendar/ spreadsheet/ … tags/ calc/ calendar/ spreadsheet/ … branches/ calc/ calendar/ spreadsheet/ …
An dieser Anordnung ist zwar nichts verkehrt, allerdings könnte es für Ihre Benutzer mehr oder weniger intuitiv sein. Besonders in Situationen mit vielen Projekten und entsprechend vielen Benutzern, kann es vorkommen, dass die Benutzer gewöhnlich nur mit einem oder zwei dieser Projekte vertraut sind. Allerdings schwächt dieser Projekt-als-Geschwister-Zweig-Ansatz die Betonung auf Projekt-Individualität und betrachtet die Gesamtmenge der Projekte als Ganzes. Das ist jedoch ein sozialer Aspekt. Wir mögen unseren ursprünglich geäußerten Vorschlag aus rein praktischen Erwägungen – es ist einfacher, in der kompletten Historie eines einzelnen Projektes zu forschen (oder sie zu verändern oder woandershin zu migrieren), wenn es einen einzelnen Pfad im Repository gibt, der die gesamte Historie für dieses eine Projekt, und nur dieses, beinhaltet – die Vergangenheit, Tags und Zweige.
Bevor Sie Ihr Subversion-Repository anlegen, bleibt die offensichtliche Frage zu beantworten, wo das Ding hin soll. Das hängt eng mit etlichen weiteren Fragen zusammen, etwa wie auf das Repository zugegriffen werden soll (über einen Subversion-Server oder direkt), wer darauf zugreifen soll (Benutzer hinter Ihrer Firmen-Firewall oder die weite Welt im offenen Netz), welche zusätzlichen Dienste Sie im Zusammenhang mit Subversion anbieten wollen (Schnittstellen zum Stöbern im Repository, Übergabebenachrichtigungen per E-Mail usw.), Ihre Sicherungsstrategie und vieles mehr.
Die Auswahl und Konfigurierung des Servers werden wir in Kapitel 6, Die Administration eines Subversion-Servers behandeln; jedoch möchten wir an dieser Stelle kurz darauf hinweisen, dass die Antworten auf einige der anderen Fragen zur Folge haben, dass Sie bei der Entscheidung über den Speicherorte für das Repository keine freie Wahl mehr haben. Beispielsweise könnten bestimmte Einsatzumgebungen erfordern, dass von mehreren Rechnern über ein freigegebenes Dateisystem auf das Repository zugegriffen werden muss, so dass (wie Sie im nächsten Abschnitt lesen werden) die Wahl der dem Repository zugrundeliegenden Datenspeicherung gar keine Wahl mehr ist, da nur eine der verfügbaren Datenspeicherungsverfahren in dieser Umgebung funktionieren wird.
Es ist unmöglich, und würde auch den Rahmen dieses Buches sprengen, wenn jede erdenkliche Einsatzart von Subversion angesprochen würde. Wir ermutigen Sie einfach, Ihre Optionen zu prüfen, indem Sie diese Seiten und weitere Quellen als Referenz verwenden und weitsichtig planen.
Subversion unterstützt zwei Optionen für das zugrundeliegende Datenspeicherungsverfahren – oft bezeichnet als „das Backend“ oder, etwas verwirrend, „das (versionierte) Dateisystem“ — welches jedes Repository verwendet. Das eine Verfahren speichert alles in einer Berkeley-DB- (oder BDB-) Datenbankumgebung; Repositorys, die dieses Verfahren verwenden, werden oft „BDB-basiert“ genannt. Das andere Verfahren speichert die Daten in gewöhnlichen, flachen Dateien, die ein spezielles Format verwenden. Unter Subversion-Entwicklern hat sich dafür die Bezeichnung FSFS [29] eingebürgert – eine Implementierung eines versionierten Dateisystems, dass direkt das Dateisystem des Betriebssystems verwendet – statt einer Datenbankbibliothek oder einer anderen Abstraktionsebene – um Daten zu speichern
Tabelle 5.1, „Vergleich der Repository-Datenspeicherung“ liefert einen Vergleich zwischen Berkeley-DB- und FSFS-Repositorys.
Tabelle 5.1. Vergleich der Repository-Datenspeicherung
Kategorie | Funktion | Berkeley DB | FSFS |
---|---|---|---|
Zuverlässigkeit | Unversehrtheit der Daten | Höchst zuverlässig, wenn es richtig aufgesetzt wird; Berkeley DB 4.4 bringt automatische Wiederherstellung | Ältere Versionen hatten einige selten aufgetretene, jedoch datenzerstörende Fehler |
Empfindlichkeit gegenüber Unterbrechungen | Sehr; Abstürze und Berechtigungsprobleme können die Datenbank „verklemmt“ hinterlassen, was eine Wiederherstellung mithilfe des Journals erfordert | Ziemlich unempfindlich | |
Zugriffsmöglichkeiten | Benutzbar über eine Laufwerk mit Nur-Lese-Zugriff | Nein | Ja |
Plattformunabhängige Speicherung | Nein | Ja | |
Benutzbar über Netz-Dateisysteme | Im Allgemeinen nicht | Ja | |
Behandlung von Gruppenberechtigungen | Empfindlich für Probleme mit der Benutzer-umask; Zugriff am besten nur durch einen Benutzer | Umgeht umask-Probleme | |
Skalierbarkeit | Plattenplatzbedarf des Repositorys | Größer (besonders, wenn Protokolldateien nicht gekürzt werden) | Kleiner |
Anzahl an Revisionsbäumen | Datenbank; keine Probleme | Einige ältere Dateisysteme lassen sich mit tausenden Einträgen in einem Verzeichnis nicht gut skalieren | |
Verzeichnisse mit vielen Dateien | Langsamer | Schneller | |
Arbeitsleistung | Auschecken der letzten Revision | Kein spürbarer Unterschied | Kein spürbarer Unterschied |
Große Übergaben | Insgesamt langsamer, aber die Kosten amortisieren sich über die Dauer der Übergabe | Insgesamt schneller, jedoch können Abschlussarbeiten zu Zeitüberschreitungen beim Client führen. |
Beide dieser Verfahren haben Vor- und Nachteile. Keins davon ist „offizieller“ als das andere, obwohl das neuere FSFS seit Subversion 1.2 das Standardverfahren ist. Beide verfügen über die ausreichende Zuverlässigkeit, um ihnen Ihre versionierten Daten anzuvertrauen. Doch wie sie in Tabelle 5.1, „Vergleich der Repository-Datenspeicherung“ sehen können, bietet das FSFS-Verfahren bezüglich seiner unterstützten Einsatzumgebungen wesentlich mehr Flexibilität. Mehr Flexibilität bedeutet, dass Sie sich mehr anstrengen müssen, um es falsch einzusetzen. Dies sind die Gründe – hinzu kommt, dass beim Verzicht auf Berkeley DB sich eine Komponente weniger im System befindet – warum heutzutage beinahe jeder das FSFS-Verfahren verwendet, wenn neue Repositorys angelegt werden.
Glücklicherweise interessiert es die meisten Programme die auf Subversion-Repositorys zugreifen nicht, welches Speicherverfahren verwendet wird. Außerdem sind Sie mit Ihrer ersten Entscheidung für das Speicherverfahren nicht notwendigerweise festgelegt – falls Sie es sich später anders überlegen sollten, bietet Subversion Methoden zur Migration der Daten im Repository in ein anderes Repository, das ein unterschiedliches Speicherverfahren verwendet. Wir werden das später in diesem Kapitel erörtern.
Die folgenden Unterabschnitte bieten einen detaillierten Blick auf die verfügbaren Speicherverfahren.
In der anfänglichen Entwurfsphase von Subversion entschieden sich die Entwickler aus einer Reihe von Gründen, Berkeley DB zu verwenden. Hierzu zählen die quelloffene Lizenz, Transaktionsunterstützung, Zuverlässigkeit, Arbeitsleistung, Einfachheit der Programmierschnittstelle, Thread-Sicherheit, Cursor-Unterstützung usw.
Berkeley DB bietet echte Transaktionsunterstützung – vielleicht seine stärkste Funktion. Mehrere Prozesse, die auf Ihre Subversion-Repositorys zugreifen, brauchen sich keine Sorgen machen, dass sie sich versehentlich gegenseitig die Daten zerschießen. Die durch das Transaktiossystem gebotene Isolation bedeutet, dass der Subversion-Repository-Programmcode für jede gegebene Operation eine statische Sicht auf die Datenbank hat – keine sich durch die Einflüsse anderer Prozesse ständig ändernde Datenbank – und basierend auf dieser Sicht Entscheidungen treffen kann. Falls die getroffene Entscheidung zu einem Konflikt damit führt, was eine anderer Prozess macht, wird die gesamte Transaktion zurückgerollt, als wäre sie nie passiert, und Subversion versucht höflich, die Operation mithilfe einer aktualisierten (aber immer noch statischen) Sicht der Datenbank erneut durchzuführen.
Eine weitere großartige Funktion von Berkeley DB sind Hot Backups – die Fähigkeit, die Datenbankumgebung zu sichern, ohne sie „vom Netz“ zu nehmen. Wir besprechen später in diesem Kapitel, wie Sie Ihr Repository sichern (in „Repository Backup“), doch sollten die Vorteile offensichtlich sein, die dadurch entstehen, dass Sie vollständige Sicherheitskopien Ihrer Repositorys ohne Wartungszeiträume machen können.
Bei Berkeley DB handelt es sich auch um ein sehr zuverlässiges Datenbanksystem, wenn es richtig verwendet wird. Subversion benutzt das Protokollierungssystem von Berkeley DB, was bedeutet, dass die Datenbank zunächst eine Beschreibung der Veränderungen in Protokolldateien auf der Platte schreibt, bevor die Veränderungen selbst durchgeführt werden. Dies stellt sicher, dass, falls etwas schief geht, die Datenbank zu einem früheren Sicherungspunkt zurückgehen kann – eine Stelle in den Protokolldateien, von der bekannt ist, dass sie eine nicht beschädigte Datenbank bezeichnet – und Transaktionen solange wiederholen kann, bis die Daten sich wieder in einem brauchbaren zustand befinden. Siehe „Plattenplatzverwaltung“ weiter unten in diesem Kapitel für weitere Informationen zu Berkeley-DB-Protokolldateien.
Doch keine Rose ohne Dornen, uns so müssen wir auch einige bekannte Einschränkungen von Berkeley DB ansprechen. Erstens sind Berkeley-DB -Umgebungen nicht portierbar. Sie können nicht einfach ein unter Unix erzeugtes Subversion-Repository auf ein Windows-System kopieren und erwarten, dass es funktioniert. Obwohl ein Großteil des Berkeley-DB-Datenbankformats architekturunabhängig ist, sind es andere Teile der Umgebung nicht. Zweitens benutzt Subversion Berkeley DB auf eine Weise, die nicht auf Windows 95/98 funktioniert – falls Sie ein BDB-basiertes Repository auf einer Windows-Maschine unterbringen müssen, bleiben Sie bei Windows 2000 oder einem seiner Nachfolger.
Obwohl Berkeley DB verspricht, sich korrekt auf freigegebenen Netzlaufwerken zu verhalten, die bestimmte Anforderungen erfüllen, [30] bieten die meisten Netz-Dateisysteme keine derartige Unterstützung. Und keinesfalls dürfen Sie zulassen, dass gleichzeitig von mehreren Clients auf ein BDB-basiertes Repository auf einer Netzfreigabe zugegriffen wird (was eigentlich der Hauptgrund dafür ist, das Repository auf einer Netzfreigabe unterzubringen).
Falls Sie versuchen sollten, Berkeley DB auf einem Netz-Dateisystem unterzubringen, das die Anforderungen nicht erfüllt, ist das Ergebnis unvorhersehbar – es kann sein, dass Sie sofort mysteriöse Fehler wahrnehmen oder es kann Monate dauern, bis Sie bemerken, dass Ihre Repository-Datenbank fast unmerklich beschädigt ist. Sie sollten ernsthaft erwägen, das FSFS-Speicherverfahren für Repositorys zu verwenden, die auf einer Netzfreigabe untergebracht werden sollen.
Schließlich ist Berkeley DB empfindlicher gegenüber Unterbrechungen als ein typisches relationales Datenbanksystem, da es sich um eine Bibliothek handelt, die direkt in Subversion eingebunden ist. Beispielsweise haben die meisten SQL-Systeme einen dedizierten Server-Prozess, der alle Tabellenzugriffe vermittelt. Falls ein auf die Datenbank zugreifendes Programm aus irgendeinem Grund abstürzt, bemerkt der Datenbank-Dämon die verlorene Verbindung und räumt anschließend auf. Und da der Datenbank-Dämon der einzige Prozess ist, der auf die Tabellen zugreift, brauchen sich Anwendungsprogramme nicht um Berechtigungskonflikte zu kümmern. Das trifft allerdings nicht auf Berkeley DB zu. Subversion (und jedes Programm, das die Subversion-Bibliotheken verwendet) greift direkt auf die Datenbanktabellen zu, was bedeutet, dass ein Programmabsturz die Datenbank vorübergehend in einem inkonsistenten, nicht zugreifbaren Zustand hinterlassen kann, so dass ein Administrator Berkeley DB dazu auffordern muss, zu einem Sicherungspunkt zurückzugehen, was etwas ärgerlich ist. Neben abgestürzten Prozessen können andere Dinge das Repository „verklemmen“, wie etwa Programme, die sich wegen Eigentums- und Zugriffsrechten auf Datenbankdateien ins Gehege kommen.
Berkeley DB 4.4 bietet (für Subversion 1.4 und spätere Versionen) die Fähigkeit, dass Subversion falls erforderlich automatisch und transparent Berkeley-DB-Umgebungen wiederherstellt. Wenn sich ein Subversion-Prozess an die Berkeley-DB-Umgebung hängt, verwendet er eine Art Prozess-Buchhaltung, um unsaubere Verbindungsabbrüche früherer Prozesse zu entdecken, führt die notwendige Wiederherstellung durch und fährt fort, als wäre nichts passiert. Dies verhindert das Vorkommen von Verklemmungen zwar nicht vollständig, verringert allerdings erheblich den Aufwand an menschlichen Eingriffen, um sich hiervon zu erholen.
Während ein Berkeley-DB-Repository ziemlich schnell und
skalierbar ist, wird es am besten von einem einzelnen
Server-Prozess unter einer Benutzerkennung verwendet –
so wie Apaches httpd oder
svnserve (siehe Kapitel 6, Die Administration eines Subversion-Servers) – statt darauf mit
mehreren Benutzern über file://
oder
svn+ssh://
URLs zuzugreifen. Falls Sie
mit mehreren Benutzern direkt auf ein Berkeley-DB-Repository
zugreifen wollen, sollten Sie unbedingt „Supporting Multiple Repository Access Methods“ weiter unten in
diesem Kapitel lesen.
Mitte 2004 entstand ein zweiter Typ eines Repository-Speichersystems – eins, das überhaupt keine Datenbank verwendet. Ein FSFS-Repository speichert die zu einer Revision gehörenden Änderungen in einer einzelnen Datei, so dass sich alle Revisionen eines Repositorys in einem Verzeichnis voller nummerierter Dateien befinden. Transaktionen werden als individuelle Dateien in getrennten Verzeichnissen erzeugt. Sobald sie vollständig ist, wird die Transaktionsdatei umbenannt und in das Revisionsverzeichnis verschoben, so dass die Atomizität von Übergaben gewährleistet ist. Und da eine Revisionsdatei dauerhaft und unveränderlich ist, kann das Repository auch im laufenden Betrieb gesichert werden, genauso wie ein BDB-basiertes Repository.
Die FSFS-Revisionsdateien beschreiben die Verzeichnisstruktur einer Revision, Dateiinhalte und Deltas zu Dateien in anderen Revisionsbäumen. Anders als eine Berkeley-DB-Datenbank, ist dieses Speicherformat auf verschiedene Betriebssysteme übertragbar und nicht von einer CPU-Architektur abhängig. Da weder Journaldateien noch Dateien für gemeinsam benutzten Speicher verwendet werden, kann auf das Repository sicher über ein Netzdateisystem zugegriffen und es in einer Nur-Lese-Umgebung untersucht werden. Das Fehlen der Datenbankverwaltung bedeutet ebenfalls eine etwas geringere Größe des Repositorys.
FSFS hat auch eine unterschiedliche Charakteristik, was den Durchsatz anbelangt. Wenn eine große Zahl an Dateien übergeben wird, kann FSFS schneller Verzeichniseinträge hinzufügen. Andererseits schreibt FSFS die letzte Version einer Datei als ein Delta gegenüber einer älteren Version, was bedeutet, dass das Auschecken des letzten Baums etwas langsamer ist als die vollständigen Texte zu holen, die in einer Berkeley-DB HEAD-Revision gespeichert sind. FSFS hat auch eine längere Verzögerung beim Fertigstellen einer Übergabe, was im Extremfall dazu führen kann, dass bei Clients Zeitüberschreitungen beim Warten auf eine Antwort auftreten.
Der wichtigste Unterschied jedoch ist die Unempfänglichkeit von FSFS gegenüber Verklemmungen, wenn etwas schief geht. Falls ein Prozess, der eine Berkeley-DB-Datenbank benutzt, ein Berechtigungsproblem bekommt oder plötzlich abstürzt, kann das die Datenbank in einen unbrauchbaren Zustand bringen, bis ein Administrator sie wiederherstellt. Falls ein Prozess, der ein FSFS-Repository benutzt, in dieselbe Situation gerät, ist das Repository hiervon überhaupt nicht betroffen. Das Schlimmste, was passieren kann, ist, dass einige Transaktionsdaten nicht abgearbeitet werden können.
Das einzige echte Argument, was gegen FSFS spricht, ist seine relative Unreife im Gegensatz zu Berkeley DB. Anders als Berkeley DB, das auf eine jahrelange Geschichte zurückblicken kann, ein eigenes Entwicklerteam hat und sich nun mit dem mächtigen Namen Oracle schmücken darf, [31] ist FSFS eine neuere Technik. Vor Subversion 1.4 purzelten immer noch einige ernsthafte Fehler in Bezug auf die Unversehrtheit der Daten heraus, die, obwohl sie sehr selten ausgelöst wurden, dennoch auftraten. Nichtsdestoweniger ist FSFS schnell zum Speicherverfahren der Wahl für einige der größten öffentlichen und privaten Subversion-Repositorys geworden und verspricht durch die Bank eine niedrigere Einstiegshürde für Subversion.
Weiter oben in diesem Kapitel (in „Strategien für die Verwendung eines Repositorys“), schauten wir auf einige der wichtigen Entscheidungen, die zu treffen sind, bevor Ihr Subversion-Repository angelegt und konfiguriert wird. Jetzt schaffen wir es endlich, uns die Hände schmutzig zu machen! In diesem Abschnitt werden wir sehen, wie ein Subversion-Repository überhaupt angelegt wird und wie es konfiguriert wird, damit es bei bestimmten Repository-Ereignissen spezielle Aktionen ausführt.
Das Anlegen eines Subversion-Repositorys ist eine unglaublich einfache Aufgabe. Das mit Subversion gelieferte Dienstprogramm svnadmin stellt ein Unterbefehl (svnadmin create) zur Verfügung, der genau das macht.
$ # Ein Repository anlegen $ svnadmin create /var/svn/repos $
Damit wird ein neues Repository im Verzeichnis
/var/svn/repos
mit dem
Standard-Speicherverfahren angelegt. Vor Subversion 1.2 war es
Berkeley DB, nun ist es FSFS. Sie können den Dateisystemtypen
ausdrücklich wählen, indem Sie das Argument
--fs-type
benutzen, das als Parameter
entweder fsfs
oder bdb
zulässt.
$ # Ein FSFS-basiertes Repository anlegen $ svnadmin create --fs-type fsfs /var/svn/repos $
# Ein Berkeley-DB-basiertes Repository anlegen $ svnadmin create --fs-type bdb /var/svn/repos $
Nach dem Ausführen dieses einfachen Befehls haben Sie ein Subversion-Repository.
Das Pfad-Argument zu svnadmin ist
bloß ein gewöhnlicher Pfad im Dateisystem und kein URL wie
ihn das Client-Programm svn verwendet, um
auf Repositorys zu verweisen. Sowohl
svnadmin als auch
svnlook werden als serverseitige
Dienstprogramme betrachtet – sie werden auf dem
Rechner benutzt, auf dem das Repository untergebracht ist,
um Aspekte des Repositorys zu untersuchen oder zu verändern;
tatsächlich sind sie nicht in der Lage, Aufgaben über das
Netz zu erledigen. Ein verbreiteter Fehler von
Subversion-Neulingen ist der Versuch, URLs (sogar
„lokale“ vom Typ file://
) an
diese zwei Programme zu übergeben.
Im Unterverzeichnis db/
Ihres
Repositorys befindet sich die Implementierung des
versionierten Dateisystems. Das Leben des versionierten
Dateisystems Ihres Repositorys beginnt mit Revision 0, die aus
nichts anderem als dem Wurzelverzeichnis
(/
) besteht. Zu Beginn hat die Revision 0
ein einziges Revisions-Property, svn:date
,
das als Wert die Angabe des Zeitpunktes besitzt, zu dem das
Repository angelegt wurde.
Da Sie nun ein Repository haben, ist es an der Zeit, es anzupassen.
Während einige Teile des Repositorys – wie die Konfigurationsdateien und Hook-Scripts – für eine manuelle Untersuchung und Bearbeitung gedacht sind, sollten Sie nicht (und sie sollten es auch nicht nötig haben) an den anderen Teilen des Repositorys „händisch“ herumdoktern. Das Dienstprogramm svnadmin sollte für alle notwendigen Änderungen an Ihrem Repository ausreichen; sie können auch Dienstprogramme von Drittanbietern (wie das Werkzeugpaket von Berkeley DB) verwenden, um in entsprechenden Unterabschnitten des Repositorys Änderungen vorzunehmen. Versuchen Sie nicht, die Historie Ihrer Versionskontrolle manuell zu verändern, indem Sie in den Speicherdateien des Repositorys herumstochern!
Ein Hook (Haken) ist ein Programm, das durch einige Repository-Ereignisse gestartet wird, wie etwa die Erzeugung einer neuen Revision oder die Veränderung eines unversionierten Propertys. Einige Hooks (die sogenannten „Pre-Hooks“) starten vor einer Repository-Operation und bieten eine Möglichkeit sowohl zu berichten, was passieren wird, als auch zu verhindern, dass es überhaupt passiert. Andere Hooks (die „Post-Hooks“) starten nach Abschluss eines Repository-Ereignisses und sind nützlich für Aufgaben, die das Repository inspizieren – aber nicht verändern. Jedem Hook wird ausreichend Information übergeben, damit er feststellen kann, um welches Ereignis es sich handelt (oder handelte), welche genauen Änderungen am Repository beabsichtigt sind (oder durchgeführt wurden) und wie der Name des Benutzers lautet, der das Ereignis ausgelöst hat.
Das Verzeichnis für die Hooks
ist
standardmäßig mit Vorlagen für verschiedene Repository-Hooks
gefüllt:
$ ls repos/hooks/ post-commit.tmpl post-unlock.tmpl pre-revprop-change.tmpl post-lock.tmpl pre-commit.tmpl pre-unlock.tmpl post-revprop-change.tmpl pre-lock.tmpl start-commit.tmpl $
Es gibt eine Vorlage für jeden Hook, den Subversion
unterstützt. Sie können sehen, wodurch jedes dieser Scripte
gestartet wird und welche Daten übergeben werden, indem Sie
den Inhalt der Scripte inspizieren. In vielen dieser Vorlagen
befinden sich auch Beispiele dafür, wie dieses Script zusammen
mit anderen Programmen aus dem Lieferumfang von Subversion
verwendet werden kann, um häufige, nützliche Aufgaben zu erledigen.
Um einen funktionierenden Hook zu installieren, brauchen Sie
nur ein ausführbares Programm oder Script im Verzeichnis
repos/hooks
abzulegen, das unter dem
Namen des Hooks (etwa start-commit oder
post-commit) gestartet werden kann.
Auf Unix Plattformen bedeutet das, ein Script oder
Programm bereitzustellen (welches ein Shell-Script, ein
Python-Programm, ein übersetztes C-Binärprogramm oder
sonstetwas sein kann), das genauso heißt wie der Hook.
Natürlich sind die Vorlagen nicht nur zur Information da
– die einfachste Möglichkeit, unter Unix einen Hook zu
installieren, ist es, einfach die passende Vorlagedatei in
eine Datei zu kopieren, der die Dateiendung
.tmpl
fehlt, den Inhalt anzupassen und
sicherzustellen, dass das Script ausführbar ist. Unter Windows
werden jedoch Dateiendungen verwendet, um festzustellen, ob
ein Programm ausführbar ist, so dass Sie ein Programm zur
Verfügung stellen müssen, dessen Basisname dem Hook entspricht
und dessen Endung einer derjenigen entspricht, die Windows für
ausführbare Programme hält, etwa .exe
für
Programme und .bat
für
Batch-Dateien.
Aus Sicherheitsgründen führt Subversion Hook-Programme
in einer leeren Umgebung aus – d.h., es sind überhaupt
keine Umgebungsvariablen gesetzt, nicht einmal
$PATH
(oder %PATH%
unter Windows). Deshalb sind viele Administratoren verwirrt,
wenn deren Hook-Programme normal starten, wenn sie manuell
aufgerufen werden, aber nicht laufen, wenn sie Subversion
startet. Stellen Sie sicher, dass Sie entweder alle
notwendigen Umgebungsvariablen in Ihren Hook-Programmen
ausdrücklich setzen und/oder absolute Pfade zu Programmen
verwenden.
Subversion führt die Hooks unter der Benutzerkennung aus, die auch der Prozess besitzt, der auf das Repository zugreift. Meistens wird auf das Repository über einen Subversion-Server zugegriffen, so dass die Benutzerkennung der des Serverprozesses entspricht. Die Hooks müssen deshalb mit den entsprechenden Berechtigungen des Betriebssystems versehen werden, damit diese Benutzerkennung sie ausführen kann. Das bedeutet auch, dass der direkte oder indirekte Zugriff auf irgendwelche Programme oder Dateien (einschließlich des Subversion-Repositorys) durch den Hook auch unter derselben Kennung erfolgt. Mit anderen Worten: Achten Sie auf mögliche Probleme im Zusammenhang mit Zugriffsrechten, die den Hook daran hindern könnten, die Ihm zugeteilten Aufgaben wahrzunehmen.
Es gibt mehrere im Subversion-Repository implementierte Hooks; Details zu jedem können Sie in „Repository Hooks“ nachlesen. Als Repository-Administrator müssen Sie entscheiden, welche Hooks sie einrichten wollen (indem Sie ein entsprechend benanntes und mit den nötigen Zugriffsrechten versehenes Hook-Programm bereitstellen) und wie Sie sie einsetzen wollen. Wenn Sie diese Entscheidung treffen, dann behalten Sie das Gesamtbild des Repository-Einsatzes im Auge. Wenn Sie beispielsweise die Konfiguration des Servers verwenden, um festzustellen, welche Benutzer Änderungen an Ihr Repository übergeben dürfen, benötigen Sie für diese Zugriffskontrolle nicht das Hook-System.
Es gibt keinen Mangel an Subversion-Hook-Programmen und Scripten, die frei verfügbar sind, entweder von der Subversion-Gemeinschaft oder von woanders her. Diese Scripte decken ein breites Spektrum ab – grundlegende Zugriffskontrolle, Kontrolle der Prozesstreue, Fehlersystemanbindung, E-Mail-basierte oder syndizierte Benachrichtigungen bei Übergaben und noch viel mehr. Oder, falls Sie Ihren eigenen schreiben wollen, siehe Kapitel 8, Embedding Subversion.
Obwohl Hook-Scripts fast alles machen können, gibt es
eine Dimension, in der sich Hook-Script-Autoren zurückhalten
sollten: Ändern Sie keine
Übergabe-Transaktion mithilfe von Hook-Scripten. Trotz der
Verlockung, Hook-Scripte zur automatischen Korrektur von
Fehlern, Unzulänglichkeiten oder Prozessverletzungen
innerhalb der zu übergebenden Dateien einzusetzen, kann das
zu Problemen führen. Subversion hält bestimmte
Repository-Daten in clientseitigen Caches vor, und wenn Sie
auf diese Art eine Übergabe-Transaktion verändern, werden
die im Cache befindlichen Informationen ungültig, ohne dass
jemand etwas merkt. Diese Inkonsistenz kann zu
überraschendem und unerwartetem Verhalten führen. Statt die
Transaktion zu verändern, sollten Sie sie einfach im
pre-commit
-Hook auf
Gültigkeit prüfen und die Übergabe
ablehnen, falls sie den Anforderungen nicht entspricht. Als
Nebeneffekt werden Ihre Benutzer lernen, wie wertvoll eine
sorgfältige, sich an den Vorgaben orientierende Arbeitsweise
ist.
Eine Berkeley-DB-Umgebung ist eine Kapselung einer oder mehrerer Datenbanken, Protokolldateien, Regionsdateien und Konfigurationsdateien. Die Berkeley-DB-Umgebung hat ihre eigene Menge an Konfigurationswerten für Dinge wie die Maximalzahl von Datenbanksperren zu einem gegebenen Zeitpunkt, die Obergrenze für die Größe der Protokolldateien usw. Darüberhinaus wählt Subversions Dateisystemlogik Standardwerte für einige der Berkeley-DB-Konfigurationsoptionen. Manchmal jedoch benötigt Ihr besonderes Repository, welches eine einzigartige Sammlung von Daten und Zugriffsmustern darstellt, eine unterschiedliche Menge von Konfigurationswerten.
Den Herstellern von Berkeley-DB ist bewusst, dass
unterschiedliche Anwendungen und Datenbankumgebungen auch
unterschiedliche Anforderungen haben, so dass sie einen
Mechanismus zur Verfügung gestellt haben, der es ermöglicht,
während der Laufzeit viele der Konfigurationseinstellungen für
die Berkeley-DB-Umgebung zu überschreiben. BDB prüft, ob es
eine Datei namens DB_CONFIG
im
Umgebungsverzeichnis (das Verzeichnis db
des Repositorys) gibt und liest die in dieser Datei
vorhandenen Optionen. Subversion erzeugt diese Datei selbst,
wenn der Rest eines Repositorys erstellt wird. Anfangs
beinhaltet diese Datei einige Standardoptionen sowie Verweise
zur Berkeley-DB-Dokumentation im Netz, so dass Sie
nachschlagen können, was diese Optionen bewirken.
Selbstverständlich können Sie beliebige von Berkeley DB
unterstützte Optionen der Datei DB_CONFIG
hinzufügen. Beachten Sie jedoch, dass Sie es vermeiden
sollten, obwohl Subversion niemals versucht, den Inhalt der
Datei zu lesen oder zu interpretieren und auch sonst keinen
direkten Gebrauch von den dortigen Optionseinstellungen macht,
die Konfiguration so zu verändern, dass sich Berkeley DB
anders verhält, als es Subversion erwartet. Die Änderungen an
DB_CONFIG
werden außerdem erst nach einer
Wiederherstellung der Datenbankumgebung (mit svnadmin
recover) gültig.
Die Wartung eines Subversion-Repositorys kann abschreckend sein, was an der Komplexität liegt, die Systemen innewohnt, die auf Datenbanken aufbauen. Die Arbeit gut zu machen, bedeutet, die Werkzeuge zu kennen – was sie sind, wann sie zu verwenden sind und wie. Dieser Abschnitt stellt Ihnen die Repository-Verwaltungswerkzeuge vor, die Subversion mitbringt und erörtert, wie sie gehandhabt werden, um Aufgaben zu erledigen, wie etwa Repository-Datenmigration, Aktualisierungen, Sicherungen und Aufräumarbeiten.
Subversion stellt eine Handvoll Dienstprogramme zur Verfügung, die nützlich zum Erstellen, Untersuchen, Verändern und Reparieren Ihres Repositorys sind. Wir wollen uns diese Werkzeuge einmal genauer ansehen. Anschließend werden wir kurz einige der zum Berkeley-DB-Paket gehörenden Dienstprogramme untersuchen, die auf die Besonderheiten der von Subversion verwendeten Datenbank zugeschnittene Funktionen anbieten, die mit Subversions eigenen Werkzeugen nicht verfügbar sind.
Das Programm svnadmin ist der beste Freund des Repository-Administrators. Neben der Fähigkeit, Subversion-Repositorys zu erzeugen, erlaubt Ihnen dieses Programm verschiedene Wartungsarbeiten auf diesen Repositorys auszuführen. Die Syntax von svnadmin ist ähnlich wie bei anderen Kommandozeilenprogrammen von Subversion:
$ svnadmin help Aufruf: svnadmin UNTERBEFEHL ARCHIV_PFAD [Optionen & Parameter ...] Geben Sie »svnadmin help <Unterbefehl>« ein, um Hilfe zu einem Unterbefehl zu erhalten. Geben Sie »svnadmin --version« ein, um die Programmversion und die Datei- systemmodule zu sehen. Verfügbare Unterbefehle: crashtest create deltify …
Früher in diesem Kapitel (in „Anlegen des Repositorys“), wurde uns der Unterbefehl svnadmin create vorgestellt. Die meisten anderen Unterbefehle von svnadmin werden wir später in diesem Kapitel behandeln. Und in „svnadmin“ können Sie in einer vollständigen Aufstellung der Unterbefehle nachlesen, was jeder zu bieten hat.
svnlook ist ein von Subversion mitgeliefertes Dienstprogramm zum Untersuchen der mannigfaltigen Revisionen und Transaktionen (bei denen es sich um Revisionen in Entstehung handelt) in einem Repository. Kein Teil dieses Programms versucht, das Repository zu verändern. svnlook wird üblicherweise von Repository-Hooks verwendet, um die abzuliefernden Änderungen zu melden (im Fall des pre-commit-Hooks) oder die gerade an das Repository übergeben wurden (im Fall des post-commit-hooks). Ein Repository-Administrator kann dieses Programm zur Diagnose benutzen.
svnlook besitzt eine überschaubare Syntax:
$ svnlook help Aufruf: svnlook UNTERBEFEHL ARCHIV_PFAD [Optionen & Parameter ...] Hinweis: Alle Unterbefehle, die die Parameter »--revision« und »--transaction« akzeptieren, werden ohne diese Parameter die neueste Revision des Projektarchivs verwenden. Geben Sie »svnlook help <Unterbefehl>« ein, um Hilfe zu einem Unterbefehl zu erhalten. Geben Sie »svnlook --version« ein, um die Programmversion und die Datei- systemmodule zu sehen. …
Die meisten Unterbefehle von svnlook
können entweder auf einem Revisions- oder auf einem
Transaktionsbaum arbeiten, indem sie Informationen über den
Baum an sich ausgeben oder darüber, inwiefern er sich von
einer früheren Revision des Repositorys unterscheidet. Sie
verwenden die Optionen --revision
(-r
) und --transaction
(-t
), um die zu untersuchende Revision bzw.
Transaktion anzugeben. Ohne eine der Optionen
--revision
(-r
) und
--transaction
(-t
)
untersucht Subversion die jüngste (oder
HEAD
) Revision des Repositorys. Das
heißt, die beiden folgenden Befehle machen genau dasselbe,
wenn 19 die jüngste Revision im Repository unter
/var/svn/repos
ist:
$ svnlook info /var/svn/repos $ svnlook info /var/svn/repos -r 19
Eine Ausnahme von diesen Regeln zu Unterbefehlen ist der Unterbefehl svnlook youngest, der keine Optionen entgegennimmt und einfach die jüngste Revisionsnummer des Repositorys ausgibt:
$ svnlook youngest /var/svn/repos 19 $
Beachten Sie, dass Sie nur Transaktionen untersuchen
können, die noch nicht übergeben sind. Die meisten
Repositorys haben keine derartigen Transaktionen, da
Transaktionen entweder übergeben (in diesem Fall sollten
Sie darauf mit der Option --revision
(-r
) zugreifen) oder abgebrochen und
entfernt sind.
Die Ausgabe svnlook ist so gestaltet, dass sie sowohl für Menschen als auch für Maschinen lesbar ist. Nehmen wir zum Beispiel die Ausgabe des Unterbefehls svnlook info:
$ svnlook info /var/svn/repos sally 2002-11-04 09:29:13 -0600 (Mon, 04 Nov 2002) 43 Den üblichen griechischen Baum hinzugefügt. $
Die Ausgabe von svnlook info besteht aus dem Folgenden in entsprechender Reihenfolge:
Der Autor gefolgt von einem Zeilenvorschub
Das Datum gefolgt von einem Zeilenvorschub
Die Anzahl der Zeichen der Protokollnachricht gefolgt von einem Zeilenvorschub.
Die eigentliche Protokollnachricht gefolgt von einem Zeilenvorschub
Diese Ausgabe ist für Menschen lesbar, d.h., Dinge wie der Zeitstempel werden als Text dargestellt statt als irgendetwas Obskures (wie die Anzahl der Nanosekunden seit der Mann von Bofrost das letzte Mal da war). Jedoch ist die Ausgabe auch maschinenlesbar – weil die Protokollnachricht mehrere Zeilen umfassen und von der Länge her unbegrenzt sein kann, liefert svnlook die Länge der Nachricht vor der eigentlichen Nachricht. Das erlaubt Scripten und anderen Programmen, die um diesen Befehl herumgeschrieben wurden, intelligente Entscheidungen in Bezug auf die Protokollnachricht zu treffen, etwa wieviel Speicher für die Nachricht anzufordern ist oder zumindest wieviele Bytes zu überspringen sind, falls diese Ausgabe nicht das letzte Stück im Datenstrom sein sollte.
svnlook kann eine Auswahl anderer Abfragen ausführen: Teilmengen der bereits erwähnten Informationen ausgeben, versionierte Verzeichnisbäume rekursiv auflisten, berichten, welche Pfade in einer bestimmten Revision oder Transaktion verändert wurden, textuelle und property-basierte Unterschiede an Dateien und Verzeichnissen aufzeigen, usw. Siehe „svnlook“ für eine vollständige Referenz der Funktionen von svnlook.
Obwohl es nicht das am meisten verwendete Werkzeug im Sortiment des Administrators sein wird, bietet svndumpfilter eine ganz besondere Art von nützlichen Funktionen – die Fähigkeit, schnell und einfach Datenströme aus der Repository-Historie zu verändern, indem es als ein pfadbasierter Filter arbeitet.
Die Syntax von svndumpfilter lautet wie folgt:
$ svndumpfilter help Aufruf: svndumpfilter UNTERBEFEHL [Optionen & Parameter ...] Geben Sie »svndumpfilter help <Unterbefehl>« ein, um Hilfe zu einem Unterbefehl zu erhalten. Geben Sie »svndumpfilter --version« ein, um die Programmversion zu sehen. Verfügbare Unterbefehle: exclude include help (?, h)
Es gibt nur zwei interessante Unterbefehle: svndumpfilter exclude und svndumpfilter include. Sie erlauben Ihnen, zwischen einer impliziten oder expliziten Einbeziehung von Pfaden im Datenstrom zu wählen. Sie können mehr über diese Unterbefehle und den einzigartigen Zweck von svndumpfilter später in diesem Kapitel unter „Filtern der Repository-Historie“ erfahren.
Der Befehl svnsync, der in Subversion 1.4 neu hinzugekommen ist, bietet Funktionen zum Verwalten eines Nur-Lese-Spiegels des Subversion-Repositorys. Das Programm hat eine Aufgabe – die versionierte Historie eines Repositorys in ein anderes zu übertragen. Und während es nicht viele Möglichkeiten gibt, dies zu tun, liegt seine hauptsächliche Stärke darin, das es aus der Ferne eingesetzt werden kann – das „Quell“- und „Ziel“-Repository können auf verschiedenen Rechnern liegen und auf einem anderen Rechner als svnsync selbst.
Wie Sie vielleicht erwarten, hat svnsync eine Syntax, die allen anderen Programmen aus diesem Kapitel gleicht:
$ svnsync help Aufruf: svnsync UNTERBEFEHL ZIEL_URL [Optionen & Parameter ...] Geben Sie »svnsync help <Unterbefehl>« ein, um Hilfe zu einem Unterbefehl zu erhalten. Geben Sie »svnsync --version« ein, um die Programmversion und die Zugriffs- module zu sehen. Verfügbare Unterbefehle: initialize (init) synchronize (sync) copy-revprops help (?, h) $
Später in diesem Kapitel werden wir mehr über das Replizieren von Repositorys mit svnsync reden (siehe „Repository Replication“).
Obwohl es kein offizielles Glied in der Werkzeugkette
von Subversion ist, handelt es sich bei dem Script
fsfs-reshard.py (zu finden im Verzeichnis
tools/server-side
des
Subversion-Quelltext-Paketes) um ein nützliches Werkzeug zur
Leistungssteigerung für Administratoren von FSFS-basierten
Subversion-Repositorys. FSFS-Repositorys enthalten Dateien,
die die Änderungen in einer einzelnen Revision beschreiben
sowie Dateien, die die zu einer Revision gehörenden Eigenschaften
beinhalten. Repositorys, die in einer früheren Version als
Subversion 1.5 erzeugt wurden, legen diese Dateien in zwei
Verzeichnissen ab – eins pro Dateityp. Während neue
Revisionen an das Repository übergeben werden, legt
Subversion dort immer mehr Dateien ab – im Lauf der
Zeit kann die Anzahl der Dateien recht groß werden. Es wurde
festgestellt, dass dies bei bestimmten netzbasierten
Dateisystemen zu Leistungseinbußen kommen kann.
Subversion 1.5 legt FSFS-basierte Repositorys mit einer geringfügig veränderten Struktur an, in der der Inhalt dieser beiden Verzeichnisse aufgebrochen ist, d.h. über mehrere Unterverzeichnisse aufgeteilt ist. Das kann die Zeit erheblich beschleunigen, die benötigt wird, um eine dieser Dateien zu finden und führt somit zu einer allgemeinen Leistungssteigerung beim Lesen aus dem Repository. Die Anzahl der Unterverzeichnisse für diese Dateien ist jedoch konfigurierbar, und hier setzt fsfs-reshard.py an. Dieses Script mischt die Dateistruktur des Repositorys und ordnet sie gemäß der Anzahl der gewünschten Unterverzeichnisse neu an. Das ist inbesonders dann nützlich, wenn ein älteres Repository in die neue Struktur von Subversion 1.5 überführt werden soll (was Subversion nicht automatisch für Sie macht) oder falls ein bereits aufgeteiltes Repository noch feiner eingestellt werden soll.
Falls Sie ein Repository verwenden, das auf Berkeley DB
basiert, befindet sich die gesamte Struktur und die Daten
Ihres versionierten Dateisystems in einer Menge von
Datenbanktabellen innerhalb des Unterverzeichnisses
db/
Ihres Repositorys. Dieses
Unterverzeichnis ist ein gewöhnliches Verzeichnis einer
Berkeley-DB-Umgebung und kann deshalb mit irgendeinem der
Berkeley Datenbankwerkzeuge verwendet werden, die
normalerweise mit Berkeley DB ausgeliefert werden.
Für die tägliche Arbeit mit Subversion werden diese Werkzeuge nicht benötigt. Die meisten Funktionen, die üblicherweise für Subversion-Repositorys gebraucht werden, sind in svnadmin integriert worden. Beispielsweise liefern svnadmin list-unused-dblogs und svnadmin list-dblogs eine Teilmenge dessen, was vom Berkeley-Dienstprogramm db_archive angeboten wird, und svnadmin recover spiegelt die verbreiteten Anwendungsfälle von db_recover wieder.
Trotzdem gibt es noch ein paar Berkeley-DB-Werkzeuge, die Ihnen nützlich sein könnten. Die Programme db_dump und db_load schreiben bzw. lesen ein spezielles Dateiformat, das die Schlüssel und Werte in einer Berkeley-DB-Datenbank beschreibt. Da Berkeley-Datenbanken nicht zwischen Rechnerarchitekturen portierbar sind, stellt dieses Format ein nützliches Verfahren zur Übertragung der Datenbanken zwischen Maschinen zur Verfügung, wobei die Architektur oder das Betriebssystem keine Rolle spielen. Später in diesem Kapitel werden wir noch beschreiben, wie Sie auch svnadmin dump und svnadmin load für ähnliche Zwecke verwenden können, doch db_dump und db_load können bestimmte Aufgaben genausogut und viel schneller erledigen. Sie können auch dabei dienlich sein, wenn der erfahrene Berkeley-DB-Hacker aus irgendwelchen Gründen die Daten in einem BDB-basierten Repository direkt vor Ort anpassen muss, was die Dienstprogramme von Subversion nicht erlauben. Ferner liefert das Dienstprogramm db_stat nützliche Informationen über den Zustand Ihrer Berkeley-DB-Umgebung, wozu ausführliche Statistiken über das Sperr- und Speicher-Teilsystem gehören.
Besuchen Sie für weitergehende Informationen zur Berkeley-Werkzeugsammlung den Dokumentationsabschnitt der Berkeley-DB-Abteilung auf der Seite von Oracle bei http://www.oracle.com/technology/documentation/berkeley-db/db/.
Manchmal kommt es vor, dass ein Benutzer einen Fehler im
Protokolleintrag gemacht hat (einen Tippfehler oder vielleicht
eine Fehlinformation). Falls das Repository entsprechend
eingestellt ist (indem der Hook
pre-revprop-change
verwendet wird; siehe
„Erstellen von Repository-Hooks“), um Änderungen
am Protokolleintrag vorzunehmen nachdem die Übergabe
abgeschlossen ist, kann der Benutzer den Protokolleintrag aus
der Ferne mit dem Befehl svn propset (siehe
svn propset)
„berichtigen“. Wegen der Möglichkeit, dadurch
für immer Informationen zu verlieren, sind
Subversion-Repositorys allerdings standardmäßig nicht so
eingestellt, dass Änderungen an unversionierten Propertys
erlaubt sind – außer für einen Administrator.
Falls ein Protokolleintrag durch einen Administrator
geändert werden muss, kann das mit svnadmin
setlog geschehen. Dieser Befehl ändert den
Protokolleintrag (das Property svn:log
)
einer gegebenen Revision eines Repositorys, indem der neue
Inhalt aus einer angegebenen Datei gelesen wird.
$ echo "Hier ist der neue, korrekte Protokolleintrag" > newlog.txt $ svnadmin setlog myrepos newlog.txt -r 388
Auch der Befehl svnadmin setlog ist
standardmäßig durch dieselben Schutzmechanismen gegen die
Veränderung unversionierter Propertys eingeschränkt wie ein
Client aus der Ferne – die Hooks pre-
und post-revprop-change
werden immer noch
ausgelöst und müssen entsprechend eingestellt werden, um
solche Änderungen zuzulassen. Allerdings kann ein
Administrator diese Schutzmechanismen umgehen, indem er die
Option --bypass-hooks
an den Befehl
svnadmin setlog übergibt.
Denken Sie trotzdem daran, dass beim Umgehen der Hooks auch Dinge umgangen werden wie E-Mail-Benachrichtigungen bei Property-Änderungen, Sicherungssysteme, die Änderungen an unversionierten Propertys verfolgen, usw. Mit anderen Worten: Seien Sie sehr vorsichtig bei der Auswahl dessen, was Sie ändern und wie Sie es ändern.
Obwohl die Kosten für Speicherplatz in den letzten Jahren unglaublich gefallen sind, ist Plattenplatz immer noch ein berechtigtes Anliegen für Administratoren, die große Mengen von Daten zu versionieren haben. Jedes im aktiven Repository gespeicherte Bisschen Information über die Versionshistorie muss zu einem anderen Ort gesichert werden; vielleicht sogar öfter, falls eine zyklische Sicherungsstrategie angewendet wird. Es ist zweckdienlich zu wissen, welche Teile von Subversions Repository am Ort verbleiben müssen, welche gesichert werden müssen und welche ruhig entfernt werden können.
Um das Repository klein zu halten, verwendet Subversion innerhalb des Repositorys Delta-Kodierung (oder Deltaspeicherung). Unter Delta-Kodierung wird die Kodierung eines Datensatzes als eine Sammlung von Unterschieden gegenüber einem anderen Datensatz verstanden. Falls die beiden Datensätze sehr ähnlich sind, bewirkt diese Delta-Kodierung eine Einsparung an Speicherplatz für den als Delta gespeicherten Datensatz – anstatt den Platz der Originaldaten zu belegen, wird hierbei nur soviel Platz benötigt, um zu sagen: „Schau mal, ich sehe genau so aus, wie der andere Datensatz da drüben, bis auf die folgenden paar Änderungen.“ Das Ergebnis ist, dass die meisten der Daten im Repository, die normalerweise recht voluminös sind – nämlich der Inhalt versionierter Dateien – in einer viel geringeren Größe gespeichert werden als der ursprüngliche Volltext dieser Daten. Und für Repositorys, die mit Subversion 1.4 oder später angelegt wurden, ist die Platzersparnis sogar noch besser – jetzt sind die Volltexte der Dateiinhalte selbst komprimiert.
Da alle delta-kodierten Daten in einem BDB-basierten Repository in einer einzigen Berkeley-DB-Datenbankdatei gespeichert werden, wird die verringerte Größe der gespeicherten Werte nicht unmittelbar die Größe der Datenbankdatei verringern. Berkeley DB führt jedoch intern Buch über unbenutzte Bereiche der Datenbankdatei und wird zunächst jene aufbrauchen, bevor die Datenbankdatei selbst vergrößert wird. Während Delta-Kodierung also nicht unmittelbare Platzersparnis bringt, kann sie jedoch das künftige Wachstum der Datenbank drastisch verlangsamen.
Obwohl es selten vorkommt, gibt es Umstände, unter denen der Übergabeprozess mit einem Fehler abbricht und die Reste einer Revision in Spe hinterlässt – eine unvollendete Transaktion samt aller Datei- und Verzeichnisänderungen, die dazugehören. Dies kann aus verschiedenen Gründen passieren: Vielleicht wurde die Operation des Clients vom Benutzer unsauber beendet oder es trat mittendrin ein Netzfehler auf. Aus welchem Grund auch immer, es können unvollendete Transaktionen auftreten. Sie verursachen keine tatsächlichen Schäden, außer Plattenplatz zu verschwenden. Ein penibler Administrator möchte sie vielleicht dennoch entfernen.
Sie können den Befehl svnadmin lstxns verwenden, um die Namen der aktuell ausstehenden Transaktionen anzuzeigen:
$ svnadmin lstxns myrepos 19 3a1 a45 $
Jeder Eintrag der Ausgabe kann dann mit dem Befehl
svnlook (und seiner Option
--transaction
(-t
))
aufgerufen werden, um festzustellen, wer die Transaktion
erzeugt hat, wann sie erzeugt wurde und welche Änderungen
sie beinhaltet – Informationen, die bei der
Entscheidung helfen können, ob eine Transaktion ein sicherer
Kandidat zum Löschen ist! Wenn Sie tatsächlich eine
Transaktion löschen wollen, kann deren Name an den Befehl
svnadmin rmtxns übergeben werden, der
dann die Transaktion aufräumt. svnadmin
rmtxns kann seine Eingabe auch direkt aus der
Ausgabe von svnadmin lstxns
beziehen!
$ svnadmin rmtxns myrepos `svnadmin lstxns myrepos` $
Falls Sie auf diese Weise diese beiden Unterbefehle verwenden, sollten Sie vorübergehend das Repository für Clients unzugänglich machen. So kann niemand eine berechtigte Transaktion beginnen, bevor Sie aufgeräumt haben. Beispiel 5.1, „txn-info.sh (ausstehende Transaktionen anzeigen)“ enthält ein kleines Shell-Script, das schnell eine Übersicht über jede ausstehende Transaktion in Ihrem Repository erzeugen kann.
Beispiel 5.1. txn-info.sh (ausstehende Transaktionen anzeigen)
#!/bin/sh ### Erzeuge Informationen über alle ausstehenden Transaktionen eines ### Subversion Repositorys. REPOS="${1}" if [ "x$REPOS" = x ] ; then echo "Aufruf: $0 REPOS_PATH" exit fi for TXN in `svnadmin lstxns ${REPOS}`; do echo "---[ Transaktion ${TXN} ]-------------------------------------------" svnlook info "${REPOS}" -t "${TXN}" done
Die Ausgabe des Scriptes ist im Grunde genommen eine Aneinanderreihung mehrerer Teile von svnlook info-Ausgaben (siehe „svnlook“) und sieht etwa so aus:
$ txn-info.sh myrepos ---[ Transaktion 19 ]------------------------------------------- sally 2001-09-04 11:57:19 -0500 (Tue, 04 Sep 2001) 0 ---[ Transaktion 3a1 ]------------------------------------------- harry 2001-09-10 16:50:30 -0500 (Mon, 10 Sep 2001) 39 Versuch, über eine schlechte Netzverbindung abzuliefern. ---[ Transaktion a45 ]------------------------------------------- sally 2001-09-12 11:09:28 -0500 (Wed, 12 Sep 2001) 0 $
Eine vor langer Zeit aufgegebene Transaktion bedeutet normalerweise eine Art fehlgeschlagenen oder unterbrochenen Übergabeversuch. Der Zeitstempel einer Transaktion kann eine interessante Information sein – ist es beispielsweise wahrscheinlich, dass eine vor neun Monaten begonnene Operation immer noch aktiv ist?
Kurz gesagt, Entscheidungen zur Bereinigung von Transaktionen sollten klug getroffen werden. Verschiedene Informationsquellen – hierzu gehören die Fehler- und Zugriffsprotokolldateien von Apache, die operativen Protokolldateien von Subversion, die Revisions-Historie von Subversion usw. – können während des Entscheidungsprozesses hinzugezogen werden. Natürlich kann sich ein Administrator auch einfach mit dem Eigentümer einer anscheinend abgebrochenen Transaktion in Verbindung setzen (z.B. per E-Mail), um sicherzustellen, dass die Transaktion sich tatsächlich in einem Zombiezustand befindet.
Bis vor kurzer Zeit waren die größten Plattenplatzfresser bei BDB-basierten Subversion-Repositorys die Protokolldateien, in die Berkeley DB zunächst alle Schritte hineinschreibt, bevor es die eigentlichen Datenbankdateien verändert. Diese Dateien halten alle Aktionen der Datenbank auf dem Weg von einem Zustand zum nächsten fest – während die Datenbankdateien zu jeder Zeit einen bestimmten Zustand widerspiegeln, beinhalten die Protokolldateien all die vielen Änderungen auf dem Weg zwischen den Zuständen. Somit können sie sehr schnell wachsen und sich anhäufen.
Glücklicherweise hat die Datenbankumgebung beginnend mit
der Version 4.2 der Berkeley DB die Fähigkeit, ihre eigenen
unbenutzten Protokolldateien automatisch zu entfernen. Alle
Repositorys, die mit einem svnadmin
angelegt wurden, das mit Berkeley DB Version 4.2 oder später
übersetzt wurde, werden mit automatischer
Protokolldateientfernung konfiguriert. Wenn Sie diese
Funktion nicht möchten, geben Sie dem Befehl
svnadmin create einfach die Option
--bdb-log-keep
mit. Sollten Sie das
vergessen oder es sich später anders überlegen, editieren
Sie einfach die Datei DB_CONFIG
im
Verzeichnis db
Ihres Repositorys indem
Sie die Zeile mit der Direktive set_flags
DB_LOG_AUTOREMOVE
auskommentieren und starten dann
svnadmin recover auf Ihrem Repository, um
die Konfigurationsänderung zu aktivieren. Siehe „Konfiguration von Berkeley DB“ für weitere
Informationen zur Datenbankkonfiguration.
Ohne eine Art automatische Protokolldateientfernung aktiviert zu haben, häufen sich die Protokolldateien während der Nutzung des Repositorys an. Es ist eigentlich ein Merkmal des Datenbanksystems – Sie sollten ausschließlich mit Hilfe der Protokolldateien in der Lage sein, Ihre gesamte Datenbank zu rekonstruieren, so dass diese Protokolldateien sehr nützlich für eine Wiederherstellung im Katastrophenfall sein können. Jedoch möchten Sie normalerweise die nicht mehr von Berkeley DB verwendeten Protokolldateien archivieren und sie zur Platzersparnis von der Platte entfernen. Verwenden Sie den Befehl svnadmin list-unused-dblogs, um die unbenutzten Protokolldateien anzuzeigen:
$ svnadmin list-unused-dblogs /var/svn/repos /var/svn/repos/log.0000000031 /var/svn/repos/log.0000000032 /var/svn/repos/log.0000000033 … $ rm `svnadmin list-unused-dblogs /var/svn/repos` ## Plattenplatz zurückgewonnen!
BDB-basierte Repositorys, deren Protokolldateien ein Bestandteil eines Sicherungs- oder Notfallplans sind, sollten nicht die automatische Entfernung verwenden. Die Wiederherstellung der Daten eines Repositorys kann nur gewährleistet werden, wenn alle Protokolldateien verfügbar sind. Falls einige der Protokolldateien von der Platte entfernt werden, bevor das Sicherungssystem die Gelegenheit bekommt, sie woandershin zu kopieren, ist die unvollständige Menge gesicherter Protokolldateien tatsächlich nutzlos.
Wie in „Berkeley DB“ erwähnt wurde, kann ein Berkeley-DB-Repository manchmal einfrieren, falls es nicht ordnungsgemäß geschlossen wird. Wenn das passiert, muss ein Administrator die Datenbank in einen konsistenten Zustand zurückfahren. Das gilt aber nur für BDB-basierte Repositorys – falls Sie FSFS-basierte verwenden, sind Sie davon nicht betroffen. Und falls Sie Subversion 1.4 mit Berkeley DB 4.4 oder später verwenden, werden Sie feststellen, dass Subversion für diese Situationen wesentlich unempfindlicher geworden ist. Trotzdem kommt es vor, dass sich Berkeley-DB-Repositorys verklemmen, und Administratoren müssen wissen, wie sie sicher damit umgehen.
Um die Daten in Ihrem Repository zu schützen, verwendet Berkeley DB einen Sperrmechanismus. Dieser Mechanismus stellt sicher, dass Teile der Datenbank nicht gleichzeitig durch mehrere Zugriffe verändert werden und jeder Prozess die Daten beim Lesen aus der Datenbank im korrekten Zustand sieht. Wenn ein Prozess irgendetwas in der Datenbank ändern muss, prüft er zunächst, ob eine Sperre auf den Zieldaten liegt. Sind die Daten nicht gesperrt, sperrt der Prozess die Daten, nimmt die Änderungen vor und entsperrt die Daten wieder. Andere Prozesse müssen auf die Freigabe der Sperre warten, bevor sie wieder auf diesen Datenbankabschnitt zugreifen dürfen. (Das hat nichts mit den Sperren zu tun, die Sie als Benutzer auf versionierte Dateien im Repository vergeben können; wir versuchen die Verwirrung, die durch diese Terminologie verursacht wird, in The Three Meanings of „Lock“ zu klären.)
Während der Nutzung Ihres Repositorys können fatale Fehler oder Unterbrechungen einen Prozess daran hindern, die von ihm in der Datenbank gesetzten Sperren wieder zu entfernen. Als Ergebnis ist das Datenbanksystem „verklemmt“. Wenn das passiert, laufen alle Versuche ins Leere, auf die Datenbank zuzugreifen (da jeder neue Prozess darauf wartet, dass die Sperre entfernt wird – was aber nicht passieren wird).
Keine Panik, falls das Ihrem Repository widerfahren sollte! Das Berkeley-DB-Dateisystem nutzt die Vorteile von Datenbanktransaktionen, Sicherungspunkten sowie vorausschreibender Journalierung, um zu gewährleisten, dass nur die katastrophalsten Ereignisse [32] dauerhaft die Datenbankumgebung zerstören können. Ein ausreichend paranoider Repository-Administrator wird irgendwie Sicherungen der Daten des Repositorys an einem anderen Ort verwahren, doch rennen Sie noch nicht zum Schrank mit den Sicherungsbändern.
Verwenden Sie stattdessen das folgende Rezept, um Ihr Repositorys zu „entklemmen“:
Stellen Sie sicher, dass keine Prozesse auf das Repository zugreifen (oder einen Zugriffsversuch machen). Für netzbasierte Repositorys bedeutet das, auch den Apache-HTTP-Server oder den svnserve-Dämon zu stoppen.
Melden Sie sich als der Benutzer an, dem das Repository gehört und der es verwaltet. Das ist wichtig, da eine Wiederherstellung unter einer falschen Benutzerkennung dazu führen kann, dass die Berechtigungen auf den Dateien eines Repositorys derart verändert werden können, dass der Zugriff auf das Repository auch dann nicht mehr möglich wird, wenn es „entklemmt“ ist.
Starten Sie den Befehl svnadmin recover
/var/svn/repos
. Sie sollten eine Ausgabe
ähnlich dieser sehen:
Exklusiven Zugriff auf das Projektarchiv erlangt Bitte warten, die Wiederherstellung des Projektarchivs kann einige Zeit dauern ... Wiederherstellung vollständig abgeschlossen. Die neueste Revision des Projektarchivs ist 19.
Die Ausführung dieses Befehls kann viele Minuten dauern.
Machen Sie einen Neustart des Server-Prozesses.
Dieses Vorgehen behebt fast jeden Fall von
Repository-Verklemmung. Stellen Sie sicher, dass Sie diesen
Befehl als der Benutzer ausführen, der Eigentümer und
Verwalter der Datenbank ist, nicht einfach als
root
. Ein Teil des
Wiederherstellungsprozesses könnte diverse Datenbankdateien
völlig neu erzeugen (z.B. gemeinsame Speicherbereiche). Wenn
Sie die Wiederherstellung als root
ausführen, werden diese Dateien dem Benutzer
root
zugeordnet, was bedeutet, dass selbst
nach der Wiederherstellung der Verbindung zur Außenwelt
gewöhnliche Benutzer keinen Zugriff mehr bekommen
werden.
Falls das oben beschriebene Vorgehen aus irgendwelchen
Gründen die Verklemmung Ihres Repository nicht beseitigt,
sollten Sie zwei Dinge tun. Schieben Sie zunächst ihr
beschädigtes Repository an die Seite (indem Sie es etwa in
repos.BROKEN
umbenennen) und spielen
seine jüngste Sicherung ein. Schicken Sie dann eine E-Mail an
die Subversion-Mailing-Liste
(<users@subversion.tigris.org>
), in der Sie Ihr
Problem detailliert beschreiben. Die Integrität der Daten
genießt bei den Entwicklern von Subversion allerhöchste
Priorität.
Ein Subversion-Dateisystem hält seine Daten in Dateien, die auf eine Art und Weise über das Repository verstreut sind, die im Allgemeinen nur die Subversion-Entwickler selbst verstehen (und auch nur sie interessieren). Allerdings können es bestimmte Umstände erforderlich machen, alle Daten oder nur Teile davon in ein anderes Repository zu kopieren oder zu verschieben.
Subversion stellt solche Funktionen durch Repository-Auszugs-Datenströme (repository dump streams) bereit. Ein Repository-Auszugs-Datenstrom (oft als „Auszugsdatei“ bezeichnet, wenn er als Datei auf Platte gespeichert wird) ist ein portables, flaches Dateiformat, das die zahlreichen Revisionen in Ihrem Repository beschreibt – was geändert wurde, von wem usw. Dieser Datenstrom ist der primäre Mechanismus zum Herumschieben der versionierten Historie – als Ganzes oder in Teilen, mit oder ohne Änderung – zwischen Repositorys. Und Subversion stellt die Werkzeuge zum Erzeugen und Laden dieser Datenströme zur Verfügung: die Unterbefehle svnadmin dump bzw. svnadmin load.
Obwohl das Format der Subversion Auszugsströme menschenlesbare Teile enthält und das Format eine gewohnte Struktur besitzt (es gleicht einem RFC 822 Format, das meistens für E-Mail verwendet wird), ist es kein reines Textformat. Es ist ein Binärformat, das sehr empfindlich gegenüber Herumgepfusche ist. Beispielsweise würden viele Texteditoren die Datei beschädigen, indem sie automatisch die Zeilenenden umformen.
Es gibt viele Gründe, Auszüge von Subversion-Repository-Daten zu machen und zu laden. In der Anfangsphase von Subversion war der häufigste Grund die Weiterentwicklung von Subversion an sich. Während Subversion reifte, gab es Zeiten, als Änderungen an der Datenbankbasis zu Kompatibilitätsproblemen mit früheren Repository-Versionen führten, so dass Benutzer mit der vorherigen Version von Subversion Auszüge von ihren Repository-Daten machen und sie mit der neueren Version von Subversion in ein frisch erzeugtes Repository laden mussten. Diese Schemaänderungen haben seit Subversion 1.0 nicht mehr stattgefunden, und die Subversion-Entwickler versprechen, dass die Benutzer zwischen Unterversionen von Subversion (wie etwa von 1.3 nach 1.4) keine Abzüge ihrer Repositorys machen und neu laden müssen. Jedoch gibt es noch andere Gründe, die es erforderlich machen, zu denen Dinge gehören wie das erneute Aufsetzen eines Berkeley-DB-Repositorys auf einem neuen Betriebssystem oder einer CPU-Architektur, der Wechsel von einem Berkeley-DB-basierten auf ein FSFS-basiertes Repository oder (was wir später in diesem Kapitel in „Filtern der Repository-Historie“ behandeln werden) das Entfernen versionierter Daten aus der Repository-Historie.
Das Auszugsformat eines Subversion Repositorys beschreibt nur versionierte Änderungen. Es beinhaltet keine Informationen über unvollendete Transaktionen, von Benutzern gesetzte Sperren auf Pfade im Repository, Anpassungen an Repository- oder Server-Konfigurationen (inklusive Hook-Scripten) usw.
Welche Gründe für den Umzug der Repository-Historie für Sie auch immer eine Rolle spielen, die Verwendung der Unterbefehle svnadmin dump und svnadmin load sind der direkte Weg. svnadmin dump gibt ein Intervall von Repository-Revisionen im speziellen Subversion-Auszugsformat aus. Der Auszug wird zur Standardausgabe geschrieben, während Mitteilungen an die Standardfehlerausgabe gehen. Das erlaubt Ihnen, den Ausgabestrom in eine Datei umzuleiten, während Sie Statusausgaben im Terminalfenster verfolgen können. Zum Beispiel:
$ svnlook youngest myrepos 26 $ svnadmin dump myrepos > dumpfile * Revision 0 ausgegeben. * Revision 1 ausgegeben. * Revision 2 ausgegeben. … * Revision 25 ausgegeben. * Revision 26 ausgegeben.
Am Ende haben Sie eine einzelne Datei (im vorangegangenen
Beispiel dumpfile
), die alle im
Repository gespeicherten Daten aus dem gewählten Intervall von
Revisionen beinhaltet. Beachten Sie, dass svnadmin
dump wie jeder andere „lesende“ Prozess
(z.B. svn checkout) Revisionsbäume aus dem
Repository liest, so dass Sie diesen Befehl jederzeit aufrufen
können.
Der andere Unterbefehl dieses Paars, svnadmin load, liest den Standardeingabestrom als eine Subversion-Repository-Auszugsdatei und spielt diese Revisionen aus dem Auszug gewissermaßen neu in das Ziel-Repository. Auch dieser Befehl erzeugt Meldungen, dieses Mal aber über die Standardausgabe:
$ svnadmin load newrepos < dumpfile <<< Neue Transaktion basierend auf Originalrevision 1 gestartet * Füge Pfad hinzu: A ... erledigt. * Füge Pfad hinzu: A/B ... erledigt. … ------- Neue Revision 1 übertragen (geladen aus Original 1) >>> <<< Neue Transaktion basierend auf Originalrevision 2 gestartet * Bearbeite Pfad: A/mu ... erledigt. * Bearbeite Pfad: A/D/G/rho ... erledigt. ------- Neue Revision 2 übertragen (geladen aus Original 2) >>> … <<< Neue Transaktion basierend auf Originalrevision 25 gestartet * Bearbeite Pfad: A/D/gamma ... erledigt. ------- Neue Revision 25 übertragen (geladen aus Original 25) >>> <<< Neue Transaktion basierend auf Originalrevision 26 gestartet * Füge Pfad hinzu: A/Z/zeta ... erledigt. * Bearbeite Pfad: A/mu ... erledigt. ------- Neue Revision 26 übertragen (geladen aus Original 26) >>>
Das Ergebnis eines Ladevorgangs sind neue Revisionen, die
dem Repository hinzugefügt wurden – dasselbe, was Sie
erhalten, wenn Sie mit einem normalen Subversion-Client
Übergaben an das Repository machen. Ebenso wie bei einer
Übergabe können können Sie Hook-Programme verwenden, um
Aktionen vor und nach jeder Übergabe während des Ladevorgangs
auszuführen. Indem Sie die Optionen
--use-pre-commit-hook
und
--use-post-commit-hook
an svnadmin
load übergeben, können Sie Subversion befehlen, für
jede zu ladende Revision die Hook-Programme pre-commit bzw.
post-commit auszuführen. Sie könnten diese beispielsweise
verwenden, um sicherzustellen, dass die geladenen Revisionen
dieselben Validierungsschritte durchlaufen müssen wie reguläre
Übergaben. Natürlich sollten Sie diese Optionen mit Sorgfalt
verwenden – wenn Ihr post-commit-Hook für jede neue
Übergabe E-Mails an eine Mailing-Liste verschickt, wollen Sie
bestimmt nicht, das innerhalb kürzester Zeit hunderte oder
tausende Übergabe-E-Mails in diese Liste hineinhageln! Sie
können mehr über Hook-Scripte in „Erstellen von Repository-Hooks“ lesen.
Beachten Sie, dass Menschen, die sich besonders gewitzt fühlen, weil svnadmin für den Auszug und den Ladevorgang den Standardeingabe- und den Standardausgabestrom benutzt, Dinge wie dieses ausprobieren können (vielleicht sogar unterschiedliche Versionen von svnadmin auf jeder Seite der Pipe):
$ svnadmin create newrepos $ svnadmin dump oldrepos | svnadmin load newrepos
Im Normalfall wird die Auszugsdatei ziemlich groß –
viel größer als das Repository selbst. Das liegt daran, dass
standardmäßig jede Version jeder Datei als vollständiger Text
in der Auszugsdatei dargestellt wird. Dies ist das schnellste
und einfachste Verhalten, und es ist nett, wenn Sie die
Auszugsdaten über eine Pipe direkt an einen weiteren Prozess
weiterleiten (etwa ein Komprimierprogramm, ein Filterprogramm
oder einen Prozess zum Laden). Wenn Sie jedoch eine
Auszugsdatei für die Langzeitspeicherung erzeugen, möchten Sie
wahrscheinlich Plattenplatz sparen, indem Sie die Option
--deltas
verwenden. Mit dieser Option werden
aufeinanderfolgende Revisionen von Dateien als komprimierte
binäre Unterschiede ausgegeben – so wie Dateirevisionen
im Repository gespeichert werden. Diese Option ist langsamer,
führt jedoch zu einer Größe der Auszugsdatei, die der Größe
des Original-Repositorys näher kommt.
Wir haben eben erwähnt, dass svnadmin
dump einen Bereich von Revisionen ausgibt. Verwenden
Sie die Option --revision
(-r
), um eine einzelne Revision oder einen
Bereich von Revisionen für den Auszug anzugeben. Wenn Sie
diese Option weglassen, wird ein Auszug aller
Repository-Revisionen erstellt.
$ svnadmin dump myrepos -r 23 > rev-23.dumpfile $ svnadmin dump myrepos -r 100:200 > revs-100-200.dumpfile
Beim Erstellen eines Auszugs jeder Revision gibt Subversion gerade soviel Information aus, dass später ein Ladeprozess in der Lage ist, diese Revision auf der Basis der Vorgängerrevision wiederherzustellen. Mit anderen Worten: Für jede Revision befinden sich nur die Dinge in der Auszugsdatei, die sich in dieser Revision geändert haben. Die einzige Ausnahme von dieser Regel ist die erste Revision, die mit dem aktuellen svnadmin dump erstellt wird.
Standardmäßig wird Subversion den Auszug der ersten Revision nicht bloß als Unterschied ausdrücken, der auf die Vorgängerrevision anzuwenden ist. Zum Ersten gibt es keine Vorgängerrevision in der Auszugsdatei. Und zum Zweiten kann Subversion den Zustand des Repositorys, in das der Auszug (falls überhaupt) geladen werden soll, nicht kennen. Um sicherzustellen, dass die Ausgabe jedes Aufrufs von svnadmin dump unabhängig ist, ist der Auszug der ersten Revision standardmäßig eine vollständige Darstellung jedes Verzeichnisses, jeder Datei und jedes Propertys aus dieser Revision im Repository.
Sie können dieses Standardverhalten jedoch ändern. Falls
Sie die Option --incremental
angeben,
vergleicht svnadmin die erste Revision für
die ein Auszug erstellt werden soll mit der vorhergehenden
Revision im Repository – auf dieselbe Art und Weise, wie
jede andere Revision behandelt wird, für die ein Auszug
erstellt werden soll – indem lediglich die Änderungen
aus dieser Revision erwähnt werden. Der Vorteil dabei ist,
dass Sie mehrere kleinere Auszugsdateien erstellen können, die
hintereinander geladen werden können, anstatt eine
große:
$ svnadmin dump myrepos -r 0:1000 > dumpfile1 $ svnadmin dump myrepos -r 1001:2000 --incremental > dumpfile2 $ svnadmin dump myrepos -r 2001:3000 --incremental > dumpfile3
Diese Auszugsdateien können mit der folgenden Befehlsfolge in ein neues Repository geladen werden:
$ svnadmin load newrepos < dumpfile1 $ svnadmin load newrepos < dumpfile2 $ svnadmin load newrepos < dumpfile3
Ein weiterer toller Trick, den Sie mit der Option
--incremental
anwenden können besteht darin,
einen neuen Bereich von Revisionsauszügen an eine existierende
Revisionsdatei anzuhängen. Beispielsweise könnten Sie einen
post-commit
-Hook haben, der der Datei einen
Auszug derjenigen Revision anfügt, die den Hook ausgelöst hat.
Oder Sie haben ein Script, das jede Nacht läuft, um Auszüge
sämtlicher Revisionen seit dem letzten Lauf anzufügen. Wenn es
auf diese Weise verwendet wird, stellt svnadmin
dump eine Möglichkeit dar, laufend die Änderungen an
Ihrem Repository für den Fall eines Systemabsturzes oder eines
anderen katastrophalen Ereignisses zu sichern.
Das Auszugsformat kann auch dazu verwendet werden, um die
Inhalte mehrerer verschiedener Repositorys in ein Repository
zusammenzuführen. Indem Sie die Option
--parent-dir
von svnadmin
load benutzen, können Sie ein neues virtuelles
Wurzelverzeichnis für den Ladevorgang angeben. Das heißt,
falls Sie beispielsweise die Auszugsdateien von drei
Repositorys haben – etwa
calc-dumpfile
,
cal-dumpfile
und
ss-dumpfile
– können Sie zunächst
ein Repository anlegen, das alle beherbergt:
$ svnadmin create /var/svn/projects $
Erstellen Sie dann neue Verzeichnisse im Repository, die den Inhalt der vorherigen drei Repositorys aufnehmen werden:
$ svn mkdir -m "Initial project roots" \ file:///var/svn/projects/calc \ file:///var/svn/projects/calendar \ file:///var/svn/projects/spreadsheet Revision 1 übertragen. $
Laden Sie schließlich die Auszugsdateien an ihren jeweiligen Ort im neuen Repository:
$ svnadmin load /var/svn/projects --parent-dir calc < calc-dumpfile … $ svnadmin load /var/svn/projects --parent-dir calendar < cal-dumpfile … $ svnadmin load /var/svn/projects --parent-dir spreadsheet < ss-dumpfile … $
Zum Schluss erwähnen wir noch einen Anwendungsfall für das Auszugsformat – die Umwandlung aus einem unterschiedlichen Speicherverfahren oder gar aus einem unterschiedlichen Versionskontrollsystem. Da das Format der Auszugsdatei größtenteils menschenlesbar ist, sollte es einfach sein, gewöhnliche Änderungsmengen – von denen jede als Revision behandelt werden sollte – mit diesem Format zu beschreiben. Tatsächlich verwendet das Dienstprogramm cvs2svn (siehe „Converting a Repository from CVS to Subversion“) dieses Auszugsformat, um den Inhalt eines CVS-Repositorys darzustellen, so dass er in ein Subversion-Repository kopiert werden kann.
Da Subversion Ihre versionierte Historie mindestens mit binären Differenzalgorithmen und Datenkompression abspeichert (optional in einem völlig undurchsichtigen Datenbanksystem), ist der Versuch manueller Eingiffe unklug, zumindest schwierig und unter allen Umständen nicht angeraten. Sobald Daten im Repository gespeichert sind, bietet Subversion im Allgemeinen keine einfache Möglichkeit, diese Daten zu entfernen. [33] Doch zwangsläufig werden sich Gelegenheiten ergeben, bei denen Sie die Historie Ihres Repositorys manipulieren müssen. Es könnte sein, dass Sie alle Instanzen einer Datei entfernen müssen, die versehentlich dem Repository hinzugefügt worden ist, aber aus welchen Gründen auch immer nicht hineingehört). [34] Oder Sie haben vielleicht mehrere Projekte, die sich ein Repository teilen und entscheiden sich nun, jedem Projekt sein eigenes Repository zu geben. Um Aufgaben wie diese bewerkstelligen zu können, benötigen Administratoren eine besser handhabbare und bearbeitbare Repräsentation der Daten in den Repositorys – das Subversion-Repository-Auszugsformat.
Wie bereits in „Repository-Daten woandershin verschieben“ beschrieben, ist das Subversion-Repository-Auszugsformat eine menschenlesbare Wiedergabe der Änderungen, die Sie an Ihren versionierten Daten im Laufe der Zeit vorgenommen haben. Verwenden Sie den Befehl svnadmin dump, um den Auszug anzulegen und svnadmin load, um ein neues Repository damit zu füllen. Das Tolle an der Menschenlesbarkeit des Auszugsformates ist, dass Sie, sofern es Ihnen nicht egal ist, die Daten manuell untersuchen und verändern können. Natürlich besteht ein Nachteil darin, dass eine Auszugsdatei eines Repositorys, in das über drei Jahre Änderungen eingeflossen sind, riesig groß sein wird, und es Sie eine lange, lange Zeit kosten wird, die Daten manuell zu untersuchen und zu verändern.
Hierbei hilft svndumpfilter. Dieses Programm verhält sich wie ein pfadbasierter Filter für Auszugsströme. Geben Sie ihm einfach eine Liste von Pfaden mit, die Sie behalten möchten oder eine Liste von Pfaden, die Sie nicht behalten möchten, und leiten Sie Ihre Auszugsdaten durch diesen Filter. Das Ergebnis ist ein modifizierter Strom der Auszugsdaten, der nur die versionierten Pfade beinhaltet, die Sie (explizit oder implizit) verlangt haben.
Lassen Sie uns an einem realistischen Beispiel betrachten, wie Sie diesen Programm verwenden könnten. Früher in diesem Kapitel (siehe „Planung der Organisation Ihres Repositorys“) erörterten wir das Entscheidungsfindungsverfahren, wie Sie Ihre Daten im Repository anordnen sollen – ein Repository pro Projekt oder kombiniert, wie Sie die Daten im Repository verteilen usw. Doch manchmal, nachdem bereits einige Revisionen hinzugekommen sind, überdenken Sie die Anordnung und würden gerne einige Änderungen vornehmen. Eine verbreitete Änderung ist die Entscheidung, mehrere Projekte, die sich ein Repository teilen, auf getrennte Repositorys pro Projekt aufzuteilen.
Unser imaginäres Repository beinhaltet drei Projekte:
calc
, calendar
und
spreadsheet
. Sie waren miteinander in der
folgenden Anordnung abgelegt:
/ calc/ trunk/ branches/ tags/ calendar/ trunk/ branches/ tags/ spreadsheet/ trunk/ branches/ tags/
Um diese drei Projekte in ihre eigenen Repositorys zu bekommen, erstellen wir zunächst einen Auszug des gesamten Repositorys:
$ svnadmin dump /var/svn/repos > repos-dumpfile * Revision 0 ausgegeben. * Revision 1 ausgegeben. * Revision 2 ausgegeben. * Revision 3 ausgegeben. … $
Dann leiten wir die Auszugsdatei durch die Filter, wobei jedesmal nur jeweils eins der obersten Verzeichnisse ausgewählt wird. Als Ergebnis erhalten wir drei Auszugsdateien:
$ svndumpfilter include calc < repos-dumpfile > calc-dumpfile … $ svndumpfilter include calendar < repos-dumpfile > cal-dumpfile … $ svndumpfilter include spreadsheet < repos-dumpfile > ss-dumpfile … $
An dieser Stelle müssen sie eine Entscheidung treffen.
Jede Ihrer Auszugsdateien wird ein gültiges Repository
erzeugen, allerdings unter Beibehaltung der Pfade wie sie im
ursprünglichen Repository waren. Das bedeutet, dass, obwohl
Sie ein Repository ausschließlich für Ihr
calc
Projekt haben, wird es immer noch ein
Wurzelverzeichnis namens calc
besitzen.
Falls Sie möchten, dass die Verzeichnisse
trunk
, tags
und
branches
direkt im Wurzelverzeichnis
Ihres Repositorys liegen, sollten Sie Ihre Auszugsdateien
editieren, indem Sie die Einträge Node-path
und Node-copyfrom-path
verändern, so dass
sie nicht mehr die erste Komponente calc/
im Pfad haben. Sie sollten auch den Abschnitt entfernen, der
das Verzeichnis calc
anlegt. Es sollte
etwa wie folgt aussehen:
Node-path: calc Node-action: add Node-kind: dir Content-length: 0
Falls Sie sich entscheiden sollten, die Auszugsdatei
manuell zu editieren, um eins der obersten Verzeichnisse zu
entfernen, sollten Sie sicherstellen, dass Ihr Editor nicht
automatisch Zeilenenden in das native Format umwandelt (z.B.
\r\n
in \n
), da sonst
der Inhalt nicht zu den Metadaten passt. Das würde Ihre
Auszugsdatei nutzlos machen.
Alles, was jetzt noch übrig bleibt, ist, Ihre drei neuen Repositorys zu erstellen und jede Auszugsdatei in das richtige Repository zu laden, wobei die UUID aus dem Auszugsstrom ignoriert wird:
$ svnadmin create calc $ svnadmin load --ignore-uuid calc < calc-dumpfile <<< Neue Transaktion basierend auf Originalrevision 1 gestartet * Füge Pfad hinzu: Makefile ... erledigt. * Füge Pfad hinzu: button.c ... erledigt. … $ svnadmin create calendar $ svnadmin load --ignore-uuid calendar < cal-dumpfile <<< Neue Transaktion basierend auf Originalrevision 1 gestartet * Füge Pfad hinzu: Makefile ... erledigt. * Füge Pfad hinzu: cal.c ... erledigt. … $ svnadmin create spreadsheet $ svnadmin load --ignore-uuid spreadsheet < ss-dumpfile <<< Neue Transaktion basierend auf Originalrevision 1 gestartet * Füge Pfad hinzu: Makefile ... erledigt. * Füge Pfad hinzu: ss.c ... erledigt. … $
Beide Unterbefehle von svndumpfilter akzeptieren Optionen, die angeben, wie „leere“ Revisionen behandelt werden sollen. Falls eine Revision nur Änderungen an herausgefilterten Pfaden beinhaltet, könnte die neue Revision als uninteressant oder gar unerwünscht gelten. Um dem Benutzer die Kontrolle darüber zu geben, wie hiermit verfahren werden soll, bietet svndumpfilter die folgenden Kommandozeilenoptionen:
--drop-empty-revs
Überhaupt keine leeren Revisionen erzeugen – einfach auslassen.
--renumber-revs
Falls leere Revisionen ausgelassen werden (mit der
Option --drop-empty-revs
), die
Nummern der übrig gebliebenen Revisionen ändern, so dass
keine Lücken in der Nummernfolge auftreten.
--preserve-revprops
Falls leere Revisionen nicht ausgelassen werden, die Eigenschaften der leeren Revisionen bewahren (Protokolleintrag, Autor, Datum, Propertys usw.). Sonst beinhalten leere Revisionen lediglich den Zeitstempel und einen erzeugten Protokolleintrag, der darauf hinweist, dass diese Revision von svndumpfilter geleert wurde.
Obwohl svndumpfilter sehr nützlich und
eine Zeitersparnis sein kann, gibt es unglücklicherweise ein
paar Fallstricke. Erstens ist das Dienstprogramm
überempfindlich gegenüber der Pfadsemantik. Achten Sie darauf,
ob die Pfade in Ihrer Auszugsdatei mit oder ohne führende
Schrägstriche angegeben werden. Sie sollten sich die Einträge
Node-path
und
Node-copyfrom-path
ansehen.
… Node-path: spreadsheet/Makefile …
Falls die Pfade führende Schrägstriche haben, sollten auch Sie Schrägstriche in den Pfaden angeben, die Sie an svndumpfilter include und svndumpfilter exclude übergeben (und wenn sie keine haben, sollten Sie auch keine angeben). Falls Ihre Auszugsdatei aus irgendwelchen Gründen einen nicht konsistenten Gebrauch von führenden Schrägstrichen macht, [35] sollten Sie diese Pfade normalisieren, so dass sie alle entweder Schrägstriche haben oder nicht.
Ebenso können kopierte Pfade Probleme bereiten. Subversion unterstützt Kopieroperationen im Repository, bei denen ein neuer Pfad erzeugt wird, indem ein bereits bestehender kopiert wird. Es kann vorkommen, dass Sie zu irgendeinem Zeitpunkt der Lebenszeit Ihres Repositorys eine Datei oder ein Verzeichnis von einer durch svndumpfilter ausgelassenen Stelle an eine durch svndumpfilter berücksichtigte Stelle kopiert haben. Um die Auszugsdateien unabhängig zu machen, muss svndumpfilter trotzdem das Hinzufügen des neuen Pfades anzeigen – mit dem Inhalt aller durch die Kopie erzeugten Dateien – allerdings nicht als eine Kopie aus einer Quelle, die es gar nicht im gefilterten Auszugsstrom gibt. Da allerdings das Subversion Auszugsdateiformat nur Änderungen von Revisionen beinhaltet, kann es sein, dass der Inhalt der Quelle der Kopie nicht verfügbar ist. Wenn Sie mutmaßen, dass Sie solche Kopien in Ihrem Repository haben, sollten Sie die Auswahl der ausgelassenen/berücksichtigten Pfade überdenken, indem Sie vielleicht die Pfade, die als Quellen für die problematischen Kopien dienten, hinzunehmen.
Schließlich behandelt svndumpfilter
Pfadfilterung ziemlich wörtlich. Wenn Sie die Historie eines
Projektes mit dem Wurzelverzeichnis
trunk/my-project
kopieren und sie in ein
eigenes Repository verschieben möchten, werden Sie
selbstverständlich den Befehl svndumpfilter
include verwenden, um alle Änderungen in und
unterhalb von trunk/my-project
zu
bewahren. Doch macht die entstehende Auszugsdatei keinerlei
Annahmen bezüglich des Repositorys, in das Sie die Daten zu
laden beabsichtigen. In diesem besonderen Fall könnten die
Auszugsdaten mit der Revision beginnen, die das Verzeichnis
trunk/my-project
hinzugefügt hat, doch
sie werden keine Direktiven enthalten,
dir das Verzeichnis trunk
selbst anlegen
(weil trunk
nicht zum Filter der zu
berücksichtigenden Pfade passt). Sie müssen sicherstellen,
dass alle Verzeichnisse, die der Auszugsstrom erwartet,
tatsächlich im Ziel-Repository vorhanden sind, bevor Sie
versuchen, den Strom in dieses Repository zu laden.
There are several scenarios in which it is quite handy to have a Subversion repository whose version history is exactly the same as some other repository's. Perhaps the most obvious one is the maintenance of a simple backup repository, used when the primary repository has become inaccessible due to a hardware failure, network outage, or other such annoyance. Other scenarios include deploying mirror repositories to distribute heavy Subversion load across multiple servers, use as a soft-upgrade mechanism, and so on.
As of version 1.4, Subversion provides a program for managing scenarios such as these—svnsync. This works by essentially asking the Subversion server to „replay“ revisions, one at a time. It then uses that revision information to mimic a commit of the same to another repository. Neither repository needs to be locally accessible to the machine on which svnsync is running—its parameters are repository URLs, and it does all its work through Subversion's Repository Access (RA) interfaces. All it requires is read access to the source repository and read/write access to the destination repository.
When using svnsync against a remote source repository, the Subversion server for that repository must be running Subversion version 1.4 or later.
Assuming you already have a source repository that you'd like to mirror, the next thing you need is an empty target repository that will actually serve as that mirror. This target repository can use either of the available filesystem data-store backends (see „Auswahl der Datenspeicherung“), but it must not yet have any version history in it. The protocol that svnsync uses to communicate revision information is highly sensitive to mismatches between the versioned histories contained in the source and target repositories. For this reason, while svnsync cannot demand that the target repository be read-only, [36] allowing the revision history in the target repository to change by any mechanism other than the mirroring process is a recipe for disaster.
Do not modify a mirror repository in such a way as to cause its version history to deviate from that of the repository it mirrors. The only commits and revision property modifications that ever occur on that mirror repository should be those performed by the svnsync tool.
Another requirement of the target repository is that the svnsync process be allowed to modify revision properties. Because svnsync works within the framework of that repository's hook system, the default state of the repository (which is to disallow revision property changes; see pre-revprop-change) is insufficient. You'll need to explicitly implement the pre-revprop-change hook, and your script must allow svnsync to set and change revision properties. With those provisions in place, you are ready to start mirroring repository revisions.
It's a good idea to implement authorization measures that allow your repository replication process to perform its tasks while preventing other users from modifying the contents of your mirror repository at all.
Let's walk through the use of svnsync in a somewhat typical mirroring scenario. We'll pepper this discourse with practical recommendations, which you are free to disregard if they aren't required by or suitable for your environment.
As a service to the fine developers of our favorite version control system, we will be mirroring the public Subversion source code repository and exposing that mirror publicly on the Internet, hosted on a different machine than the one on which the original Subversion source code repository lives. This remote host has a global configuration that permits anonymous users to read the contents of repositories on the host, but requires users to authenticate to modify those repositories. (Please forgive us for glossing over the details of Subversion server configuration for the moment—those are covered thoroughly in Kapitel 6, Die Administration eines Subversion-Servers.) And for no other reason than that it makes for a more interesting example, we'll be driving the replication process from a third machine—the one that we currently find ourselves using.
First, we'll create the repository which will be our mirror. This and the next couple of steps do require shell access to the machine on which the mirror repository will live. Once the repository is all configured, though, we shouldn't need to touch it directly again.
$ ssh admin@svn.example.com \ "svnadmin create /var/svn/svn-mirror" admin@svn.example.com's password: ******** $
At this point, we have our repository, and due to our
server's configuration, that repository is now
„live“ on the Internet. Now, because we don't
want anything modifying the repository except our replication
process, we need a way to distinguish that process from other
would-be committers. To do so, we use a dedicated username
for our process. Only commits and revision property
modifications performed by the special username
syncuser
will be allowed.
We'll use the repository's hook system both to allow the
replication process to do what it needs to do and to enforce
that only it is doing those things. We accomplish this by
implementing two of the repository event
hooks—pre-revprop-change and start-commit. Our
pre-revprop-change
hook script is found
in Beispiel 5.2, „Mirror repository's pre-revprop-change hook script“, and basically verifies that the user attempting the
property changes is our syncuser
user. If
so, the change is allowed; otherwise, it is denied.
Beispiel 5.2. Mirror repository's pre-revprop-change hook script
#!/bin/sh USER="$3" if [ "$USER" = "syncuser" ]; then exit 0; fi echo "Only the syncuser user may change revision properties" >&2 exit 1
That covers revision property changes. Now we need to
ensure that only the syncuser
user is
permitted to commit new revisions to the repository. We do
this using a start-commit
hook scripts
such as the one in Beispiel 5.3, „Mirror repository's start-commit hook script“.
Beispiel 5.3. Mirror repository's start-commit hook script
#!/bin/sh USER="$2" if [ "$USER" = "syncuser" ]; then exit 0; fi echo "Only the syncuser user may commit new revisions" >&2 exit 1
After installing our hook scripts and ensuring that they are executable by the Subversion server, we're finished with the setup of the mirror repository. Now, we get to actually do the mirroring.
The first thing we need to do with svnsync is to register in our target repository the fact that it will be a mirror of the source repository. We do this using the svnsync initialize subcommand. The URLs we provide point to the root directories of the target and source repositories, respectively. In Subversion 1.4, this is required—only full mirroring of repositories is permitted. In Subversion 1.5, though, you can use svnsync to mirror only some subtree of the repository, too.
$ svnsync help init initialize (init): usage: svnsync initialize DEST_URL SOURCE_URL Initialize a destination repository for synchronization from another repository. … $ svnsync initialize http://svn.example.com/svn-mirror \ http://svn.collab.net/repos/svn \ --sync-username syncuser --sync-password syncpass Copied properties for revision 0. $
Our target repository will now remember that it is a mirror of the public Subversion source code repository. Notice that we provided a username and password as arguments to svnsync—that was required by the pre-revprop-change hook on our mirror repository.
In Subversion 1.4, the values given to
svnsync's --username
and
--password
command-line options were used
for authentication against both the source and destination
repositories. This caused problems when a user's
credentials weren't exactly the same for both repositories,
especially when running in noninteractive mode (with the
--non-interactive
option).
This has been fixed in Subversion 1.5 with the
introduction of two new pairs of options. Use
--source-username
and
--source-password
to provide authentication
credentials for the source repository; use
--sync-username
and
--sync-password
to provide credentials for
the destination repository. (The old
--username
and --password
options still exist for compatibility, but we advise against
using them.)
And now comes the fun part. With a single subcommand, we can tell svnsync to copy all the as-yet-unmirrored revisions from the source repository to the target. [37] The svnsync synchronize subcommand will peek into the special revision properties previously stored on the target repository, and determine both what repository it is mirroring as well as that the most recently mirrored revision was revision 0. Then it will query the source repository and determine what the latest revision in that repository is. Finally, it asks the source repository's server to start replaying all the revisions between 0 and that latest revision. As svnsync get the resultant response from the source repository's server, it begins forwarding those revisions to the target repository's server as new commits.
$ svnsync help synchronize synchronize (sync): usage: svnsync synchronize DEST_URL Transfer all pending revisions to the destination from the source with which it was initialized. … $ svnsync synchronize http://svn.example.com/svn-mirror Transmitting file data ........................................ Committed revision 1. Copied properties for revision 1. Transmitting file data .. Committed revision 2. Copied properties for revision 2. Transmitting file data ..... Committed revision 3. Copied properties for revision 3. … Transmitting file data .. Committed revision 23406. Copied properties for revision 23406. Transmitting file data . Committed revision 23407. Copied properties for revision 23407. Transmitting file data .... Committed revision 23408. Copied properties for revision 23408. $
Of particular interest here is that for each mirrored
revision, there is first a commit of that revision to the
target repository, and then property changes follow. This is
because the initial commit is performed by (and attributed to)
the user syncuser
, and it is datestamped
with the time as of that revision's creation. Also,
Subversion's underlying repository access interfaces don't
provide a mechanism for setting arbitrary revision properties
as part of a commit. So svnsync follows up
with an immediate series of property modifications that copy
into the target repository all the revision properties found
for that revision in the source repository. This also has the
effect of fixing the author and datestamp of the revision to
match that of the source repository.
Also noteworthy is that svnsync performs careful bookkeeping that allows it to be safely interrupted and restarted without ruining the integrity of the mirrored data. If a network glitch occurs while mirroring a repository, simply repeat the svnsync synchronize command, and it will happily pick up right where it left off. In fact, as new revisions appear in the source repository, this is exactly what you to do to keep your mirror up to date.
There is, however, one bit of inelegance in the process. Because Subversion revision properties can be changed at any time throughout the lifetime of the repository, and because they don't leave an audit trail that indicates when they were changed, replication processes have to pay special attention to them. If you've already mirrored the first 15 revisions of a repository and someone then changes a revision property on revision 12, svnsync won't know to go back and patch up its copy of revision 12. You'll need to tell it to do so manually by using (or with some additional tooling around) the svnsync copy-revprops subcommand, which simply rereplicates all the revision properties for a particular revision or range thereof.
$ svnsync help copy-revprops copy-revprops: usage: svnsync copy-revprops DEST_URL [REV[:REV2]] Copy the revision properties in a given range of revisions to the destination from the source with which it was initialized. … $ svnsync copy-revprops http://svn.example.com/svn-mirror 12 Copied properties for revision 12. $
That's repository replication in a nutshell. You'll likely want some automation around such a process. For example, while our example was a pull-and-push setup, you might wish to have your primary repository push changes to one or more blessed mirrors as part of its post-commit and post-revprop-change hook implementations. This would enable the mirror to be up to date in as near to real time as is likely possible.
Also, while it isn't very commonplace to do so, svnsync does gracefully mirror repositories in which the user as whom it authenticates has only partial read access. It simply copies only the bits of the repository that it is permitted to see. Obviously, such a mirror is not useful as a backup solution.
In Subversion 1.5, svnsync grew the ability to also mirror a subset of a repository rather than the whole thing. The process of setting up and maintaining such a mirror is exactly the same as when mirroring a whole repository, except that instead of specifying the source repository's root URL when running svnsync init, you specify the URL of some subdirectory within that repository. Synchronization to that mirror will now copy only the bits that changed under that source repository subdirectory. There are some limitations to this support, though. First, you can't mirror multiple disjoint subdirectories of the source repository into a single mirror repository—you'd need to instead mirror some parent directory that is common to both. Second, the filtering logic is entirely path-based, so if the subdirectory you are mirroring was renamed at some point in the past, your mirror would contain only the revisions since the directory appeared at the URL you specified. And likewise, if the source subdirectory is renamed in the future, your synchronization processes will stop mirroring data at the point that the source URL you specified is no longer valid.
As far as user interaction with repositories and mirrors goes, it is possible to have a single working copy that interacts with both, but you'll have to jump through some hoops to make it happen. First, you need to ensure that both the primary and mirror repositories have the same repository UUID (which is not the case by default). See „Managing Repository UUIDs“ later in this chapter for more about this.
Once the two repositories have the same UUID, you can use
svn switch with the --relocate
option to point your working
copy to whichever of the repositories you wish to operate
against, a process that is described in svn switch. There is a possible danger
here, though, in that if the primary and mirror repositories
aren't in close synchronization, a working copy up to date
with, and pointing to, the primary repository will, if
relocated to point to an out-of-date mirror, become confused
about the apparent sudden loss of revisions it fully expects
to be present, and it will throw errors to that effect. If
this occurs, you can relocate your working copy back to the
primary repository and then either wait until the mirror
repository is up to date, or backdate your working copy to a
revision you know is present in the sync repository, and then
retry the relocation.
Finally, be aware that the revision-based replication provided by svnsync is only that—replication of revisions. Only information carried by the Subversion repository dump file format is available for replication. As such, svnsync has the same sorts of limitations that the repository dump stream has, and does not include such things as the hook implementations, repository or server configuration data, uncommitted transactions, or information about user locks on repository paths.
Despite numerous advances in technology since the birth of the modern computer, one thing unfortunately rings true with crystalline clarity—sometimes things go very, very awry. Power outages, network connectivity dropouts, corrupt RAM, and crashed hard drives are but a taste of the evil that Fate is poised to unleash on even the most conscientious administrator. And so we arrive at a very important topic—how to make backup copies of your repository data.
There are two types of backup methods available for Subversion repository administrators—full and incremental. A full backup of the repository involves squirreling away in one sweeping action all the information required to fully reconstruct that repository in the event of a catastrophe. Usually, it means, quite literally, the duplication of the entire repository directory (which includes either a Berkeley DB or FSFS environment). Incremental backups are lesser things: backups of only the portion of the repository data that has changed since the previous backup.
As far as full backups go, the naïve approach might seem like a sane one, but unless you temporarily disable all other access to your repository, simply doing a recursive directory copy runs the risk of generating a faulty backup. In the case of Berkeley DB, the documentation describes a certain order in which database files can be copied that will guarantee a valid backup copy. A similar ordering exists for FSFS data. But you don't have to implement these algorithms yourself, because the Subversion development team has already done so. The svnadmin hotcopy command takes care of the minutia involved in making a hot backup of your repository. And its invocation is as trivial as the Unix cp or Windows copy operations:
$ svnadmin hotcopy /var/svn/repos /var/svn/repos-backup
The resultant backup is a fully functional Subversion repository, able to be dropped in as a replacement for your live repository should something go horribly wrong.
When making copies of a Berkeley DB repository, you can
even instruct svnadmin hotcopy to purge any
unused Berkeley DB logfiles (see „Entfernen unbenutzter Protokolldateien von Berkeley DB“) from the
original repository upon completion of the copy. Simply
provide the --clean-logs
option on the
command line.
$ svnadmin hotcopy --clean-logs /var/svn/bdb-repos /var/svn/bdb-repos-backup
Additional tooling around this command is available, too.
The tools/backup/
directory of the
Subversion source distribution holds the
hot-backup.py script. This script adds a
bit of backup management atop svnadmin
hotcopy, allowing you to keep only the most recent
configured number of backups of each repository. It will
automatically manage the names of the backed-up repository
directories to avoid collisions with previous backups and
will „rotate off“ older backups, deleting them so
that only the most recent ones remain. Even if you also have an
incremental backup, you might want to run this program on a
regular basis. For example, you might consider using
hot-backup.py from a program scheduler
(such as cron on Unix systems), which can
cause it to run nightly (or at whatever granularity of time
you deem safe).
Some administrators use a different backup mechanism built
around generating and storing repository dump data. We
described in „Repository-Daten woandershin verschieben“
how to use svnadmin dump with the --incremental
option to
perform an incremental backup of a given revision or range of
revisions. And of course, you can achieve a full backup variation of
this by omitting the --incremental
option to that command. There is some value in these methods,
in that the format of your backed-up information is
flexible—it's not tied to a particular platform,
versioned filesystem type, or release of Subversion or
Berkeley DB. But that flexibility comes at a cost, namely
that restoring that data can take a long time—longer
with each new revision committed to your repository. Also, as
is the case with so many of the various backup methods,
revision property changes that are made to already backed-up
revisions won't get picked up by a nonoverlapping,
incremental dump generation. For these reasons, we recommend
against relying solely on dump-based backup approaches.
As you can see, each of the various backup types and methods has its advantages and disadvantages. The easiest is by far the full hot backup, which will always result in a perfect working replica of your repository. Should something bad happen to your live repository, you can restore from the backup with a simple recursive directory copy. Unfortunately, if you are maintaining multiple backups of your repository, these full copies will each eat up just as much disk space as your live repository. Incremental backups, by contrast, tend to be quicker to generate and smaller to store. But the restoration process can be a pain, often involving applying multiple incremental backups. And other methods have their own peculiarities. Administrators need to find the balance between the cost of making the backup and the cost of restoring it.
The svnsync program (see „Repository Replication“) actually provides a rather handy middle-ground approach. If you are regularly synchronizing a read-only mirror with your main repository, in a pinch your read-only mirror is probably a good candidate for replacing that main repository if it falls over. The primary disadvantage of this method is that only the versioned repository data gets synchronized—repository configuration files, user-specified repository path locks, and other items that might live in the physical repository directory but not inside the repository's virtual versioned filesystem are not handled by svnsync.
In any backup scenario, repository administrators need to be aware of how modifications to unversioned revision properties affect their backups. Since these changes do not themselves generate new revisions, they will not trigger post-commit hooks, and may not even trigger the pre-revprop-change and post-revprop-change hooks. [38] And since you can change revision properties without respect to chronological order—you can change any revision's properties at any time—an incremental backup of the latest few revisions might not catch a property modification to a revision that was included as part of a previous backup.
Generally speaking, only the truly paranoid would need to back up their entire repository, say, every time a commit occurred. However, assuming that a given repository has some other redundancy mechanism in place with relatively fine granularity (such as per-commit emails or incremental dumps), a hot backup of the database might be something that a repository administrator would want to include as part of a system-wide nightly backup. It's your data—protect it as much as you'd like.
Often, the best approach to repository backups is a diversified one that leverages combinations of the methods described here. The Subversion developers, for example, back up the Subversion source code repository nightly using hot-backup.py and an off-site rsync of those full backups; keep multiple archives of all the commit and property change notification emails; and have repository mirrors maintained by various volunteers using svnsync. Your solution might be similar, but should be catered to your needs and that delicate balance of convenience with paranoia. And whatever you do, validate your backups from time to time—what good is a spare tire that has a hole in it? While all of this might not save your hardware from the iron fist of Fate, [39] it should certainly help you recover from those trying times.
Subversion repositories have a universally unique identifier (UUID) associated with them. This is used by Subversion clients to verify the identity of a repository when other forms of verification aren't good enough (such as checking the repository URL, which can change over time). Most Subversion repository administrators rarely, if ever, need to think about repository UUIDs as anything more than a trivial implementation detail of Subversion. Sometimes, however, there is cause for attention to this detail.
As a general rule, you want the UUIDs of your live repositories to be unique. That is, after all, the point of having UUIDs. But there are times when you want the repository UUIDs of two repositories to be exactly the same. For example, if you make a copy of a repository for backup purposes, you want the backup to be a perfect replica of the original so that, in the event that you have to restore that backup and replace the live repository, users don't suddenly see what looks like a different repository. When dumping and loading repository history (as described earlier in „Repository-Daten woandershin verschieben“), you get to decide whether to apply the UUID encapsulated in the data dump stream to the repository in which you are loading the data. The particular circumstance will dictate the correct behavior.
There are a couple of ways to set (or reset) a repository's UUID, should you need to. As of Subversion 1.5, this is as simple as using the svnadmin setuuid command. If you provide this subcommand with an explicit UUID, it will validate that the UUID is well-formed and then set the repository UUID to that value. If you omit the UUID, a brand-new UUID will be generated for your repository.
$ svnlook uuid /var/svn/repos cf2b9d22-acb5-11dc-bc8c-05e83ce5dbec $ svnadmin setuuid /var/svn/repos # generate a new UUID $ svnlook uuid /var/svn/repos 3c3c38fe-acc0-11dc-acbc-1b37ff1c8e7c $ svnadmin setuuid /var/svn/repos \ cf2b9d22-acb5-11dc-bc8c-05e83ce5dbec # restore the old UUID $ svnlook uuid /var/svn/repos cf2b9d22-acb5-11dc-bc8c-05e83ce5dbec $
For folks using versions of Subversion earlier than 1.5,
these tasks are a little more complicated. You can explicitly
set a repository's UUID by piping a repository dump file stub
that carries the new UUID specification through
svnadmin load --force-uuid
.REPOS-PATH
$ svnadmin load --force-uuid /var/svn/repos <<EOF SVN-fs-dump-format-version: 2 UUID: cf2b9d22-acb5-11dc-bc8c-05e83ce5dbec EOF $ svnlook uuid /var/svn/repos cf2b9d22-acb5-11dc-bc8c-05e83ce5dbec $
Having older versions of Subversion generate a brand-new UUID is not quite as simple to do, though. Your best bet here is to find some other way to generate a UUID, and then explicitly set the repository's UUID to that value.
Subversion repository data is wholly contained within the repository directory. As such, you can move a Subversion repository to some other location on disk, rename a repository, copy a repository, or delete a repository altogether using the tools provided by your operating system for manipulating directories—mv, cp -a, and rm -r on Unix platforms; copy, move, and rmdir /s /q on Windows; vast numbers of mouse and menu gyrations in various graphical file explorer applications, and so on.
Of course, there's often still more to be done when trying to cleanly affect changes such as this. For example, you might need to update your Subversion server configuration to point to the new location of a relocated repository or to remove configuration bits for a now-deleted repository. If you have automated processes that publish information from or about your repositories, they may need to be updated. Hook scripts might need to be reconfigured. Users may need to be notified. The list can go on indefinitely, or at least to the extent that you've built processes and procedures around your Subversion repository.
In the case of a copied repository, you should also consider the fact that Subversion uses repository UUIDs to distinguish repositories. If you copy a Subversion repository using a typical shell recursive copy command, you'll wind up with two repositories that are identical in every way—including their UUIDs. In some circumstances, this might be desirable. But in the instances where it is not, you'll need to generate a new UUID for one of these identical repositories. See „Managing Repository UUIDs“ for more about managing repository UUIDs.
By now you should have a basic understanding of how to create, configure, and maintain Subversion repositories. We introduced you to the various tools that will assist you with this task. Throughout the chapter, we noted common administration pitfalls and offered suggestions for avoiding them.
All that remains is for you to decide what exciting data to store in your repository, and finally, how to make it available over a network. The next chapter is all about networking.
[26] Das hört sich vielleicht prestigeträchtig und hochmütig an, doch wir meinen lediglich jeden, der an diesem mysteriösen Bereich hinter der Arbeitskopie interessiert ist, wo sich alle Daten befinden.
[27] Ob es an Ignoranz oder an schlecht überlegten Konzepten zur Erstellung berechtigter Metriken für die Software-Entwicklung liegt, ist es dumm, Angst vor globalen Revisionsnummern zu haben, und es ist deshalb kein Kriterium, das Sie heranziehen sollten, wenn Sie abwägen, wie Sie Ihre Projekte und Repositorys anlegen wollen.
[28] Das Trio trunk
,
tags
, and branches
wird manchmal als „die TTB-Verzeichnisse“
bezeichnet.
[29] Wenn Jack Repenning gefragt wird, ist die Aussprache oft „fass-fass“. (Jedoch geht dieses Buch davon aus, dass der Leser „eff-ess-eff-ess“ denkt)
[30] Berkeley DB setzt voraus, dass das zugrundeliegende Dateisystem strenge POSIX-Sperrmechanismen implementiert und, noch wichtiger, die Fähigkeit mitbringt, Dateien direkt in den Prozessspeicher abzubilden.
[31] Oracle kaufte Sleepycat und sein Vorzeigeprogramm, Berkeley DB, am Valentinstag 2006.
[32] Beispielsweise Festplatte + starker Elektromagnet = Desaster.
[33] Das ist doch überhaupt der Grund dafür, Versionskontrolle einzusetzen, oder?
[34] Das bewusste, vorsichtige Entfernen bestimmter Teile versionierter Daten wird tatsächlich von wirklichen Anwendungsfällen verlangt. Das ist der Grund, warum eine „Auslösch“-Funktion eine der am häufigsten gewünschten Funktionen von Subversion ist, von der die Subversion-Entwickler hoffen, sie bald zur Verfügung stellen zu können.
[35] Obwohl svnadmin dump ein konsistentes Vorgehen bezüglich führender Schrägstriche vorweisen kann (indem es sie nicht einfügt), sind andere Programme, die Auszugsdateien erzeugen eventuell nicht so konsistent.
[36] In fact, it can't truly be read-only, or svnsync itself would have a tough time copying revision history into it.
[37] Be forewarned that while it will take only a few seconds for the average reader to parse this paragraph and the sample output that follows it, the actual time required to complete such a mirroring operation is, shall we say, quite a bit longer.
[38] svnadmin setlog can be called in a way that bypasses the hook interface altogether.
[39] You know—the collective term for all of her „fickle fingers.“
Inhaltsverzeichnis
Der Zugriff auf ein Subversion-Repository kann problemlos
von mehreren Clients, welche auf demselben Rechner wie
Subversion laufen, gleichzeitig erfolgen – unter Verwendung der
file://
-Methode. Aber typischerweise läuft
der Subversion-Server auf einem separaten Rechner, und der Zugriff
erfolgt von Clients auf vielen verschiedenen Computern aus der ganzen
Firma – ja sogar der ganzen Welt.
In diesem Kapitel erklären wir, wie Sie ihr Subversion-Repository für den Fernzugriff von Clients fit machen. Wir werden ausführlich auf alle aktuell verfügbaren Servermechanismen von Subversion eingehen und über ihre Konfiguration und Verwendung reden. Nach dem Lesen dieses Kapitels sollten Sie in der Lage sein, zu entscheiden, welche Netzwerk-Konfiguration Ihren Bedürfnissen entspricht und wie diese auf ihrem Server eingerichtet wird.
Subversion wurde mit einer abstrakten Netzwerkschicht entworfen. Dies bedeutet, dass auf ein Repository automatisiert von beliebigen Server-Prozessen zugegriffen werden kann, und die für Clients vorhandene „Repository-Access“-API (Programmierschnittstelle) erlaubt es Programmierern, Plugins zu entwickeln, die relevante Netzwerkprotokolle verstehen. Theoretisch ermöglicht dies Subversion, eine unbegrenzte Zahl an Netzwerkprotokollen zu verwenden. Zum Zeitpunkt an dem dies geschrieben wird, gibt es aber nur zwei Server.
Apache ist ein sehr beliebter Webserver, welcher mittels des mod_dav_svn-Moduls auf Repositorys zugreifen und diese für Clients verfügbar machen kann. Verwendet wird dabei das WebDAV/DeltaV-Protokoll, welches eine Erweiterung von HTTP ist. Da Apache ein stark erweiterbarer Webserver ist, bietet er eine Menge an „frei verfügbaren“ Funktionen/Modulen, wie SSL-verschlüsselte Verbindungen, Logging, sowie die Integration diverser Authentifikationssysteme von Drittanbietern und einen eingeschränkten Web-Browser-gestützten Repository-Lesezugriff.
In der anderen Ecke befindet sich svnserve: ein kleiner, leichtgewichtiger Server, der ein einfaches Netzwerkprotokoll für die Zugriffe der Clients verwendet. Da dieses Protokoll für die Verwendung mit Subversion entwickelt wurde und, im Gegensatz zu HTTP, zustandsorientiert ist, bietet es einen deutlich schnelleren Netzwerkzugriff – spart allerdings auch einige wichtige Funktionen aus. So bietet er eine SASL-basierte Verschlüsselung und Authentifikation, hat aber keine Logging-Funktionen oder eingebauten Web-Browser-Zugriff. Wie auch immer, er ist extrem einfach einzurichten und für kleinere Teams, welche einfach nur schnell mit Subversion "loslegen" wollen, die beste Wahl.
Ein dritte Möglichkeit ist, svnserve durch
SSH-Verbindungen zu tunneln. Auch wenn in diesem Fall weiterhin
svnserve verwendet wird, so unterscheidet sich
die Funktionalität ziemlich von der normalen Nutzung von
svnserve. SSH wird zur Verschlüsselung der gesamten
Kommunikation verwendet. Ebenso zur Authentifizierung, was die
Verwendung von realen Nutzerkonten auf dem Subversion-Server notwendig
macht (anders als beim einfachen svnserve, der seine
eigene Nutzerverwaltung hat). Des weiteren ist es notwendig – da jeder
angemeldete Nutzer einen eigenen svnserve-Prozess
startet – einer Gruppe von lokalen Nutzern (aus Sicht der Rechtevergabe)
vollen Zugriff auf das Repository via file://
URLs zu
ermöglichen. Pfad-basierte Zugriffskontrolle schließt sich in diesem Fall aus,
da die Nutzer direkt auf die Datenbank-Dateien zugreifen.
Tabelle 6.1, „Vergleich der Serveroptionen für Subversion“ zeigt eine kurze Zusammenfassung der drei typischen Server-Konfigurationen.
Tabelle 6.1. Vergleich der Serveroptionen für Subversion
Funktionen | Apache + mod_dav_svn | svnserve | svnserve via SSH |
---|---|---|---|
Authentifizierungsmöglichkeiten | HTTP(S) basic auth, X.509 Zertifikate, LDAP, NTLM, oder jede andere für den Apache Webserver verfügbare Methode | CRAM-MD5 als Voreinstellung, LDAP, NTLM oder jede andere für SASL verfügbare Methode | SSH |
Nutzerkonfigurationen | private users Datei oder jede andere für den Apache Webserver verfügbare Methode (LDAP, SQL, etc) | private users Datei, oder jede andere für SASL verfügbare Methode (LDAP, SQL, etc.) | lokale Nutzerkonten auf dem Server |
Autorisierungsmöglichkeiten | Lese-/Schreibzugriff auf das komplette Repository oder pfadbasierte Rechtevergabe | Lese-/Schreibzugriff auf das komplette Repository oder pfadbasierte Rechtevergabe | Lese-/Schreibzugriff nur auf ganzes Repository einstellbar |
Verschlüsselung | optional mit SSL | optional mit der SASL-Funktionen | Bestandteil der SSH-Verbindung |
Loggen | Apache-seitiges Loggen aller HTTP-Anfragen, optionales „High-Level“-Loggen aller Client-Operationen | kein Loggen | kein Loggen |
Interoperabilität | Zugriff durch andere WebDAV-Clients | Verbindung nur mit svn-Clients möglich | Verbindung nur mit svn-Clients möglich |
web-basierte Anzeige des Repositorys | eingeschränkte Unterstützung, alternativ mittels Programmen von Drittanbietern, wie etwa ViewVC, erweiterbar | nur mittels Programmen von Drittanbietern, wie etwa ViewVC | nur mittels Programmen von Drittanbietern, wie etwa ViewVC |
Master-Slave-Server Replikationen | transparenter Schreib-Proxy vom Slave zum Master | beschränkt auf nur lesbare Slave-Server | beschränkt auf nur lesbare Slave-Server |
Geschwindigkeit | ein wenig langsamer | ein wenig schneller | ein wenig schneller |
Erstkonfiguration | eher komplexer | sehr einfach | durchschnittlich |
Also dann, welchen Server sollten Sie nun verwenden? Welcher ist der beste?
Auf diese Frage gibt es offensichtlich nicht die eine, richtige Antwort. Denn jedes Team stellt andere Anforderungen, und die verschieden Server bieten unterschiedliche Funktionen und Voraussetzungen. Das Subversion-Projekt selbst bevorzugt keinen der genannten Server oder betrachtet einen als etwas „offizieller“ als die anderen.
Wir beleuchten nun die einzelnen Gründe, die für die eine oder andere Konstellation sprechen, ebenso auch Gründe, welche vielleicht gegen eine der Möglichkeiten sprechen.
Das Aufsetzen geht schnell und einfach.
Das verwendete Netzwerkprotokoll ist zustandsorientiert und merklich schneller als WebDAV.
Es müssen keine lokalen Nutzerkonten auf dem Server eingerichtet werden.
Das Passwort wird nicht über das Netzwerk übertragen.
Es gibt standardmäßig nur eine Authentifizierungsmethode, das Netzwerkprotokoll ist unverschlüsselt und das Passwort wird vom Server im Klartext gespeichert. (Mit SASL können diese Probleme zwar umgangen werden, dies erfordert aber eine etwas aufwendigere Konfiguration.)
Es wird nichts geloggt, auch keine Fehler.
Keinen eingebauten Webbrowser-gestützten Lesezugriff. (Wenn Sie dies wünschen, müssen Sie einen eigenständigen Webserver sowie Repository-Browser-Software installieren.)
Das verwendete Netzwerkprotokoll ist zustandsorientiert und merklich schneller als WebDAV.
Sie können bestehende Nutzerzugänge des SSH-Servers verwenden.
Der gesamte Netzwerkverkehr ist verschlüsselt.
Es steht nur eine Authentifizierungsmöglichkeit zur Verfügung.
Es wird nichts geloggt, auch keine Fehler.
Die verwendeten Nutzer müssen in derselben Nutzergruppe (auf dem Server) sein, oder sich einen SSH-Key teilen.
Bei unsachgemäßer Verwendung kann es zu Problemen mit den Dateirechten kommen.
Subversion hat damit Zugriff auf alle für den Apache verfügbaren Authentifizierungsmethoden (und das sind viele).
Es müssen auf dem Server keine Nutzerkonten angelegt werden.
Apache loggt nach Wunsch (fast) alles.
Der Netzwerkverkehr kann mittels SSL verschlüsselt werden.
In der Regel lässt sich das HTTP(S)-Protokoll problemlos durch Firewalls routen.
Auf das Repository kann lesend auch via Webbrowser zugegriffen werden.
Das Repository lässt sich als Netzlaufwerk einhängen (mounten). Änderungen an den Dateien unterliegen trotzdem der Versionskontrolle. (siehe „Autoversioning“.)
Er ist merklich langsamer als svnserve, da HTTP als zustandsloses Protokoll eine höhere Netzwerklast verursacht.
Die Ersteinrichtung kann etwas schwierig sein.
Im Allgemeinen empfehlen die Autoren dieses Buches eine einfache svnserve-Installation für kleine Teams, denen an einer schnellen und unkomplizierten Nutzung von Subversion gelegen ist. Dies ist die Variante, welche sich am einfachsten einrichten und administrieren lässt. Sollte später Bedarf bestehen, so kann immer noch auf eine komplexere Servervariante gewechselt werden.
Es folgen einige allgemeine Empfehlungen und Tipps, basierend auf mehrjähriger Erfahrung in der Nutzerbetreuung:
Falls Sie für ihr Team die einfachste Servervariante suchen, dann kommen Sie mit einer Standard-svnserve-Installation am schnellsten ans Ziel. Beachten Sie aber, dass der Inhalt ihres Repositorys im Klartext über das Netzwerk übertragen wird. Wenn Sie nur innerhalb ihres Firmennetzwerks oder eines VPNs arbeiten, so ist dies kein Beinbruch. Ist ihr Repository allerdings vom Internet aus erreichbar, so sollten Sie eventuell sicherstellen, dass darin keine sensiblen Daten vorhanden sind (z.B. nur Open-Source Code o.ä.), oder Sie legen noch einmal Hand an und verschlüsseln mittels SASL die Netzwerkverbindung zur ihrem Repository.
Wenn Sie bereits über Systeme zur Authentifizierung (LDAP, Active Directory, NTLM, X.509 etc.) verfügen und Subversion in diese integrieren möchten, so bleibt Ihnen die Wahl zwischen einer Apache-gestützten Variante oder eines mit SASL vermählten svnserve. Stehen serverseitige Logs zur Aufzeichnung von Client-Aktivitäten und Serverfehlern auf Ihrer Wunschliste, dann ist Apache die einzige Option.
Wenn Sie sich für die Verwendung von Apache oder eines Standard-svnserve entschieden haben, dann legen Sie auf ihrem System einen einfachen svn-Nutzer an und lassen den Serverprozess unter diesem Nutzer laufen. Stellen Sie zudem sicher, dass das gesamte Verzeichnis mit dem Repository nur diesem svn-Nutzer gehört. Damit wird der Zugriff auf ihr Repository durch das Dateisystem des Serverbetriebssystems verwaltet, und nur der Serverprozess kann noch Änderungen daran vornehmen.
Wenn Sie bereits über eine aus SSH-Zugängen bestehende Infrastruktur verfügen, und Ihre Nutzer auf dem Subversion-Server schon lokale Zugänge haben, dann ist die Verwendung einer svnserve-über-SSH-Lösung sinnvoll. Wir empfehlen diese Variante allerdings nur sehr ungern. Es ist im Allgemeinen sicherer, Ihren Nutzern nur durch svnserve oder Apache verwaltete Zugänge den Zugriff auf Ihr Repository zu ermöglichen und eben nicht mittels vollwertiger Nutzerzugänge auf dem Serversystem. Falls der Wunsch nach einer starken Netzwerkverschlüsselung Sie auf die Verwendung des SSH gebracht hat, dann empfehlen wir Ihnen stattdessen die Verwendung von Apache und SSL, bzw. die Kombination aus svnserve und SASL-Verschlüsselung.
Lassen Sie sich bitte nicht von der Idee verführen,
allen Ihren Nutzern direkten Zugriff auf das Repository mittels der
file://
-Methode zu geben. Auch wenn der Zugriff
auf das Repository durch eine Netzwerkfreigabe erfolgt, bleibt es immmer
noch eine schlechte Idee.
Dadurch wird jeglicher Sicherheitspuffer zwischen dem Nutzer und dem Repository
entfernt: Ein Anwender kann ohne (oder auch mit) Absicht die Datenbank des Repositorys
beschädigen.
Es wird zudem schwierig, das Repository offline zu nehmen um eine Inspektion
oder ein Upgrade durchzuführen. Zudem kann es Ihnen eine Menge Probleme mit
den Dateirechten einbringen (siehe „Supporting Multiple Repository Access Methods“).
Beachten Sie bitte auch, dass dies einer der Gründe ist, warum wir vor der
Verwendung der svn+ssh://
-Methode für den Repository-Zugriff
warnen. Vom Standpunkt der Sicherheit ist dies effektiv dasselbe wie
die Verwendung von file://
für den Zugriff durch lokale
Benutzer und kann zu denselben Problemen führen, wenn der Administrator nicht
alle Vorsicht walten lässt.
Das Programm svnserve ist ein leichtgewichtiger Server,
welcher für die Kommunikation mit den Clients ein auf TCP/IP basierendes,
zustandsorientiertes Protokoll verwendet. Um sich mit dem Server zu
verbinden, verwenden die Clients entweder das svn://
-
oder das svn+ssh://
-Schema. In diesem Abschnitt behandeln
wir die unterschiedlichen Möglichkeiten, svnserve
einzusetzen, wie sich die Clients am Server authentifizieren und wie
die passenden Zugangsrechte zum Repository korrekt eingerichtet werden.
Es gibt mehrere Möglichkeiten, svnserve zu starten:
svnserve als eigenständigen Dienst (engl. daemon) starten und auf Anfragen von Clients reagieren lassen.
svnserve bei Bedarf mit Hilfe des Unix-Dienstes inetd starten, wenn auf einem festgelegten Port Anfragen eines svn-Clients ankommen.
Einen SSH-Server verwenden, um svnserve fallweise über einen verschlüsselten SSH-Tunnel zu betreiben.
svnserve als Microsoft-Windows-Dienst laufen lassen.
Die einfachste Variante ist, svnserve als
eigenständigen (Unix-)Dienst laufen zu lassen. Verwenden Sie hierfür
die -d
Option beim Aufruf:
$ svnserve -d $ # svnserve läuft nun als Dienst und lauscht auf Port 3690
Wird svnserve als Dienst betrieben,
können Sie mit den Optionen --listen-port
und
--listen-host
festlegen, auf welchem Port und unter
welchem Hostnamen er lauschen soll.
Wurde svnserve auf diese Weise erfolgreich gestartet,
stehen nun alle Repositorys auf dem Server für Nutzer im Netzwerk zur Verfügung.
Für einen Zugriff muss ein Client den absoluten Pfad zum
Repository im URL angeben. Ist das Repository beispielsweise im Verzeichnis
/var/svn/project1
gespeichert, so sieht ein entsprechender URL
für den Zugriff folgendermaßen aus: svn://host.example.com/var/svn/project1
.
Um die Sicherheit zu erhöhen, kann svnserve beim Start mit
der Option -r
auf ein bestimmtes Verzeichnis beschränkt werden, so dass nur noch
die darin liegenden Repositorys im Netz verfügbar sind. Ein Beispiel:
$ svnserve -d -r /var/svn …
Mit der -r
-Option wird festgelegt, welches
Verzeichnis vom svnserve bei Anfragen als
Wurzelverzeichnis (engl. root) verwendet wird. Ein Client muss
nun in seiner URL nur noch den Pfad relativ zum neuen Wurzelverzeichnis
angeben, was die URL erheblich verkürzt und
die Verzeichnisstruktur etwas verschleiert:
$ svn checkout svn://host.example.com/project1 …
Wenn Sie inetd zum Starten des
Prozesses verwenden wollen,
so übergeben Sie svnserve beim Aufruf
die Option -i
(--inetd
). Im folgenden Beispiel sehen
wir die Ausgaben beim Aufruf von svnserve -i
auf der Kommandozeile. Beachten Sie aber, dass dies nicht
der Weg ist, wie der Dienst normalerweise gestartet wird – eine genaue
Beschreibung, wie svnserve über inetd gestartet
wird, folgt anschließend.
$ svnserve -i ( success ( 1 2 ( ANONYMOUS ) ( edit-pipeline ) ) )
Mit der --inetd
-Option versucht svnserve
mit dem Subversion-Client unter Verwendung eines speziellen Protokolls via
stdin
und stdout
zu sprechen.
Dies ist der normale Weg für ein Programm, welches über inetd
gestartet wurde. Die IANA (Internet Assigned Numbers Authority) hat für das
Subversion-Protokoll den Port 3690 reserviert – auf einem Unix-ähnlichen System
fügen Sie einfach folgende Zeilen (wenn noch nicht vorhanden) in die Datei
/etc/services
ein:
svn 3690/tcp # Subversion svn 3690/udp # Subversion
Wenn Sie den klassischen Unix-inetd
verwenden, können Sie die folgende Zeile in die Datei /etc/inetd.conf
einfügen:
svn stream tcp nowait svnowner /usr/bin/svnserve svnserve -i
Stellen Sie sicher, dass „svnowner“ der Nutzer ist,
welcher alle notwendigen Zugriffsrechte auf ihre Repositorys hat.
Kommt nun eine Anfrage eines Subversion-Clients auf Port 3690 herein,
so wird inetd einen svnserve-Prozess
starten, um die Anfrage zu bedienen. Wahrscheinlich möchten Sie
noch die -r
-Option zur oben genannten Zeile hinzufügen,
um einzuschränken, welche Repositorys exportiert werden dürfen.
Eine dritte Möglichkeit ist, svnserve mittels
der -t
-Option im Tunnel-Modus aufzurufen.
Bei diesem Aufruf wird vorausgesetzt, dass ein anderes Programm für
den Remote-Zugriff – etwa rsh oder ssh –
den Nutzer bereits erfolgreich authentifiziert hat, um nun einen privaten
svnserve-Prozess als dieser Nutzer
zu starten. (Beachten Sie, dass für Sie als Nutzer selten bis nie die
Notwendigkeit bestehen wird, svnserve mit der
-t
-Option von Hand auf der Kommandozeile aufzurufen –
der SSH-Dienst wird dies in der Regel für Sie machen.) svnserve
wird sich nun normal verhalten (Abwicklung der Kommunikation über stdin
und stdout
) und davon ausgehen, dass alle Daten mit Hilfe des Tunnels
zum Client weitergeleitet werden. Wird svnserve wie in diesem Fall
durch ein Tunnel-Programm aufgerufen, ist es notwendig, dass der aufrufende Nutzer volle Lese-
und Schreibrechte auf die Dateien der Repository-Datenbank hat.
Es verhält sich dabei im Grunde genommen so, als wenn der Nutzer mit einem
file://
-URL auf ein Repository zugreifen würde.
Wir werden diese Option noch genauer in diesem Kapitel behandeln, und zwar in „Tunneling over SSH“.
Gehört ihr Windows zur NT-Familie (2000, 2003, XP oder Vista),
so können Sie svnserve auch als normalen
Windows-Dienst laufen lassen. Dies ist wesentlich sinnvoller, als
die Option --daemon
(-d
) zu verwenden und ihn
als selbstständigen Dienst zu betreiben. Sie müssten dann immer eine
Konsole (cmd) öffnen, den passenden Befehl aufrufen und die Konsole
anschließend die ganze Zeit geöffnet lassen. Ein Windows-Dienst dagegen
läuft im Hintergrund, kann bereits beim Hochfahren
automatisch starten und lässt sich wie jeder andere Windows-Dienst
mit demselben Administrationsprogramm starten und stoppen.
Es ist notwendig, den neuen Windows-Dienst unter Verwendung des Kommandozeilenprogramms SC.EXE einzurichten. Ähnlich der inetd-Konfigurationszeile müssen Sie den genauen Aufruf für den Start von svnserve festlegen:
C:\> sc create svn binpath= "C:\svn\bin\svnserve.exe --service -r C:\repos" displayname= "Subversion Server" depend= Tcpip start= auto
Hiermit erzeugen Sie einen neuen Windows-Dienst mit dem
Namen „svn“, welcher jedesmal das Programm
svnserve.exe startet (und in diesem Fall
C:\repos
als Wurzelverzeichnis verwendet).
In diesem Beispiel müssen jedoch einige wichtige Punkte beachtet werden.
Als erstes ist es wichtig, dass das Programm svnserve.exe
immer mit der Option --service
aufgerufen wird.
Alle weiteren Optionen müssen in derselben Zeile folgen, allerdings
dürfen sich widersprechende Option nicht verwendet werden – wie etwa
--daemon
(-d
), --tunnel
oder --inetd
(-i
).
Optionen wie -r
oder --listen-port
sind
hingegen in Ordnung. Zweitens, seien Sie beim Aufruf von SC.EXE
mit Leerzeichen vorsichtig: Beim Schreiben der Schlüssel= Wert
-Zeile
darf zwischen Schlüssel
und =
kein
Leerzeichen stehen, vor Wert
muss genau ein Leerzeichen stehen.
Seien Sie zuletzt auch bei der Verwendung von Leerzeichen innerhalb ihres
Kommandozeilenaufrufes vorsichtig. Sollten Verzeichnisangaben etwa Leerzeichen
(oder andere zu schützende Zeichen) enthalten, so umschließen Sie sie mit
zusätzlichen doppelten Anführungszeichen:
C:\> sc create svn binpath= "\"C:\program files\svn\bin\svnserve.exe\" --service -r C:\repos" displayname= "Subversion Server" depend= Tcpip start= auto
Beachten Sie bitte auch, dass das Wort binpath
etwas irreführend ist – sein Wert ist eine Kommandozeile
und nicht der Pfad zu einem Programm. Dies ist der Grund, warum
Sie vorhandene Leerzeichen mit doppelten Anführungszeichen schützen müssen.
Ist der Dienst erstmal eingerichtet, können Sie ihn mit Hilfe von grafischen Programmen (etwa der Microsoft Management Console) stoppen, starten oder seinen Status abfragen. Alternativ steht ihnen auch die Kommandozeile zur Verfügung:
C:\> net stop svn C:\> net start svn
Der Dienst kann natürlich auch wieder deinstalliert werden, indem
Sie den Befehl sc delete svn
aufrufen.
Stoppen Sie den Dienst aber vorher!
Das Programm SC.EXE kennt noch etliche andere nützliche
Optionen und Parameter, ein Aufruf von sc /?
verrät
ihnen, welche das sind.
Wenn sich ein Subversion-Client mit einem svnserve-Prozess verbindet, geschieht folgendes:
Der Client wählt ein bestimmtes Repository.
Der Server liest die zum Repository gehörende Datei conf/svnserve.conf
und führt die darin enthaltenen Regeln für die Authentifikation (Legitimation, Identitätsprüfung)
und die Autorisation (Berechtigungen, Befugnisse) aus.
Je nach festgelegten Regeln und Einstellungen geht es mit einem der folgenden Punkte weiter:
Der Client kann seine Anfragen anonym, also ohne eine vorhergehende Authentifikationsanfrage, senden.
Der Client kann jederzeit eine Anmeldeaufforderung erhalten.
Läuft die Verbindung über einen Tunnel, so erklärt der Client, dass eine externe Anmeldung stattgefunden hat (meistens durch SSH).
Der svnserve-Server beherrscht als Standardeinstellung nur den CRAM-MD5-Anmeldedialog [40]. Im Kern läuft dieser wie folgt ab: Der Server sendet einen kleinen Datensatz als Anfrage an den Client. Dieser erzeugt mittels des MD5-Hash-Algorithmus einen Fingerprint/Hash des Passwortes zusammen mit dem Datensatz und sendet diesen Fingerprint als Antwort zurück an den Server. Der Server vollzieht nun dieselbe Operation mit dem Passwort und dem Datensatz und vergleicht anschließend seinen Fingerprint mit dem des Clients. Während des gesamten Vorgangs wird das eigentliche Passwort nie über das Netzwerk gesendet.
Enthält ihr svnserve-Server Unterstützung für SASL, so beherrscht er nicht nur die CRAM-MD5-Anmeldung, sondern noch eine Menge anderer Verfahren zur Authentifikation. Lesen Sie „Using svnserve with SASL“ weiter unten, um zu lernen, wie die einzelnen Möglichkeiten zur Authentifikation und Verschlüsselung in SASL eingerichtet werden.
Es ist selbstverständlich auch möglich, dass sich der Client über ein eigenständiges Tunnel-Programm anmeldet, etwa ssh. In einem solchem Fall stellt der Server nur fest, unter welchem Nutzerkonto er gestartet wurde, und verwendet dieses für die weitere Anmeldung. Mehr dazu im Kapitel „Tunneling over SSH“.
Wie Sie sicher bereits bemerkt haben, ist die Datei svnserve.conf
in jedem Repository die zentrale Anlaufstelle für alle Regeln im Rahmen der
Nutzeranmeldung und Rechtevergabe. Die Datei hat dasselbe Format wie die anderen
Konfigurationsdateien (siehe „Runtime Configuration Area“):
Die Abschnittsbezeichnungen sind von eckigen Klammern umschlossen
([
und ]
), Kommentare werden mit Rauten
(#
) eingeleitet, und jeder Abschnitt enthält spezielle Variablen,
denen Werte zugewiesen werden (variable = value
).
Lassen Sie uns einen Blick in diese Dateien werfen, um zu sehen wie sie verwendet werden.
Zu Beginn enthält der Abschnitt [general]
in
der Datei svnserve.conf
alle Einstellungen, welche
für den Start notwendig sind. Lassen Sie uns anfangen und den Variablen
Werte zuweisen: Wählen Sie den Namen der Datei, welche die Namen
ihrer Nutzer und deren Passwörter enthält, und entscheiden Sie sich
für den Namen der Authentifizierungsumgebung:
[general] password-db = passwortdatei realm = Anmeldedomäne
Den Namen des realm
können Sie frei wählen.
Er teilt den Clients mit, an welcher „Authentifizierungsumgebung“
sie sich anmelden. Der Subversion-Client zeigt diesen Namen im
Anmeldedialog und verwendet ihn auch (zusammen mit dem Namen und Port des Servers)
als Schlüssel, welcher als Teil des Anmeldenachweises auf der Festplatte des
Nutzers gespeichert wird
(siehe dazu „Client Credentials Caching“).
Die Variable password-db
enthält den Namen der Passwortdatei,
die vom Aufbau her gleich ist und die Namen der Nutzer und deren Passwörter speichert.
Als Beispiel:
[users] harry = geheimespasswort sally = undnocheins
Der Wert von password-db
kann
den absoluten oder relativen Pfad zur Benutzerdatei enthalten.
In der Regel, ist es am einfachsten diese Datei ebenfalls
im conf/
-Verzeichnis des Repositorys
zu speichern – also dort, wo auch svnserve.conf
liegt. Andererseits möchten Sie vielleicht eine Passwortdatei
für mehrere Repositories verwenden; in diesem Fall sollten Sie
die Datei an einem zentraleren Ort ablegen.
Die Repositorys, die sich die Benutzerdatei teilen, sollten so
konfiguriert sein, dass sie derselben Authentifizierungsumgebung
angehören, da die Benutzerliste
im Wesentlichen einen Authentifizierungs-Bereich definiert.
Wo die Datei auch liegen mag, stellen Sie sicher, die Lese-
und Schreibrechte entsprechend zu setzen. Falls Sie wissen,
unter welchem Konto svnserve laufen wird,
sollten Sie den Lesezugriff zur Benutzerdatei auf das
Notwendige beschränken.
Es sind noch zwei weitere Variablen in der Datei svnserve.conf
zu setzten: Sie legen fest, was nicht authentifizierten (anonymen)
und authentifizierten Nutzern erlaubt ist. Die Variablen
anon-access
und auth-access
können auf die Werte none
, read
oder write
gesetzt werden. Wenn Sie den Wert auf
none
setzen, so unterbinden Sie sowohl den Lese- als
auch den Schreibzugriff – read
erlaubt den Nur-Lese-Zugriff
auf das Repository und write
gibt auf das gesamte Repository
Lese- und Schreibzugriff.
[general] password-db = Benutzerdatei realm = Ihr realm # Anonyme Benutzer können nur lesend zugreifen anon-access = read # Authentifizierte Benutzer können sowohl lesen als auch schreiben auth-access = write
Tatsächlich sind die in diesem Beispiel gezeigten Einstellungen, auch die Standardwerte der Variablen, falls Sie vergessen sollten, sie zu setzten. Für den Fall, dass Sie noch zurückhaltender sein möchten, können Sie den anonymen Zugriff auch komplett unterbinden:
[general] password-db = Benutzerdatei realm = Ihr realm # Anonyme Benutzer sind nicht erlaubt anon-access = none # Authentifizierte Benutzer können sowohl lesen als auch schreiben auth-access = write
Der Serverprozess versteht nicht nur diese „pauschalen“
Zugriffseinstellungen für ein Repository, sondern auch feiner
granulierte Zugriffsrechte auf einzelne Dateien und Verzeichnisse
innerhalb des Repositories. Um diese Funktion nutzen zu können, müssen Sie eine
Datei anlegen, welche die umfangreicheren Regeln enthält und anschließend die
Variable authz-db
mit folgenden Wert setzten:
[general] password-db = Benutzerdatei realm = Ihr realm # Zum Festlegen von umfangreicheren Zugriffsregeln für bestimmte Bereiche authz-db = Auth-Datei
Wir werden die Syntax der Auth-Datei
noch später in diesem Kapitel besprechen, und zwar in
„Path-Based Authorization“. Beachten Sie,
dass die authz-db
-Variable die Verwendung der
anon-access
- und auth-access
-Variablen
nicht ausschließt – wenn alle diese Variablen gleichzeitig
gesetzt sind, so müssen auch alle diese Regeln
erfolgreich greifen, bevor ein Zugriff erlaubt wird.
For many teams, the built-in CRAM-MD5 authentication is all they need from svnserve. However, if your server (and your Subversion clients) were built with the Cyrus Simple Authentication and Security Layer (SASL) library, you have a number of authentication and encryption options available to you.
Normally, when a subversion client connects to svnserve, the server sends a greeting that advertises a list of the capabilities it supports, and the client responds with a similar list of capabilities. If the server is configured to require authentication, it then sends a challenge that lists the authentication mechanisms available; the client responds by choosing one of the mechanisms, and then authentication is carried out in some number of round-trip messages. Even when SASL capabilities aren't present, the client and server inherently know how to use the CRAM-MD5 and ANONYMOUS mechanisms (see „Integrierte Authentifikation und Autorisation“). If server and client were linked against SASL, a number of other authentication mechanisms may also be available. However, you'll need to explicitly configure SASL on the server side to advertise them.
To activate specific SASL mechanisms on the server,
you'll need to do two things. First, create
a [sasl]
section in your
repository's svnserve.conf
file with an
initial key-value pair:
[sasl] use-sasl = true
Second, create a main SASL configuration file
called svn.conf
in a place where the
SASL library can find it—typically in the directory
where SASL plug-ins are located. You'll have to locate the
plug-in directory on your particular system, such
as /usr/lib/sasl2/
or /etc/sasl2/
. (Note that this
is not
the svnserve.conf
file that lives
within a repository!)
On a Windows server, you'll also have to edit the system
registry (using a tool such as regedit)
to tell SASL where to find things. Create a registry key
named [HKEY_LOCAL_MACHINE\SOFTWARE\Carnegie
Mellon\Project Cyrus\SASL Library]
, and place two
keys inside it: a key called SearchPath
(whose value is a path to the directory containing the SASL
sasl*.dll
plug-in libraries), and a key
called
ConfFile
(whose value is a path to the
parent directory containing
the svn.conf
file you created).
Because SASL provides so many different kinds of
authentication mechanisms, it would be foolish (and far
beyond the scope of this book) to try to describe every
possible server-side configuration. Instead, we recommend
that you read the documentation supplied in the
doc/
subdirectory of the SASL source
code. It goes into great detail about every mechanism and
how to configure the server appropriately for each. For the
purposes of this discussion, we'll just demonstrate a simple
example of configuring the DIGEST-MD5 mechanism. For
example, if your subversion.conf
(or svn.conf
) file contains the
following:
pwcheck_method: auxprop auxprop_plugin: sasldb sasldb_path: /etc/my_sasldb mech_list: DIGEST-MD5
you've told SASL to advertise the DIGEST-MD5
mechanism to clients and to check user passwords against a
private password database located
at /etc/my_sasldb
. A system
administrator can then use
the saslpasswd2 program to add or modify
usernames and passwords in the database:
$ saslpasswd2 -c -f /etc/my_sasldb -u realm username
A few words of warning: first, make sure the
„realm“ argument
to saslpasswd2 matches the same realm
you've defined in your
repository's svnserve.conf
file; if
they don't match, authentication will fail. Also, due to a
shortcoming in SASL, the common realm must be a string with
no space characters. Finally, if you decide to go with the
standard SASL password database, make sure
the svnserve program has read access to
the file (and possibly write access as well, if you're using
a mechanism such as OTP).
This is just one simple way of configuring SASL. Many other authentication mechanisms are available, and passwords can be stored in other places such as in LDAP or a SQL database. Consult the full SASL documentation for details.
Remember that if you configure your server to only allow certain SASL authentication mechanisms, this forces all connecting clients to have SASL support as well. Any Subversion client built without SASL support (which includes all pre-1.5 clients) will be unable to authenticate. On the one hand, this sort of restriction may be exactly what you want („My clients must all use Kerberos!“). However, if you still want non-SASL clients to be able to authenticate, be sure to advertise the CRAM-MD5 mechanism as an option. All clients are able to use CRAM-MD5, whether they have SASL capabilities or not.
SASL is also able to perform data encryption if a
particular mechanism supports it. The built-in CRAM-MD5
mechanism doesn't support encryption, but DIGEST-MD5 does,
and mechanisms such as SRP actually require use of the
OpenSSL library. To enable or disable different levels of
encryption, you can set two values in your repository's
svnserve.conf
file:
[sasl] use-sasl = true min-encryption = 128 max-encryption = 256
The min-encryption
and
max-encryption
variables control the
level of encryption demanded by the server. To disable
encryption completely, set both values to 0. To enable
simple checksumming of data (i.e., prevent tampering and
guarantee data integrity without encryption), set both
values to 1. If you wish to allow—but not
require—encryption, set the minimum value to 0, and
the maximum value to some bit length. To require encryption
unconditionally, set both values to numbers greater than 1.
In our previous example, we require clients to do at least
128-bit encryption, but no more than 256-bit
encryption.
svnserve's built-in authentication (and SASL support) can be very handy, because it avoids the need to create real system accounts. On the other hand, some administrators already have well-established SSH authentication frameworks in place. In these situations, all of the project's users already have system accounts and the ability to „SSH into“ the server machine.
It's easy to use SSH in conjunction with
svnserve. The client simply uses the
svn+ssh://
URL scheme to connect:
$ whoami harry $ svn list svn+ssh://host.example.com/repos/project harryssh@host.example.com's password: ***** foo bar baz …
In this example, the Subversion client is invoking a local
ssh process, connecting to
host.example.com
, authenticating as the
user harryssh
(according to SSH user
configuration), then spawning a private
svnserve process on the remote machine
running as the user harryssh
. The
svnserve command is being invoked in tunnel
mode (-t
), and its network protocol is being
„tunneled“ over the encrypted connection by
ssh, the tunnel agent.
If the client performs a commit, the authenticated username
harryssh
will be used as the author
of the new revision.
The important thing to understand here is that the Subversion client is not connecting to a running svnserve daemon. This method of access doesn't require a daemon, nor does it notice one if present. It relies wholly on the ability of ssh to spawn a temporary svnserve process, which then terminates when the network connection is closed.
When using svn+ssh://
URLs to access a
repository, remember that it's the ssh
program prompting for authentication, and
not the svn client
program. That means there's no automatic password-caching
going on (see „Client Credentials Caching“). The
Subversion client often makes multiple connections to the
repository, though users don't normally notice this due to the
password caching feature. When using
svn+ssh://
URLs, however, users may be
annoyed by ssh repeatedly asking for a
password for every outbound connection. The solution is to
use a separate SSH password-caching tool such as
ssh-agent on a Unix-like system, or
pageant on Windows.
When running over a tunnel, authorization is primarily
controlled by operating system permissions to the repository's
database files; it's very much the same as if Harry were
accessing the repository directly via a
file://
URL. If multiple system users are
going to be accessing the repository directly, you may want to
place them into a common group, and you'll need to be careful
about umasks (be sure to read „Supporting Multiple Repository Access Methods“ later in this
chapter). But even in the case of tunneling, you can still use the
svnserve.conf
file to block access, by
simply setting auth-access = read
or auth-access = none
.
[41]
You'd think that the story of SSH tunneling would end
here, but it doesn't. Subversion allows you to create custom
tunnel behaviors in your runtime config
file (see „Runtime Configuration Area“.) For
example, suppose you want to use RSH instead of SSH.
[42]
In the [tunnels]
section of your
config
file, simply define it like
this:
[tunnels] rsh = rsh
And now, you can use this new tunnel definition by using a
URL scheme that matches the name of your new variable:
svn+rsh://host/path
. When using the new
URL scheme, the Subversion client will actually be running the
command rsh host svnserve -t
behind the
scenes. If you include a username in the URL (e.g.,
svn+rsh://username@host/path
), the client
will also include that in its command (rsh
username@host svnserve -t
). But you can define new
tunneling schemes to be much more clever than that:
[tunnels] joessh = $JOESSH /opt/alternate/ssh -p 29934
This example demonstrates a couple of things. First, it
shows how to make the Subversion client launch a very specific
tunneling binary (the one located at
/opt/alternate/ssh
) with specific
options. In this case, accessing an
svn+joessh://
URL would invoke the
particular SSH binary with -p 29934
as
arguments—useful if you want the tunnel program to
connect to a nonstandard port.
Second, it shows how to define a custom environment
variable that can override the name of the tunneling program.
Setting the SVN_SSH
environment variable is
a convenient way to override the default SSH tunnel agent.
But if you need to have several different overrides for
different servers, each perhaps contacting a different port or
passing a different set of options to SSH, you can use the
mechanism demonstrated in this example. Now if we were to set
the JOESSH
environment variable, its value
would override the entire value of the tunnel
variable—$JOESSH would be executed
instead of /opt/alternate/ssh -p
29934
.
It's possible to control not only the way in which the client invokes ssh, but also to control the behavior of sshd on your server machine. In this section, we'll show how to control the exact svnserve command executed by sshd, as well as how to have multiple users share a single system account.
To begin, locate the home directory of the account
you'll be using to launch svnserve. Make
sure the account has an SSH public/private keypair
installed, and that the user can log in via public-key
authentication. Password authentication will not work,
since all of the following SSH tricks revolve around using
the SSH authorized_keys
file.
If it doesn't already exist, create the
authorized_keys
file (on Unix,
typically ~/.ssh/authorized_keys
).
Each line in this file describes a public key that is
allowed to connect. The lines are typically of the
form:
ssh-dsa AAAABtce9euch… user@example.com
The first field describes the type of key, the second
field is the base64-encoded key itself, and the third field
is a comment. However, it's a lesser known fact that the
entire line can be preceded by a command
field:
command="program" ssh-dsa AAAABtce9euch… user@example.com
When the command
field is set, the
SSH daemon will run the named program instead of the
typical tunnel-mode svnserve invocation that the
Subversion client asks for. This opens the door to a number
of server-side tricks. In the following examples, we
abbreviate the lines of the file as:
command="program" TYPE KEY COMMENT
Because we can specify the executed server-side command, it's easy to name a specific svnserve binary to run and to pass it extra arguments:
command="/path/to/svnserve -t -r /virtual/root" TYPE KEY COMMENT
In this example, /path/to/svnserve
might be a custom wrapper script
around svnserve which sets the umask (see
„Supporting Multiple Repository Access Methods“.) It also
shows how to anchor svnserve in a virtual
root directory, just as one often does when
running svnserve as a daemon process.
This might be done either to restrict access to parts of the
system, or simply to relieve the user of having to type an
absolute path in the svn+ssh://
URL.
It's also possible to have multiple users share a single
account. Instead of creating a separate system account for
each user, generate a public/private key pair for each
person. Then place each public key into
the authorized_users
file, one per
line, and use the --tunnel-user
option:
command="svnserve -t --tunnel-user=harry" TYPE1 KEY1 harry@example.com command="svnserve -t --tunnel-user=sally" TYPE2 KEY2 sally@example.com
This example allows both Harry and Sally to connect to
the same account via public key authentication. Each of
them has a custom command that will be executed;
the --tunnel-user
option
tells svnserve to assume that the named
argument is the authenticated user. Without
--tunnel-user
, it would appear as though
all commits were coming from the one shared system
account.
A final word of caution: giving a user access to the
server via public-key in a shared account might still allow
other forms of SSH access, even if you've set
the command
value
in authorized_keys
. For example, the
user may still get shell access through SSH or be able to
perform X11 or general port forwarding through your server.
To give the user as little permission as possible, you may
want to specify a number of restrictive options immediately
after the command
:
command="svnserve -t --tunnel-user=harry",no-port-forwarding,no-agent-forw arding,no-X11-forwarding,no-pty TYPE1 KEY1 harry@example.com
Note that this all must be on one line—truly on
one line—since SSH authorized_keys
files do not even allow the conventional backslash character
(\
) for line continuation. The only
reason we've shown it with a line break is to fit it on
the physical page of a book.
The Apache HTTP Server is a „heavy-duty“ network server that Subversion can leverage. Via a custom module, httpd makes Subversion repositories available to clients via the WebDAV/DeltaV protocol, which is an extension to HTTP 1.1 (see http://www.webdav.org/ for more information). This protocol takes the ubiquitous HTTP protocol that is the core of the World Wide Web, and adds writing—specifically, versioned writing—capabilities. The result is a standardized, robust system that is conveniently packaged as part of the Apache 2.0 software, supported by numerous operating systems and third-party products, and doesn't require network administrators to open up yet another custom port. [43] While an Apache-Subversion server has more features than svnserve, it's also a bit more difficult to set up. With flexibility often comes more complexity.
Much of the following discussion includes references to Apache configuration directives. While some examples are given of the use of these directives, describing them in full is outside the scope of this chapter. The Apache team maintains excellent documentation, publicly available on their web site at http://httpd.apache.org. For example, a general reference for the configuration directives is located at http://httpd.apache.org/docs-2.0/mod/directives.html.
Also, as you make changes to your Apache setup, it is likely
that somewhere along the way a mistake will be made. If you are
not already familiar with Apache's logging subsystem, you should
become aware of it. In your httpd.conf
file are directives that specify the on-disk locations of the
access and error logs generated by Apache (the
CustomLog
and ErrorLog
directives, respectively).
Subversion's mod_dav_svn uses Apache's error
logging interface as well. You can always browse the contents
of those files for information that might reveal the source of a
problem that is not clearly noticeable otherwise.
To network your repository over HTTP, you basically need four components, available in two packages. You'll need Apache httpd 2.0, the mod_dav DAV module that comes with it, Subversion, and the mod_dav_svn filesystem provider module distributed with Subversion. Once you have all of those components, the process of networking your repository is as simple as:
Getting httpd 2.0 up and running with the mod_dav module
Installing the mod_dav_svn backend to mod_dav, which uses Subversion's libraries to access the repository
Configuring your httpd.conf
file to export (or expose) the repository
You can accomplish the first two items either by
compiling httpd and Subversion from
source code or by installing prebuilt binary packages of
them on your system. For the most up-to-date information on
how to compile Subversion for use with the Apache HTTP Server,
as well as how to compile and configure Apache itself for
this purpose, see the INSTALL
file in
the top level of the Subversion source code tree.
Once you have all the necessary components installed on
your system, all that remains is the configuration of Apache
via its httpd.conf
file. Instruct Apache
to load the mod_dav_svn module using the
LoadModule
directive. This directive must
precede any other Subversion-related configuration items. If
your Apache was installed using the default layout, your
mod_dav_svn module should have been
installed in the modules
subdirectory of
the Apache install location (often
/usr/local/apache2
). The
LoadModule
directive has a simple syntax,
mapping a named module to the location of a shared library on
disk:
LoadModule dav_svn_module modules/mod_dav_svn.so
Note that if mod_dav was compiled as a
shared object (instead of statically linked directly to the
httpd binary), you'll need a similar
LoadModule
statement for it, too. Be sure
that it comes before the mod_dav_svn line:
LoadModule dav_module modules/mod_dav.so LoadModule dav_svn_module modules/mod_dav_svn.so
At a later location in your configuration file, you now
need to tell Apache where you keep your Subversion repository
(or repositories). The Location
directive
has an XML-like notation, starting with an opening tag and
ending with a closing tag, with various other configuration
directives in the middle. The purpose of the
Location
directive is to instruct Apache to
do something special when handling requests that are directed
at a given URL or one of its children. In the case of
Subversion, you want Apache to simply hand off support for
URLs that point at versioned resources to the DAV layer. You
can instruct Apache to delegate the handling of all URLs whose
path portions (the part of the URL that follows the server's
name and the optional port number) begin with
/repos/
to a DAV provider whose
repository is located at
/var/svn/repository
using the
following httpd.conf
syntax:
<Location /repos> DAV svn SVNPath /var/svn/repository </Location>
If you plan to support multiple Subversion repositories
that will reside in the same parent directory on your local
disk, you can use an alternative
directive—SVNParentPath
—to
indicate that common parent directory. For example, if you
know you will be creating multiple Subversion repositories in
a directory /var/svn
that would be
accessed via URLs such as
http://my.server.com/svn/repos1
,
http://my.server.com/svn/repos2
, and so on, you
could use the httpd.conf
configuration
syntax in the following example:
<Location /svn> DAV svn # any "/svn/foo" URL will map to a repository /var/svn/foo SVNParentPath /var/svn </Location>
Using the previous syntax, Apache will delegate the
handling of all URLs whose path portions begin with
/svn/
to the Subversion DAV provider,
which will then assume that any items in the directory
specified by the SVNParentPath
directive
are actually Subversion repositories. This is a particularly
convenient syntax in that, unlike the use of the
SVNPath
directive, you don't have to
restart Apache to create and network new repositories.
Be sure that when you define your new
Location
, it doesn't overlap with other
exported locations. For example, if your main
DocumentRoot
is exported to
/www
, do not export a Subversion
repository in <Location /www/repos>
.
If a request comes in for the URI
/www/repos/foo.c
, Apache won't know
whether to look for a file repos/foo.c
in
the DocumentRoot
, or whether to delegate
mod_dav_svn to return
foo.c
from the Subversion repository.
The result is often an error from the server of the form
301 Moved Permanently
.
At this stage, you should strongly consider the question of permissions. If you've been running Apache for some time now as your regular web server, you probably already have a collection of content—web pages, scripts, and such. These items have already been configured with a set of permissions that allows them to work with Apache, or more appropriately, that allows Apache to work with those files. Apache, when used as a Subversion server, will also need the correct permissions to read and write to your Subversion repository.
You will need to determine a permission system setup that
satisfies Subversion's requirements without messing up any
previously existing web page or script installations. This
might mean changing the permissions on your Subversion
repository to match those in use by other things that Apache
serves for you, or it could mean using the
User
and Group
directives in httpd.conf
to specify that
Apache should run as the user and group that owns your
Subversion repository. There is no single correct way to set
up your permissions, and each administrator will have
different reasons for doing things a certain way. Just be
aware that permission-related problems are perhaps the most
common oversight when configuring a Subversion repository for
use with Apache.
At this point, if you configured
httpd.conf
to contain something such as the
following:
<Location /svn> DAV svn SVNParentPath /var/svn </Location>
your repository is „anonymously“
accessible to the world. Until you configure some
authentication and authorization policies, the Subversion
repositories that you make available via the
Location
directive will be generally
accessible to everyone. In other words:
Anyone can use a Subversion client to check out a working copy of a repository URL (or any of its subdirectories).
Anyone can interactively browse the repository's latest revision simply by pointing a web browser to the repository URL.
Anyone can commit to the repository.
Of course, you might have already set up
a pre-commit
hook script to prevent
commits (see „Erstellen von Repository-Hooks“).
But as you read on, you'll see that it's also possible to use
Apache's built-in methods to restrict access in specific
ways.
The easiest way to authenticate a client is via the HTTP Basic authentication mechanism, which simply uses a username and password to verify that a user is who she says she is. Apache provides an htpasswd utility for managing the list of acceptable usernames and passwords. Let's grant commit access to Sally and Harry. First, we need to add them to the password file:
$ ### First time: use -c to create the file $ ### Use -m to use MD5 encryption of the password, which is more secure $ htpasswd -cm /etc/svn-auth-file harry New password: ***** Re-type new password: ***** Adding password for user harry $ htpasswd -m /etc/svn-auth-file sally New password: ******* Re-type new password: ******* Adding password for user sally $
Next, you need to add some more
httpd.conf
directives inside your
Location
block to tell Apache what to do
with your new password file. The
AuthType
directive specifies the type of
authentication system to use. In this case, we want to
specify the Basic
authentication system.
AuthName
is an arbitrary name that you
give for the authentication domain. Most browsers will
display this name in the pop-up dialog box when the browser
is querying the user for her name and password. Finally,
use the AuthUserFile
directive to specify
the location of the password file you created using
htpasswd.
After adding these three directives, your
<Location>
block should look
something like this:
<Location /svn> DAV svn SVNParentPath /var/svn AuthType Basic AuthName "Subversion repository" AuthUserFile /etc/svn-auth-file </Location>
This <Location>
block is not
yet complete, and it will not do anything useful. It's
merely telling Apache that whenever authorization is
required, Apache should harvest a username and password from
the Subversion client. What's missing here, however, are
directives that tell Apache which sorts
of client requests require authorization. Wherever
authorization is required, Apache will demand authentication
as well. The simplest thing to do is protect all requests.
Adding Require valid-user
tells Apache
that all requests require an authenticated user:
<Location /svn> DAV svn SVNParentPath /var/svn AuthType Basic AuthName "Subversion repository" AuthUserFile /etc/svn-auth-file Require valid-user </Location>
Be sure to read the next section („Authorization Options“) for more detail on the
Require
directive and other ways to set
authorization policies.
One word of warning: HTTP Basic Auth passwords pass in very nearly plain text over the network, and thus are extremely insecure.
Another option is to not use Basic authentication, but to use Digest authentication instead. Digest authentication allows the server to verify the client's identity without passing the plain-text password over the network. Assuming that the client and server both know the user's password, they can verify that the password is the same by using it to apply a hashing function to a one-time bit of information. The server sends a small random-ish string to the client; the client uses the user's password to hash the string; the server then looks to see whether the hashed value is what it expected.
Configuring Apache for Digest authentication is also fairly easy, and only a small variation on our prior example. Be sure to consult Apache's documentation for full details.
<Location /svn> DAV svn SVNParentPath /var/svn AuthType Digest AuthName "Subversion repository" AuthDigestDomain /svn/ AuthUserFile /etc/svn-auth-file Require valid-user </Location>
If you're looking for maximum security, public key
cryptography is the best solution. It may be best to use
some sort of SSL encryption, so that clients authenticate
via https://
instead
of http://
; at a bare minimum, you can
configure Apache to use a self-signed server certificate.
[44]
Consult Apache's documentation (and OpenSSL documentation)
about how to do that.
Businesses that need to expose their repositories for access outside the company firewall should be conscious of the possibility that unauthorized parties could be „sniffing“ their network traffic. SSL makes that kind of unwanted attention less likely to result in sensitive data leaks.
If a Subversion client is compiled to use OpenSSL,
it gains the ability to speak to an Apache server via
https://
URLs. The Neon library used by
the Subversion client is not only able to verify server
certificates, but can also supply client certificates when
challenged. When the client and server have exchanged SSL
certificates and successfully authenticated one another, all
further communication is encrypted via a session key.
It's beyond the scope of this book to describe how to generate client and server certificates and how to configure Apache to use them. Many other books, including Apache's own documentation, describe this task. But what we can cover here is how to manage server and client certificates from an ordinary Subversion client.
When speaking to Apache via https://
,
a Subversion client can receive two different types of
information:
A server certificate
A demand for a client certificate
If the client receives a server certificate, it needs to verify that it trusts the certificate: is the server really who it claims to be? The OpenSSL library does this by examining the signer of the server certificate, or certificate authority (CA). If OpenSSL is unable to automatically trust the CA, or if some other problem occurs (such as an expired certificate or hostname mismatch), the Subversion command-line client will ask you whether you want to trust the server certificate anyway:
$ svn list https://host.example.com/repos/project Error validating server certificate for 'https://host.example.com:443': - The certificate is not issued by a trusted authority. Use the fingerprint to validate the certificate manually! Certificate information: - Hostname: host.example.com - Valid: from Jan 30 19:23:56 2004 GMT until Jan 30 19:23:56 2006 GMT - Issuer: CA, example.com, Sometown, California, US - Fingerprint: 7d:e1:a9:34:33:39:ba:6a:e9:a5:c4:22:98:7b:76:5c:92:a0:9c:7b (R)eject, accept (t)emporarily or accept (p)ermanently?
This dialogue should look familiar; it's essentially the
same question you've probably seen coming from your web
browser (which is just another HTTP client like Subversion).
If you choose the (p)
ermanent option, the server certificate
will be cached in your private runtime
auth/
area in just the same way your
username and password are cached (see „Client Credentials Caching“). If cached,
Subversion will automatically trust this certificate
in future negotiations.
Your runtime servers
file also gives
you the ability to make your Subversion client automatically
trust specific CAs, either globally or on a per-host basis.
Simply set the ssl-authority-files
variable to a semicolon-separated list of PEM-encoded CA
certificates:
[global] ssl-authority-files = /path/to/CAcert1.pem;/path/to/CAcert2.pem
Many OpenSSL installations also have a predefined set
of „default“ CAs that are nearly universally
trusted. To make the Subversion client automatically trust
these standard authorities, set the
ssl-trust-default-ca
variable to
true
.
When talking to Apache, a Subversion client might also receive a challenge for a client certificate. Apache is asking the client to identify itself: is the client really who it says it is? If all goes correctly, the Subversion client sends back a private certificate signed by a CA that Apache trusts. A client certificate is usually stored on disk in encrypted format, protected by a local password. When Subversion receives this challenge, it will ask you for a path to the certificate and the password that protects it:
$ svn list https://host.example.com/repos/project Authentication realm: https://host.example.com:443 Client certificate filename: /path/to/my/cert.p12 Passphrase for '/path/to/my/cert.p12': ******** …
Notice that the client certificate is a „p12“ file. To use a client certificate with Subversion, it must be in PKCS#12 format, which is a portable standard. Most web browsers are already able to import and export certificates in that format. Another option is to use the OpenSSL command-line tools to convert existing certificates into PKCS#12.
Again, the runtime servers
file
allows you to automate this challenge on a per-host basis.
Either or both pieces of information can be described in
runtime variables:
[groups] examplehost = host.example.com [examplehost] ssl-client-cert-file = /path/to/my/cert.p12 ssl-client-cert-password = somepassword
Once you've set the
ssl-client-cert-file
and
ssl-client-cert-password
variables, the
Subversion client can automatically respond to a client
certificate challenge without prompting you.
[45]
At this point, you've configured authentication, but not authorization. Apache is able to challenge clients and confirm identities, but it has not been told how to allow or restrict access to the clients bearing those identities. This section describes two strategies for controlling access to your repositories.
The simplest form of access control is to authorize certain users for either read-only access to a repository or read/write access to a repository.
You can restrict access on all repository operations by
adding the Require valid-user
directive
to your <Location>
block. Using
our previous example, this would mean that only clients that
claimed to be either harry
or
sally
and that provided the correct
password for their respective username would be allowed to
do anything with the Subversion repository:
<Location /svn> DAV svn SVNParentPath /var/svn # how to authenticate a user AuthType Basic AuthName "Subversion repository" AuthUserFile /path/to/users/file # only authenticated users may access the repository Require valid-user </Location>
Sometimes you don't need to run such a tight ship. For
example, Subversion's own source code repository at
http://svn.collab.net/repos/svn allows anyone
in the world to perform read-only repository tasks (such as
checking out working copies and browsing the repository with
a web browser), but restricts all write operations to
authenticated users. To do this type of selective
restriction, you can use the Limit
and
LimitExcept
configuration directives.
Like the Location
directive, these blocks
have starting and ending tags, and you would nest them
inside your <Location>
block.
The parameters present on the Limit
and LimitExcept
directives are HTTP
request types that are affected by that block. For example,
if you wanted to disallow all access to your repository
except the currently supported read-only operations, you
would use the LimitExcept
directive,
passing the GET
,
PROPFIND
, OPTIONS
, and
REPORT
request type parameters. Then the
previously mentioned Require valid-user
directive would be placed inside the
<LimitExcept>
block instead of just
inside the <Location>
block.
<Location /svn> DAV svn SVNParentPath /var/svn # how to authenticate a user AuthType Basic AuthName "Subversion repository" AuthUserFile /path/to/users/file # For any operations other than these, require an authenticated user. <LimitExcept GET PROPFIND OPTIONS REPORT> Require valid-user </LimitExcept> </Location>
These are only a few simple examples. For more in-depth
information about Apache access control and the
Require
directive, take a look at the
Security
section of the Apache
documentation's tutorials collection at http://httpd.apache.org/docs-2.0/misc/tutorials.html.
It's possible to set up finer-grained permissions using a second Apache httpd module, mod_authz_svn. This module grabs the various opaque URLs passing from client to server, asks mod_dav_svn to decode them, and then possibly vetoes requests based on access policies defined in a configuration file.
If you've built Subversion from source code,
mod_authz_svn is automatically built
and installed alongside mod_dav_svn.
Many binary distributions install it automatically as well.
To verify that it's installed correctly, make sure it comes
right after mod_dav_svn's
LoadModule
directive in
httpd.conf
:
LoadModule dav_module modules/mod_dav.so LoadModule dav_svn_module modules/mod_dav_svn.so LoadModule authz_svn_module modules/mod_authz_svn.so
To activate this module, you need to configure your
Location
block to use the
AuthzSVNAccessFile
directive, which
specifies a file containing the permissions policy for paths
within your repositories. (In a moment, we'll discuss the
format of that file.)
Apache is flexible, so you have the option to configure your block in one of three general patterns. To begin, choose one of these basic configuration patterns. (The following examples are very simple; look at Apache's own documentation for much more detail on Apache authentication and authorization options.)
The simplest block is to allow open access to everyone. In this scenario, Apache never sends authentication challenges, so all users are treated as „anonymous.“ (See Beispiel 6.1, „A sample configuration for anonymous access“.)
Beispiel 6.1. A sample configuration for anonymous access
<Location /repos> DAV svn SVNParentPath /var/svn # our access control policy AuthzSVNAccessFile /path/to/access/file </Location>
On the opposite end of the paranoia scale, you can
configure your block to demand authentication from everyone.
All clients must supply credentials to identify themselves.
Your block unconditionally requires authentication via the
Require valid-user
directive, and it
defines a means to authenticate. (See
Beispiel 6.2, „A sample configuration for authenticated access“.)
Beispiel 6.2. A sample configuration for authenticated access
<Location /repos> DAV svn SVNParentPath /var/svn # our access control policy AuthzSVNAccessFile /path/to/access/file # only authenticated users may access the repository Require valid-user # how to authenticate a user AuthType Basic AuthName "Subversion repository" AuthUserFile /path/to/users/file </Location>
A third very popular pattern is to allow a combination
of authenticated and anonymous access. For example, many
administrators want to allow anonymous users to read certain
repository directories, but want only authenticated users to
read (or write) more sensitive areas. In this setup, all
users start out accessing the repository anonymously. If
your access control policy demands a real username at any
point, Apache will demand authentication from the client.
To do this, use both the Satisfy Any
and Require valid-user
directives
together. (See
Beispiel 6.3, „A sample configuration for mixed
authenticated/anonymous access“.)
Beispiel 6.3. A sample configuration for mixed authenticated/anonymous access
<Location /repos> DAV svn SVNParentPath /var/svn # our access control policy AuthzSVNAccessFile /path/to/access/file # try anonymous access first, resort to real # authentication if necessary. Satisfy Any Require valid-user # how to authenticate a user AuthType Basic AuthName "Subversion repository" AuthUserFile /path/to/users/file </Location>
Once you've settled on one of these three
basic httpd.conf
templates, you need to
create your file containing access rules for particular
paths within the repository. We describe this later in
this chapter, in
„Path-Based Authorization“.
The mod_dav_svn module goes through a
lot of work to make sure that data you've marked
„unreadable“ doesn't get accidentally leaked.
This means it needs to closely monitor all of the paths
and file-contents returned by commands such as svn
checkout and svn update.
If these commands encounter a path that isn't
readable according to some authorization policy, the
path is typically omitted altogether. In the case of
history or rename tracing—for example, running a command such
as svn cat -r OLD foo.c
on a file that
was renamed long ago—the rename tracking will simply
halt if one of the object's former names is determined to be
read-restricted.
All of this path checking can sometimes be quite
expensive, especially in the case of svn
log. When retrieving a list of revisions, the
server looks at every changed path in each revision and
checks it for readability. If an unreadable path is
discovered, it's omitted from the list of the
revision's changed paths (normally seen with
the --verbose
option), and the whole log
message is suppressed. Needless to say, this can be
time-consuming on revisions that affect a large number of
files. This is the cost of security: even if you haven't
configured a module such as
mod_authz_svn at all, the
mod_dav_svn module is still asking Apache
httpd to run authorization checks on
every path. The mod_dav_svn module has
no idea what authorization modules have been installed, so
all it can do is ask Apache to invoke whatever might be
present.
On the other hand, there's also an escape hatch of
sorts, which allows you to trade security features for
speed. If you're not enforcing any sort of per-directory
authorization (i.e., not using
mod_authz_svn or similar module),
you can disable all of this path checking. In your
httpd.conf
file, use the
SVNPathAuthz
directive as shown in
Beispiel 6.4, „Disabling path checks altogether“.
Beispiel 6.4. Disabling path checks altogether
<Location /repos> DAV svn SVNParentPath /var/svn SVNPathAuthz off </Location>
The SVNPathAuthz
directive
is „on“ by default. When
set to „off,“ all path-based authorization
checking is disabled;
mod_dav_svn stops invoking authorization
checks on every path it discovers.
We've covered most of the authentication and authorization options for Apache and mod_dav_svn. But there are a few other nice features that Apache provides.
One of the most useful benefits of an Apache/WebDAV
configuration for your Subversion repository is that the
youngest revisions of your versioned files and directories
are immediately available for viewing via a regular web
browser. Since Subversion uses URLs to identify versioned
resources, those URLs used for HTTP-based repository access
can be typed directly into a web browser. Your browser will
issue an HTTP GET
request for that URL;
based on whether that URL represents a versioned directory
or file, mod_dav_svn will respond with a
directory listing or with file contents.
Since the URLs do not contain any information about which version of the resource you wish to see, mod_dav_svn will always answer with the youngest version. This functionality has the wonderful side effect that you can pass around Subversion URLs to your peers as references to documents, and those URLs will always point at the latest manifestation of that document. Of course, you can even use the URLs as hyperlinks from other web sites, too.
When browsing a Subversion repository, the web browser
gets a clue about how to render a file's contents by
looking at the Content-Type:
header
returned in Apache's response to the
HTTP GET
request. The value of this
header is some sort of MIME type. By default, Apache will
tell the web browsers that all repository files are of
the „default“ MIME type,
typically text/plain
. This can be
frustrating, however, if a user wishes repository files to
render as something more meaningful—for example,
it might be nice to have a foo.html
file
in the repository actually render as HTML when
browsing.
To make this happen, you need only to make sure that
your files have the
proper svn:mime-type
set. We discuss this
in more detail in
„File Content Type“,
and you can even configure your client to automatically
attach proper svn:mime-type
properties
to files entering the repository for the first time; see
„Automatic Property Setting“.
So in our example, if one were to set
the svn:mime-type
property
to text/html
on
file foo.html
, Apache would
properly tell your web browser to render the file as HTML.
One could also attach proper image/*
MIME-type properties to image files and ultimately get an
entire web site to be viewable directly from a repository!
There's generally no problem with this, as long as the web
site doesn't contain any dynamically generated
content.
You generally will get more use out of URLs to
versioned files—after all, that's where the
interesting content tends to lie. But you might have
occasion to browse a Subversion directory listing, where
you'll quickly note that the generated HTML used to
display that listing is very basic, and certainly not
intended to be aesthetically pleasing (or even
interesting). To enable customization of these directory
displays, Subversion provides an XML index feature. A
single SVNIndexXSLT
directive in your
repository's Location
block of
httpd.conf
will
instruct mod_dav_svn to generate XML
output when displaying a directory listing, and to
reference the XSLT stylesheet of your choice:
<Location /svn> DAV svn SVNParentPath /var/svn SVNIndexXSLT "/svnindex.xsl" … </Location>
Using the SVNIndexXSLT
directive and
a creative XSLT stylesheet, you can make your directory
listings match the color schemes and imagery used in other
parts of your web site. Or, if you'd prefer, you can use
the sample stylesheets provided in the Subversion source
distribution's tools/xslt/
directory.
Keep in mind that the path provided to the
SVNIndexXSLT
directory is actually a URL
path—browsers need to be able to read your
stylesheets to make use of them!
If you're serving a collection of repositories from a
single URL via the SVNParentPath
directive, then it's also possible to have Apache display
all available repositories to a web browser. Just
activate the SVNListParentPath
directive:
<Location /svn> DAV svn SVNParentPath /var/svn SVNListParentPath on … </Location>
If a user now points her web browser to the
URL http://host.example.com/svn/
, she'll
see a list of all Subversion repositories sitting
in /var/svn
. Obviously, this can
be a security problem, so this feature is turned off by
default.
Because Apache is an HTTP server at heart, it contains
fantastically flexible logging features. It's beyond the
scope of this book to discuss all of the ways logging can be
configured, but we should point out that even the most
generic httpd.conf
file will cause
Apache to produce two logs:
error_log
and access_log
. These logs may appear
in different places, but are typically created in the
logging area of your Apache installation. (On Unix, they
often live
in /usr/local/apache2/logs/
.)
The error_log
describes any internal
errors that Apache runs into as it works.
The access_log
file records every
incoming HTTP request received by Apache. This makes it
easy to see, for example, which IP addresses Subversion
clients are coming from, how often particular clients use
the server, which users are authenticating properly, and
which requests succeed or fail.
Unfortunately, because HTTP is a stateless protocol,
even the simplest Subversion client operation generates
multiple network requests. It's very difficult to look at
the access_log
and deduce what the
client was doing—most operations look like a series
of cryptic PROPPATCH
, GET
,
PUT
, and REPORT
requests. To make things worse, many client operations send
nearly identical series of requests, so it's even harder to
tell them apart.
mod_dav_svn, however, can come to your aid. By activating an „operational logging“ feature, you can ask mod_dav_svn to create a separate log file describing what sort of high-level operations your clients are performing.
To do this, you need to make use of
Apache's CustomLog
directive (which is
explained in more detail in Apache's own documentation).
Be sure to invoke this
directive outside your
Subversion Location
block:
<Location /svn> DAV svn … </Location> CustomLog logs/svn_logfile "%t %u %{SVN-ACTION}e" env=SVN-ACTION
In this example, we're asking Apache to create a special
logfile, svn_logfile
, in the standard
Apache logs
directory.
The %t
and %u
variables are replaced by the time and username of the
request, respectively. The really important parts are the
two instances of SVN-ACTION
.
When Apache sees that variable, it substitutes the value of
the SVN-ACTION
environment variable,
which is automatically set by mod_dav_svn
whenever it detects a high-level client action.
So, instead of having to interpret a
traditional access_log
like
this:
[26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc/!svn/vcc/default HTTP/1.1" 207 398 [26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc/!svn/bln/59 HTTP/1.1" 207 449 [26/Jan/2007:22:25:29 -0600] "PROPFIND /svn/calc HTTP/1.1" 207 647 [26/Jan/2007:22:25:29 -0600] "REPORT /svn/calc/!svn/vcc/default HTTP/1.1" 200 607 [26/Jan/2007:22:25:31 -0600] "OPTIONS /svn/calc HTTP/1.1" 200 188 [26/Jan/2007:22:25:31 -0600] "MKACTIVITY /svn/calc/!svn/act/e6035ef7-5df0-4ac0-b811-4be7c823f998 HTTP/1.1" 201 227 …
you can peruse a much more
intelligible svn_logfile
like
this:
[26/Jan/2007:22:24:20 -0600] - get-dir /tags r1729 props [26/Jan/2007:22:24:27 -0600] - update /trunk r1729 depth=infinity send-copyfrom-args [26/Jan/2007:22:25:29 -0600] - status /trunk/foo r1729 depth=infinity [26/Jan/2007:22:25:31 -0600] sally commit r1730
For an exhaustive list of all actions logged, see „High-level logging“.
One of the nice advantages of using Apache as a Subversion server is that it can be set up for simple replication. For example, suppose that your team is distributed across four offices around the globe. The Subversion repository can exist only in one of those offices, which means the other three offices will not enjoy accessing it—they're likely to experience significantly slower traffic and response times when updating and committing code. A powerful solution is to set up a system consisting of one master Apache server and several slave Apache servers. If you place a slave server in each office, users can check out a working copy from whichever slave is closest to them. All read requests go to their local slave. Write requests get automatically routed to the single master server. When the commit completes, the master then automatically „pushes“ the new revision to each slave server using the svnsync replication tool.
This configuration creates a huge perceptual speed increase for your users, because Subversion client traffic is typically 80–90% read requests. And if those requests are coming from a local server, it's a huge win.
In this section, we'll walk you through a standard setup of this single-master/multiple-slave system. However, keep in mind that your servers must be running at least Apache 2.2.0 (with mod_proxy loaded) and Subversion 1.5 (mod_dav_svn).
First, configure your master server's
httpd.conf
file in the usual way.
Make the repository available at a certain URI location,
and configure authentication and authorization however
you'd like. After that's done, configure each of your
„slave“ servers in the exact same way, but
add the special SVNMasterURI
directive
to the block:
<Location /svn> DAV svn SVNPath /var/svn/repos SVNMasterURI http://master.example.com/svn … </Location>
This new directive tells a slave server to redirect all write requests to the master. (This is done automatically via Apache's mod_proxy module.) Ordinary read requests, however, are still serviced by the slaves. Be sure that your master and slave servers all have matching authentication and authorization configurations; if they fall out of sync, it can lead to big headaches.
Next, we need to deal with the problem of infinite recursion. With the current configuration, imagine what will happen when a Subversion client performs a commit to the master server. After the commit completes, the server uses svnsync to replicate the new revision to each slave. But because svnsync appears to be just another Subversion client performing a commit, the slave will immediately attempt to proxy the incoming write request back to the master! Hilarity ensues.
The solution to this problem is to have the master
push revisions to a different
<Location>
on the slaves. This
location is configured to not proxy
write requests at all, but to accept normal commits from
(and only from) the master's IP address:
<Location /svn-proxy-sync> DAV svn SVNPath /var/svn/repos Order deny,allow Deny from all # Only let the server's IP address access this Location: Allow from 10.20.30.40 … </Location>
Now that you've configured
your Location
blocks on master and
slaves, you need to configure the master to replicate to
the slaves. This is done the usual way—
using svnsync. If you're not familiar
with this tool, see
„Repository Replication“ for
details.
First, make sure that each slave repository has a
pre-revprop-change
hook script which
allows remote revision property changes. (This is
standard procedure for being on the receiving end of
svnsync.) Then log into the master
server and configure each of the slave repository URIs to
receive data from the master repository on the local
disk:
$ svnsync init http://slave1.example.com/svn-proxy-sync file://var/svn/repos Copied properties for revision 0. $ svnsync init http://slave2.example.com/svn-proxy-sync file://var/svn/repos Copied properties for revision 0. $ svnsync init http://slave3.example.com/svn-proxy-sync file://var/svn/repos Copied properties for revision 0. # Perform the initial replication $ svnsync sync http://slave1.example.com/svn-proxy-sync Transmitting file data .... Committed revision 1. Copied properties for revision 1. Transmitting file data ....... Committed revision 2. Copied properties for revision 2. … $ svnsync sync http://slave2.example.com/svn-proxy-sync Transmitting file data .... Committed revision 1. Copied properties for revision 1. Transmitting file data ....... Committed revision 2. Copied properties for revision 2. … $ svnsync sync http://slave3.example.com/svn-proxy-sync Transmitting file data .... Committed revision 1. Copied properties for revision 1. Transmitting file data ....... Committed revision 2. Copied properties for revision 2. …
After this is done, we configure the master server's
post-commit
hook script to invoke
svnsync on each slave server:
#!/bin/sh # Post-commit script to replicate newly committed revision to slaves svnsync sync http://slave1.example.com/svn-proxy-sync > /dev/null 2>&1 svnsync sync http://slave2.example.com/svn-proxy-sync > /dev/null 2>&1 svnsync sync http://slave3.example.com/svn-proxy-sync > /dev/null 2>&1
The extra bits on the end of each line aren't
necessary, but they're a sneaky way to allow the sync
commands to run in the background so that the Subversion
client isn't left waiting forever for the commit to
finish. In addition to this
post-commit
hook, you'll need a
post-revprop-change
hook as well so
that when a user, say, modifies a log message, the slave
servers get that change also:
#!/bin/sh # Post-revprop-change script to replicate revprop-changes to slaves REV=${2} svnsync copy-revprops http://slave1.example.com/svn-proxy-sync ${REV} > /dev/null 2>&1 svnsync copy-revprops http://slave2.example.com/svn-proxy-sync ${REV} > /dev/null 2>&1 svnsync copy-revprops http://slave3.example.com/svn-proxy-sync ${REV} > /dev/null 2>&1
The only thing we've left out here is what to do about
locks. Because locks are strictly enforced by the master
server (the only place where commits happen), we don't
technically need to do anything. Many teams don't use
Subversion's locking features at all, so it may be a
nonissue for you. However, if lock changes aren't
replicated from master to slaves, it means that clients
won't be able to query the status of locks
(e.g., svn status -u
will show no
information about repository locks). If this bothers you,
you can write post-lock
and
post-unlock
hook scripts that run
svn lock and svn
unlock on each slave machine, presumably through
a remote shell method such as SSH. That's left as an
exercise for the reader!
Your master/slave replication system should now be ready to use. A couple of words of warning are in order, however. Remember that this replication isn't entirely robust in the face of computer or network crashes. For example, if one of the automated svnsync commands fails to complete for some reason, the slaves will begin to fall behind. For example, your remote users will see that they've committed revision 100, but then when they run svn update, their local server will tell them that revision 100 doesn't yet exist! Of course, the problem will be automatically fixed the next time another commit happens and the subsequent svnsync is successful—the sync will replicate all waiting revisions. But still, you may want to set up some sort of out-of-band monitoring to notice synchronization failures and force svnsync to run when things go wrong.
Several of the features already provided by Apache in
its role as a robust web server can be leveraged for
increased functionality or security in Subversion as well.
The Subversion client is able to use SSL (the Secure Sockets
Layer, discussed earlier). If your Subversion client is
built to support SSL, it can access your Apache server
using https://
and enjoy a high-quality
encrypted network session.
Equally useful are other features of the Apache and Subversion relationship, such as the ability to specify a custom port (instead of the default HTTP port 80) or a virtual domain name by which the Subversion repository should be accessed, or the ability to access the repository through an HTTP proxy.
Finally, because mod_dav_svn is speaking a subset of the WebDAV/DeltaV protocol, it's possible to access the repository via third-party DAV clients. Most modern operating systems (Win32, OS X, and Linux) have the built-in ability to mount a DAV server as a standard network „shared folder.“ This is a complicated topic, but also wondrous when implemented. For details, read Anhang C, WebDAV and Autoversioning.
Note that there are a number of other small tweaks one can
make to mod_dav_svn that are too obscure
to mention in this chapter. For a complete list of
all httpd.conf
directives
that mod_dav_svn responds to, see
„Directives“.
Both Apache and svnserve are capable of granting (or denying) permissions to users. Typically this is done over the entire repository: a user can read the repository (or not), and she can write to the repository (or not). It's also possible, however, to define finer-grained access rules. One set of users may have permission to write to a certain directory in the repository, but not others; another directory might not even be readable by all but a few special people.
Both servers use a common file format to describe these
path-based access rules. In the case of Apache, one needs to
load the mod_authz_svn module and then add
the AuthzSVNAccessFile
directive (within
the httpd.conf
file) pointing to your own
rules file. (For a full explanation, see
„Per-directory access control“.) If
you're using svnserve, you need to make
the authz-db
variable
(within svnserve.conf
) point to your
rules file.
Once your server knows where to find your rules file, it's time to define the rules.
The syntax of the file is the same familiar one used
by svnserve.conf
and the runtime
configuration files. Lines that start with a hash
(#
) are ignored. In its simplest form, each
section names a repository and path within it, as well as the
authenticated usernames are the option names within each
section. The value of each option describes the user's level of
access to the repository path: either
r
(read-only) or rw
(read/write). If the user is not mentioned at all, no access is
allowed.
To be more specific: the value of the section names is
either of the form [repos-name:path]
or of the
form [path]
. If you're using the
SVNParentPath
directive, it's important
to specify the repository names in your sections. If you omit
them, a section such as
[/some/dir]
will match the path
/some/dir
in every
repository. If you're using the SVNPath
directive, however, it's fine to only define paths in your
sections—after all, there's only one repository.
[calc:/branches/calc/bug-142] harry = rw sally = r
In this first example, the user harry
has
full read and write access on the
/branches/calc/bug-142
directory in the
calc
repository, but the user
sally
has read-only access. Any other users
are blocked from accessing this directory.
Of course, permissions are inherited from parent to child directory. That means we can specify a subdirectory with a different access policy for Sally:
[calc:/branches/calc/bug-142] harry = rw sally = r # give sally write access only to the 'testing' subdir [calc:/branches/calc/bug-142/testing] sally = rw
Now Sally can write to the testing
subdirectory of the branch, but can still only read other parts.
Harry, meanwhile, continues to have complete read/write access
to the whole branch.
It's also possible to explicitly deny permission to someone via inheritance rules, by setting the username variable to nothing:
[calc:/branches/calc/bug-142] harry = rw sally = r [calc:/branches/calc/bug-142/secret] harry =
In this example, Harry has read/write access to the
entire bug-142
tree, but has absolutely no
access at all to the secret
subdirectory
within it.
The thing to remember is that the most specific path always matches first. The server tries to match the path itself, and then the parent of the path, then the parent of that, and so on. The net effect is that mentioning a specific path in the access file will always override any permissions inherited from parent directories.
By default, nobody has any access to the repository at all.
That means that if you're starting with an empty file, you'll
probably want to give at least read permission to all users at
the root of the repository. You can do this by using the
asterisk variable (*
), which means „all
users“:
[/] * = r
This is a common setup; notice that no repository
name is mentioned in the section name. This makes all repositories
world-readable to all users. Once all users have read access to
the repositories, you can give explicit
rw
permission to certain users on specific
subdirectories within specific repositories.
The asterisk variable (*
) is also worth
special mention because it's the
only pattern that matches an anonymous
user. If you've configured your server block to allow a mixture
of anonymous and authenticated access, all users start out
accessing anonymously. The server looks for a
*
value defined for the path being accessed;
if it can't find one, it demands real authentication from
the client.
The access file also allows you to define whole groups of
users, much like the Unix /etc/group
file:
[groups] calc-developers = harry, sally, joe paint-developers = frank, sally, jane everyone = harry, sally, joe, frank, sally, jane
Groups can be granted access control just like users.
Distinguish them with an „at“
(@
) prefix:
[calc:/projects/calc] @calc-developers = rw [paint:/projects/paint] jane = r @paint-developers = rw
Another important fact is that
the first matching rule is the one which gets
applied to a user. In the prior example, even though Jane is a
member of the paint-developers
group (which has
read/write access), the jane = r
rule will be
discovered and matched before the group rule, thus denying Jane
write access.
Groups can also be defined to contain other groups:
[groups] calc-developers = harry, sally, joe paint-developers = frank, sally, jane everyone = @calc-developers, @paint-developers
Subversion 1.5 brings another useful feature to the access
file syntax: username aliases. Some authentication systems
expect and carry relatively short usernames of the sorts we've
been describing here—harry
,
sally
, joe
, and so on. But
other authentication systems—such as those which use LDAP
stores or SSL client certificates—may carry much more
complex usernames. For example, Harry's username in an
LDAP-protected system might be CN=Harold
Hacker,OU=Engineers,DC=red-bean,DC=com
. With
usernames like that, the access file can become quite bloated
with long or obscure usernames that are easy to mistype.
Fortunately, username aliases allow you to have to type the
correct complex username only once, in a statement which assigns to
it a more easily digestable alias.
[aliases] harry = CN=Harold Hacker,OU=Engineers,DC=red-bean,DC=com sally = CN=Sally Swatterbug,OU=Engineers,DC=red-bean,DC=com joe = CN=Gerald I. Joseph,OU=Engineers,DC=red-bean,DC=com …
Once you've defined a set of aliases, you can refer to the users elsewhere in the access file via their aliases in all the same places you could have instead used their actual usernames. Simply prepend an ampersand to the alias to distinguish it from a regular username:
[groups] calc-developers = &harry, &sally, &joe paint-developers = &frank, &sally, &jane everyone = @calc-developers, @paint-developers
You might also choose to use aliases if your users' usernames change frequently. Doing so allows you to need to update only the aliases table when these username changes occur, instead of doing global-search-and-replace operations on the whole access file.
You've seen how a repository can be accessed in many different ways. But is it possible—or safe—for your repository to be accessed by multiple methods simultaneously? The answer is yes, provided you use a bit of foresight.
At any given time, these processes may require read and write access to your repository:
Regular system users using a Subversion client (as
themselves) to access the repository directly via
file://
URLs
Regular system users connecting to SSH-spawned private svnserve processes (running as themselves), which access the repository
An svnserve process—either a daemon or one launched by inetd—running as a particular fixed user
An Apache httpd process, running as a particular fixed user
The most common problem administrators run into is
repository ownership and permissions. Does every process (or
user) in the preceding list have the rights to read and write the
repository's underlying data files? Assuming you have a
Unix-like operating system, a straightforward approach might be
to place every potential repository user into a
new svn
group, and make the repository wholly
owned by that group. But even that's not enough, because a
process may write to the database files using an unfriendly
umask—one that prevents access by other users.
So the next step beyond setting up a common group for
repository users is to force every repository-accessing process
to use a sane umask. For users accessing the repository
directly, you can make the svn program into a
wrapper script that first runs umask 002
and
then runs the real svn client program. You
can write a similar wrapper script for the
svnserve program, and add a umask
002
command to Apache's own startup script,
apachectl
. For example:
$ cat /usr/bin/svn #!/bin/sh umask 002 /usr/bin/svn-real "$@"
Another common problem is often encountered on Unix-like
systems. If your repository is backed by Berkeley DB, for
example, it occasionally creates new log files to journal its
actions. Even if the Berkeley DB repository is wholly owned by
the svn group, these newly created log files
won't necessarily be owned by that same group, which then
creates more permissions problems for your users. A good
workaround is to set the group SUID bit on the
repository's db
directory. This causes all
newly created log files to have the same group owner as the
parent directory.
Once you've jumped through these hoops, your repository should be accessible by all the necessary processes. It may seem a bit messy and complicated, but the problems of having multiple users sharing write access to common files are classic ones that are not often elegantly solved.
Fortunately, most repository administrators will never
need to have such a complex configuration.
Users who wish to access repositories that live on the same
machine are not limited to using file://
access URLs—they can typically contact the Apache HTTP
server or svnserve using
localhost
for the server name in their
http://
or svn://
URL.
And maintaining multiple server processes for your Subversion
repositories is likely to be more of a headache than necessary.
We recommend that you choose a single server that best meets your
needs and stick with it!
[40] See RFC 2195.
[41] Note that using any sort of svnserve-enforced access control at all is a bit pointless; the user already has direct access to the repository database.
[42] We don't actually recommend this, since RSH is notably less secure than SSH.
[43] They really hate doing that.
[44] While self-signed server certificates are still vulnerable to a „man-in-the-middle“ attack, such an attack is much more difficult for a casual observer to pull off, compared to sniffing unprotected passwords.
[45] More security-conscious folk might not want to store
the client certificate password in the runtime
servers
file.
[46] Back then, it was called ViewCVS.
[47] A common theme in this book!
Inhaltsverzeichnis
Version control can be a complex subject, as much art as science, that offers myriad ways of getting stuff done. Throughout this book, you've read of the various Subversion command-line client subcommands and the options that modify their behavior. In this chapter, we'll look into still more ways to customize the way Subversion works for you—setting up the Subversion runtime configuration, using external helper applications, Subversion's interaction with the operating system's configured locale, and so on.
Subversion provides many optional behaviors that the user can control. Many of these options are of the kind that a user would wish to apply to all Subversion operations. So, rather than forcing users to remember command-line arguments for specifying these options and to use them for every operation they perform, Subversion uses configuration files, segregated into a Subversion configuration area.
The Subversion configuration area is a two-tiered hierarchy of option names and their values. Usually, this boils down to a special directory that contains configuration files (the first tier), which are just text files in standard INI format (with „sections“ providing the second tier). You can easily edit these files using your favorite text editor (such as Emacs or vi), and they contain directives read by the client to determine which of several optional behaviors the user prefers.
The first time the svn
command-line client is executed, it creates a per-user
configuration area. On Unix-like systems, this area appears
as a directory named .subversion
in the
user's home directory. On Win32 systems, Subversion creates a
folder named Subversion
, typically inside
the Application Data
area of the user's
profile directory (which, by the way, is usually a hidden
directory). However, on this platform, the exact location
differs from system to system and is dictated by the Windows
Registry.
[48]
We will refer to the per-user configuration area using its Unix
name, .subversion
.
In addition to the per-user configuration area, Subversion
also recognizes the existence of a system-wide configuration
area. This gives system administrators the ability to
establish defaults for all users on a given machine. Note
that the system-wide configuration area alone does not dictate
mandatory policy—the settings in the per-user
configuration area override those in the system-wide one, and
command-line arguments supplied to the svn
program have the final word on behavior. On Unix-like
platforms, the system-wide configuration area is
expected to be the /etc/subversion
directory; on Windows machines, it looks for a
Subversion
directory inside the common
Application Data
location (again, as
specified by the Windows Registry). Unlike the per-user
case, the svn program does not attempt
to create the system-wide configuration area.
The per-user configuration area currently contains three
files—two configuration files (config
and
servers
), and a README.txt
file, which describes the INI format. At the time of their
creation, the files contain default values for each of the
supported Subversion options, mostly commented out and grouped
with textual descriptions about how the values for the key
affect Subversion's behavior. To change a certain behavior,
you need only to load the appropriate configuration file into
a text editor, and to modify the desired option's value. If at
any time you wish to have the default configuration settings
restored, you can simply remove (or rename) your configuration
directory and then run some innocuous svn
command, such as svn --version
. A new
configuration directory with the default contents will be
created.
The per-user configuration area also contains a cache of
authentication data. The auth
directory
holds a set of subdirectories that contain pieces of cached
information used by Subversion's various supported
authentication methods. This directory is created in such a
way that only the user herself has permission to read its
contents.
In addition to the usual INI-based configuration area, Subversion clients running on Windows platforms may also use the Windows Registry to hold the configuration data. The option names and their values are the same as in the INI files. The „file/section“ hierarchy is preserved as well, though addressed in a slightly different fashion—in this schema, files and sections are just levels in the Registry key tree.
Subversion looks for system-wide configuration values
under the
HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion
key. For example, the global-ignores
option,
which is in the miscellany
section of the
config
file, would be found at
HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores
.
Per-user configuration values should be stored under
HKEY_CURRENT_USER\Software\Tigris.org\Subversion
.
Registry-based configuration options are parsed before their file-based counterparts, so they are overridden by values found in the configuration files. In other words, Subversion looks for configuration information in the following locations on a Windows system; lower-numbered locations take precedence over higher-numbered locations:
Command-line options
The per-user INI files
The per-user Registry values
The system-wide INI files
The system-wide Registry values
Also, the Windows Registry doesn't really support the
notion of something being „commented out.“
However, Subversion will ignore any option key whose name
begins with a hash (#
) character. This
allows you to effectively comment out a Subversion option
without deleting the entire key from the Registry, obviously
simplifying the process of restoring that option.
The svn command-line client never
attempts to write to the Windows Registry and will not attempt
to create a default configuration area there. You can create
the keys you need using the REGEDIT
program. Alternatively, you can create a
.reg
file (such as the one in Beispiel 7.1, „Sample registration entries (.reg) file“), and
then double-click on that file's icon in the Explorer shell,
which will cause the data to be merged into your
Registry.
Beispiel 7.1. Sample registration entries (.reg) file
REGEDIT4 [HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\groups] [HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\global] "#http-proxy-host"="" "#http-proxy-port"="" "#http-proxy-username"="" "#http-proxy-password"="" "#http-proxy-exceptions"="" "#http-timeout"="0" "#http-compression"="yes" "#neon-debug-mask"="" "#ssl-authority-files"="" "#ssl-trust-default-ca"="" "#ssl-client-cert-file"="" "#ssl-client-cert-password"="" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth] "#store-passwords"="yes" "#store-auth-creds"="yes" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers] "#editor-cmd"="notepad" "#diff-cmd"="" "#diff3-cmd"="" "#diff3-has-program-arg"="" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels] [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany] "#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store" "#log-encoding"="" "#use-commit-times"="" "#no-unlock"="" "#enable-auto-props"="" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
The previous example shows the contents of a
.reg
file, which contains some of the most
commonly used configuration options and their default values.
Note the presence of both system-wide (for network
proxy-related options) and per-user settings (editor programs
and password storage, among others). Also note that all the
options are effectively commented out. You need only to
remove the hash (#
) character from the
beginning of the option names and set the values as you
desire.
In this section, we will discuss the specific runtime configuration options that Subversion currently supports.
The servers
file contains
Subversion configuration options related to the network
layers. There are two special section names in this
file—groups
and
global
. The groups
section is essentially a cross-reference table. The keys in
this section are the names of other sections in the file;
their values are globs—textual
tokens that possibly contain wildcard
characters—that are compared against the hostnames of
the machine to which Subversion requests are sent.
[groups] beanie-babies = *.red-bean.com collabnet = svn.collab.net [beanie-babies] … [collabnet] …
When Subversion is used over a network, it attempts to
match the name of the server it is trying to reach with a
group name under the groups
section. If
a match is made, Subversion then looks for a section in the
servers
file whose name is the matched
group's name. From that section, it reads the actual network
configuration settings.
The global
section contains the
settings that are meant for all of the servers not matched
by one of the globs under the groups
section. The options available in this section are
exactly the same as those that are valid for the other server
sections in the file (except, of course, the special
groups
section), and are as
follows:
http-proxy-exceptions
This specifies a comma-separated list of patterns for repository hostnames that should be accessed directly, without using the proxy machine. The pattern syntax is the same as is used in the Unix shell for filenames. A repository hostname matching any of these patterns will not be proxied.
http-proxy-host
This specifies the hostname of the proxy computer through which your HTTP-based Subversion requests must pass. It defaults to an empty value, which means that Subversion will not attempt to route HTTP requests through a proxy computer, and will instead attempt to contact the destination machine directly.
http-proxy-port
This specifies the port number on the proxy host to use. It defaults to an empty value.
http-proxy-username
This specifies the username to supply to the proxy machine. It defaults to an empty value.
http-proxy-password
This specifies the password to supply to the proxy machine. It defaults to an empty value.
http-timeout
This specifies the amount of time, in seconds, to
wait for a server response. If you experience
problems with a slow network connection causing
Subversion operations to time out, you should increase
the value of this option. The default value is
0
, which instructs the underlying
HTTP library, Neon, to use its default timeout
setting.
http-compression
This specifies whether Subversion should
attempt to compress network requests made to DAV-ready
servers. The default value is yes
(though compression will occur only if that capability
is compiled into the network layer). Set this to
no
to disable compression, such as
when debugging network transmissions.
http-library
Subversion provides a pair of repository access
modules that understand its WebDAV network protocol.
The original one, which shipped with Subversion 1.0, is
libsvn_ra_neon
(though back then it
was called libsvn_ra_dav
). Newer
Subversion versions also provide
libsvn_ra_serf
, which uses a
different underlying implementation and aims to
support some of the newer HTTP concepts.
At this point, libsvn_ra_serf
is still considered experimental, though it appears to
work in the common cases quite well. To encourage
experimentation, Subversion provides the
http-library
runtime configuration
option to allow users to specify (generally, or in a
per-server-group fashion) which WebDAV access module
they'd prefer to use—neon
or
serf
.
http-auth-types
This option is a semicolon-delimited list of
authentication types supported by the Neon-based
WebDAV repository access modules. Valid members of
this list are basic
,
digest
, and
negotiate
.
neon-debug-mask
This is an integer mask that the underlying HTTP
library, Neon, uses for choosing what type of
debugging output to yield. The default value is
0
, which will silence all debugging
output. For more information about how Subversion
makes use of Neon, see Kapitel 8, Embedding Subversion.
ssl-authority-files
This is a semicolon-delimited list of paths to files containing certificates of the certificate authorities (or CAs) that are accepted by the Subversion client when accessing the repository over HTTPS.
ssl-trust-default-ca
Set this variable to yes
if you
want Subversion to automatically trust the set of
default CAs that ship with OpenSSL.
ssl-client-cert-file
If a host (or set of hosts) requires an SSL client certificate, you'll normally be prompted for a path to your certificate. By setting this variable to that same path, Subversion will be able to find your client certificate automatically without prompting you. There's no standard place to store your certificate on disk; Subversion will grab it from any path you specify.
ssl-client-cert-password
If your SSL client certificate file is encrypted
by a passphrase, Subversion will prompt you for the
passphrase whenever the certificate is used. If you
find this annoying (and don't mind storing the
password in the servers
file),
you can set this variable to the certificate's
passphrase. You won't be prompted anymore.
The config
file contains the rest
of the currently available Subversion runtime
options—those not related to networking. There are
only a few options in use as of this writing, but they are
again grouped into sections in expectation of future
additions.
The auth
section contains settings
related to Subversion's authentication and authorization
against the repository. It contains the following:
store-passwords
This instructs Subversion to cache, or not to
cache, passwords that are supplied by the user in
response to server authentication challenges. The
default value is yes
. Set this to
no
to disable this on-disk password
caching. You can override this option for a single
instance of the svn command using
the --no-auth-cache
command-line
parameter (for those subcommands that support it).
For more information, see „Client Credentials Caching“.
store-auth-creds
This setting is the same as
store-passwords
, except that it
enables or disables on-disk caching of
all authentication information:
usernames, passwords, server certificates, and any
other types of cacheable credentials.
The helpers
section controls which
external applications Subversion uses to accomplish its
tasks. Valid options in this section are:
editor-cmd
This specifies the program Subversion will use to query the user for certain types of textual metadata or when interactively resolving conflicts. See „Using External Editors“ for more details on using external text editors with Subversion.
diff-cmd
This specifies the absolute path of a differencing program, used when Subversion generates „diff“ output (such as when using the svn diff command). By default, Subversion uses an internal differencing library—setting this option will cause it to perform this task using an external program. See „Using External Differencing and Merge Tools“ for more details on using such programs.
diff3-cmd
This specifies the absolute path of a three-way differencing program. Subversion uses this program to merge changes made by the user with those received from the repository. By default, Subversion uses an internal differencing library—setting this option will cause it to perform this task using an external program. See „Using External Differencing and Merge Tools“ for more details on using such programs.
diff3-has-program-arg
This flag should be set to true
if the program specified by the
diff3-cmd
option accepts a
--diff-program
command-line
parameter.
merge-tool-cmd
This specifies the program that Subversion will use to perform three-way merge operations on your versioned files. See „Using External Differencing and Merge Tools“ for more details on using such programs.
The tunnels
section allows you to
define new tunnel schemes for use with
svnserve and svn://
client connections. For more details, see „Tunneling over SSH“.
The miscellany
section is where
everything that doesn't belong elsewhere winds up.
[49]
In this section, you can find:
global-ignores
When running the svn status
command, Subversion lists unversioned files and
directories along with the versioned ones, annotating
them with a ?
character (see „Verschaffen Sie sich einen Überblick über Ihre
Änderungen“). Sometimes it can
be annoying to see uninteresting, unversioned
items—for example, object files that result from
a program's compilation—in this display. The
global-ignores
option is a list of
whitespace-delimited globs that describe the names of
files and directories that Subversion should not
display unless they are versioned. The default value
is *.o *.lo *.la #*# .*.rej *.rej .*~ *~
.#* .DS_Store
.
As well as svn status, the
svn add and svn import
commands also ignore files that match the list
when they are scanning a directory. You can override this
behavior for a single instance of any of these commands
by explicitly specifying the filename, or by using
the --no-ignore
command-line flag.
For information on finer-grained control of ignored items, see „Ignoring Unversioned Items“.
enable-auto-props
This instructs Subversion to automatically set
properties on newly added or imported files. The
default value is no
, so set this to
yes
to enable this feature.
The auto-props
section of this file
specifies which properties are to be set on which files.
log-encoding
This variable sets the default character set
encoding for commit log messages. It's a permanent
form of the --encoding
option (see
„svn Options“). The Subversion
repository stores log messages in UTF-8 and assumes
that your log message is written using your operating
system's native locale. You should specify a
different encoding if your commit messages are written
in any other encoding.
use-commit-times
Normally your working copy files have timestamps that reflect the last time they were touched by any process, whether your own editor or some svn subcommand. This is generally convenient for people developing software, because build systems often look at timestamps as a way of deciding which files need to be recompiled.
In other situations, however, it's sometimes nice
for the working copy files to have timestamps that
reflect the last time they were changed in the
repository. The svn export command
always places these „last-commit
timestamps“ on trees that it produces. By
setting this config variable to
yes
, the svn
checkout, svn update,
svn switch, and svn
revert commands will also set last-commit
timestamps on files that they touch.
mime-types-file
This option, new to Subversion 1.5, specifies the
path of a MIME types mapping file, such as the
mime.types
file provided by the
Apache HTTP Server. Subversion uses this file to
assign MIME types to newly added or imported files.
See „Automatic Property Setting“ and
„File Content Type“ for more about Subversion's detection and use of
file content types.
preserved-conflict-file-exts
The value of this option is a space-delimited list of file extensions that Subversion should preserve when generating conflict filenames. By default, the list is empty. This option is new to Subversion 1.5.
When Subversion detects conflicting file content
changes, it defers resolution of those conflicts to the
user. To assist in the resolution, Subversion keeps
pristine copies of the various competing versions of
the file in the working copy. By default, those
conflict files have names constructed by appending to
the original filename a custom extension such as
.mine
or
.
(where REV
REV
is a revision
number). A mild annoyance with this naming scheme is
that on operating systems where a file's extension
determines the default application used to open and
edit that file, appending a custom extension prevents
the file from being easily opened by its native
application. For example, if the file
ReleaseNotes.pdf
was conflicted,
the conflict files might be named
ReleaseNotes.pdf.mine
or
ReleaseNotes.pdf.r4231
. While
your system might be configured to use Adobe's Acrobat
Reader to open files whose extensions are
.pdf
, there probably isn't an
application configured on your system to open all
files whose extensions are
.r4231
.
You can fix this annoyance by using this
configuration option, though. For files with one of
the specified extensions, Subversion will append to
the conflict file names the custom extension just as
before, but then also reappend the file's original
extension. Using the previous example, and assuming
that pdf
is one of the extensions
configured in this list thereof, the conflict files
generated for ReleaseNotes.pdf
would instead be named
ReleaseNotes.pdf.mine.pdf
and
ReleaseNotes.pdf.r4231.pdf
.
Because each file ends in
.pdf
, the correct default
application will be used to view them.
interactive-conflicts
This is a Boolean option that specifies whether
Subversion should try to resolve conflicts
interactively. If its value is yes
(which is the default value), Subversion will prompt
the user for how to handle conflicts in the manner
demonstrated in „Konflikte auflösen (Änderungen anderer einarbeiten)“. Otherwise, it will simply flag the conflict and
continue its operation, postponing resolution to a later
time.
no-unlock
This Boolean option corresponds to svn
commit's --no-unlock
option, which tells Subversion not to release locks on
files you've just committed. If this runtime option
is set to yes
, Subversion will
never release locks automatically, leaving you to run
svn unlock explicitly. It defaults
to no
.
The auto-props
section controls
the Subversion client's ability to automatically set
properties on files when they are added or imported.
It contains any number of key-value pairs in the
format PATTERN = PROPNAME=VALUE[;PROPNAME=VALUE
...]
, where PATTERN
is a file
pattern that matches one or more filenames and the rest of
the line is a semicolon-delimited set of property
assignments. Multiple matches
on a file will result in multiple propsets for that
file; however, there is no guarantee that auto-props
will be applied in the order in which they are listed
in the config file, so you can't have one rule
„override“ another. You can find several
examples of auto-props usage in the
config
file. Lastly, don't
forget to set enable-auto-props
to
yes
in the miscellany
section if you want to enable auto-props.
Localization is the act of making programs behave in a region-specific way. When a program formats numbers or dates in a way specific to your part of the world or prints messages (or accepts input) in your native language, the program is said to be localized. This section describes steps Subversion has made toward localization.
Most modern operating systems have a notion of the „current locale“—that is, the region or country whose localization conventions are honored. These conventions—typically chosen by some runtime configuration mechanism on the computer—affect the way in which programs present data to the user, as well as the way in which they accept user input.
On most Unix-like systems, you can check the values of the locale-related runtime configuration options by running the locale command:
$ locale LANG= LC_COLLATE="C" LC_CTYPE="C" LC_MESSAGES="C" LC_MONETARY="C" LC_NUMERIC="C" LC_TIME="C" LC_ALL="C" $
The output is a list of locale-related environment
variables and their current values. In this example, the
variables are all set to the default C
locale, but users can set these variables to specific
country/language code combinations. For example, if one were
to set the LC_TIME
variable to
fr_CA
, programs would know to present
time and date information formatted according to a
French-speaking Canadian's expectations. And if one were to
set the LC_MESSAGES
variable to
zh_TW
, programs would know to present
human-readable messages in Traditional Chinese. Setting the
LC_ALL
variable has the effect of changing
every locale variable to the same value. The value of
LANG
is used as a default value for any
locale variable that is unset. To see the list of available
locales on a Unix system, run the command locale
-a
.
On Windows, locale configuration is done via the „Regional and Language Options“ control panel item. There you can view and select the values of individual settings from the available locales, and even customize (at a sickening level of detail) several of the display formatting conventions.
The Subversion client, svn, honors the
current locale configuration in two ways. First, it notices
the value of the LC_MESSAGES
variable and
attempts to print all messages in the specified language. For
example:
$ export LC_MESSAGES=de_DE $ svn help cat cat: Gibt den Inhalt der angegebenen Dateien oder URLs aus. Aufruf: cat ZIEL[@REV]... …
This behavior works identically on both Unix and Windows
systems. Note, though, that while your operating system might
have support for a certain locale, the Subversion client still
may not be able to speak the particular language. In order to
produce localized messages, human volunteers must provide
translations for each language. The translations are written
using the GNU gettext package, which results in translation
modules that end with the .mo
filename
extension. For example, the German translation file is named
de.mo
. These translation files are
installed somewhere on your system. On Unix, they typically
live in /usr/share/locale/
, while
on Windows they're often found in the
share\locale\
folder in Subversion's
installation area. Once installed, a module is named after
the program for which it provides translations. For example, the
de.mo
file may ultimately end up
installed as
/usr/share/locale/de/LC_MESSAGES/subversion.mo
.
By browsing the installed .mo
files, you
can see which languages the Subversion client is able to
speak.
The second way in which the locale is honored involves how svn interprets your input. The repository stores all paths, filenames, and log messages in Unicode, encoded as UTF-8. In that sense, the repository is internationalized—that is, the repository is ready to accept input in any human language. This means, however, that the Subversion client is responsible for sending only UTF-8 filenames and log messages into the repository. To do this, it must convert the data from the native locale into UTF-8.
For example, suppose you create a file named
caffè.txt
, and then when committing the
file, you write the log message as „Adesso il caffè è
più forte.“ Both the filename and the log message contain
non-ASCII characters, but because your locale is set to
it_IT
, the Subversion client knows to
interpret them as Italian. It uses an Italian character set
to convert the data to UTF-8 before sending it off to the
repository.
Note that while the repository demands UTF-8 filenames and log messages, it does not pay attention to file contents. Subversion treats file contents as opaque strings of bytes, and neither client nor server makes an attempt to understand the character set or encoding of the contents.
The most obvious way to get data into Subversion is through
the addition of files to version control, committing changes to
those files, and so on. But other pieces of
information besides merely versioned file data live in your
Subversion repository. Some of these bits of
information—commit log messages, lock comments, and some
property values—tend to be textual in nature and are
provided explicitly by users. Most of this information can be
provided to the Subversion command-line client using the
--message
(-m
) and
--file
(-F
) options with the
appropriate subcommands.
Each of these options has its pros and cons. For example,
when performing a commit, --file
(-F
) works well if you've already prepared a
text file that holds your commit log message. If you didn't,
though, you can use --message
(-m
) to provide a log message on the command
line. Unfortunately, it can be tricky to compose anything more
than a simple one-line message on the command line. Users want
more flexibility—multiline, free-form log message editing
on demand.
Subversion supports this by allowing you to specify an external text editor that it will launch as necessary to give you a more powerful input mechanism for this textual metadata. There are several ways to tell Subversion which editor you'd like use. Subversion checks the following things, in the order specified, when it wants to launch such an editor:
--editor-cmd
command-line option
SVN_EDITOR
environment variable
editor-cmd
runtime configuration option
VISUAL
environment variable
EDITOR
environment variable
Possibly, a fallback value built into the Subversion libraries (not present in the official builds)
The value of any of these options or variables is the beginning of a command line to be executed by the shell. Subversion appends to that command line a space and the pathname of a temporary file to be edited. So, to be used with Subversion, the configured or specified editor needs to support an invocation in which its last command-line parameter is a file to be edited, and it should be able to save the file in place and return a zero exit code to indicate success.
As noted, external editors can be used to provide commit log
messages to any of the committing subcommands (such as
svn commit or import,
svn mkdir or delete when
provided a URL target, etc.), and Subversion will try to
launch the editor automatically if you don't specify either of
the --message
(-m
) or
--file
(-F
) options. The
svn propedit command is built almost entirely
around the use of an external editor. And beginning in version
1.5, Subversion will also use the configured external text
editor when the user asks it to launch an editor during
interactive conflict resolution. Oddly, there doesn't appear to
be a way to use external editors to interactively provide lock
comments.
The interface between Subversion and external two- and three-way
differencing tools harkens back to a time when Subversion's only
contextual differencing capabilities were built around
invocations of the GNU diffutils toolchain, specifically the
diff and diff3 utilities.
To get the kind of behavior Subversion needed, it called these
utilities with more than a handful of options and parameters,
most of which were quite specific to the utilities. Some time
later, Subversion grew its own internal differencing library,
and as a failover mechanism, the --diff-cmd
and
--diff3-cmd
options were added to the
Subversion command-line client so that users could more easily
indicate that they preferred to use the GNU diff and diff3
utilities instead of the newfangled internal diff library. If
those options were used, Subversion would simply ignore the
internal diff library, and fall back to running those external
programs, lengthy argument lists and all. And that's where
things remain today.
It didn't take long for folks to realize that having such easy configuration mechanisms for specifying that Subversion should use the external GNU diff and diff3 utilities located at a particular place on the system could be applied toward the use of other differencing tools, too. After all, Subversion didn't actually verify that the things it was being told to run were members of the GNU diffutils toolchain. But the only configurable aspect of using those external tools is their location on the system—not the option set, parameter order, and so on. Subversion continues to throw all those GNU utility options at your external diff tool regardless of whether that program can understand those options. And that's where things get unintuitive for most users.
The key to using external two- and three-way differencing tools (other than GNU diff and diff3, of course) with Subversion is to use wrapper scripts, which convert the input from Subversion into something that your differencing tool can understand, and then to convert the output of your tool back into a format that Subversion expects—the format that the GNU tools would have used. The following sections cover the specifics of those expectations.
The decision on when to fire off a contextual two- or three-way
diff as part of a larger Subversion operation is made entirely
by Subversion and is affected by, among other things, whether
the files being operated on are human-readable as
determined by their svn:mime-type
property.
This means, for example, that even if you had the niftiest
Microsoft Word-aware differencing or merging tool in the
universe, it would never be invoked by Subversion as long as
your versioned Word documents had a configured MIME type that
denoted that they were not human-readable (such as
application/msword
). For more about MIME
type settings, see „File Content Type“
Subversion 1.5 introduces interactive resolution of
conflicts (described in „Konflikte auflösen (Änderungen anderer einarbeiten)“), and one of the options provided to users is the ability to
launch a third-party merge tool. If this action is taken,
Subversion will consult the merge-tool-cmd
runtime configuration option to find the name of an external
merge tool and, upon finding one, will launch that tool with the
appropriate input files. This differs from the configurable
three-way differencing tool in a couple of ways. First, the
differencing tool is always used to handle three-way
differences, whereas the merge tool is employed only when
three-way difference application has detected a conflict.
Second, the interface is much cleaner—your configured
merge tool need only accept as command-line parameters four path
specifications: the base file, the „theirs“ file
(which contains upstream changes), the „mine“ file
(which contains local modifications), and the path of the file
where the final resolved contents should be stored.
Subversion calls external diff programs with parameters suitable for the GNU diff utility, and expects only that the external program will return with a successful error code. For most alternative diff programs, only the sixth and seventh arguments—the paths of the files that represent the left and right sides of the diff, respectively—are of interest. Note that Subversion runs the diff program once per modified file covered by the Subversion operation, so if your program runs in an asynchronous fashion (or is „backgrounded“), you might have several instances of it all running simultaneously. Finally, Subversion expects that your program return an error code of 1 if your program detected differences, or 0 if it did not—any other error code is considered a fatal error. [50]
Beispiel 7.2, „diffwrap.py“ and Beispiel 7.3, „diffwrap.bat“ are templates for external diff tool wrappers in the Python and Windows batch scripting languages, respectively.
Beispiel 7.2. diffwrap.py
#!/usr/bin/env python import sys import os # Configure your favorite diff program here. DIFF = "/usr/local/bin/my-diff-tool" # Subversion provides the paths we need as the last two parameters. LEFT = sys.argv[-2] RIGHT = sys.argv[-1] # Call the diff command (change the following line to make sense for # your diff program). cmd = [DIFF, '--left', LEFT, '--right', RIGHT] os.execv(cmd[0], cmd) # Return an errorcode of 0 if no differences were detected, 1 if some were. # Any other errorcode will be treated as fatal.
Beispiel 7.3. diffwrap.bat
@ECHO OFF REM Configure your favorite diff program here. SET DIFF="C:\Program Files\Funky Stuff\My Diff Tool.exe" REM Subversion provides the paths we need as the last two parameters. REM These are parameters 6 and 7 (unless you use svn diff -x, in REM which case, all bets are off). SET LEFT=%6 SET RIGHT=%7 REM Call the diff command (change the following line to make sense for REM your diff program). %DIFF% --left %LEFT% --right %RIGHT% REM Return an errorcode of 0 if no differences were detected, 1 if some were. REM Any other errorcode will be treated as fatal.
Subversion calls external merge programs with parameters suitable for the GNU diff3 utility, expecting that the external program will return with a successful error code and that the full file contents that result from the completed merge operation are printed on the standard output stream (so that Subversion can redirect them into the appropriate version-controlled file). For most alternative merge programs, only the ninth, tenth, and eleventh arguments, the paths of the files which represent the „mine,“ „older,“ and „yours“ inputs, respectively, are of interest. Note that because Subversion depends on the output of your merge program, your wrapper script must not exit before that output has been delivered to Subversion. When it finally does exit, it should return an error code of 0 if the merge was successful, or 1 if unresolved conflicts remain in the output—any other error code is considered a fatal error.
Beispiel 7.4, „diff3wrap.py“ and Beispiel 7.5, „diff3wrap.bat“ are templates for external merge tool wrappers in the Python and Windows batch scripting languages, respectively.
Beispiel 7.4. diff3wrap.py
#!/usr/bin/env python import sys import os # Configure your favorite diff program here. DIFF3 = "/usr/local/bin/my-merge-tool" # Subversion provides the paths we need as the last three parameters. MINE = sys.argv[-3] OLDER = sys.argv[-2] YOURS = sys.argv[-1] # Call the merge command (change the following line to make sense for # your merge program). cmd = [DIFF3, '--older', OLDER, '--mine', MINE, '--yours', YOURS] os.execv(cmd[0], cmd) # After performing the merge, this script needs to print the contents # of the merged file to stdout. Do that in whatever way you see fit. # Return an errorcode of 0 on successful merge, 1 if unresolved conflicts # remain in the result. Any other errorcode will be treated as fatal.
Beispiel 7.5. diff3wrap.bat
@ECHO OFF REM Configure your favorite diff3/merge program here. SET DIFF3="C:\Program Files\Funky Stuff\My Merge Tool.exe" REM Subversion provides the paths we need as the last three parameters. REM These are parameters 9, 10, and 11. But we have access to only REM nine parameters at a time, so we shift our nine-parameter window REM twice to let us get to what we need. SHIFT SHIFT SET MINE=%7 SET OLDER=%8 SET YOURS=%9 REM Call the merge command (change the following line to make sense for REM your merge program). %DIFF3% --older %OLDER% --mine %MINE% --yours %YOURS% REM After performing the merge, this script needs to print the contents REM of the merged file to stdout. Do that in whatever way you see fit. REM Return an errorcode of 0 on successful merge, 1 if unresolved conflicts REM remain in the result. Any other errorcode will be treated as fatal.
Sometimes there's a single right way to do things; sometimes there are many. Subversion's developers understand that while the majority of its exact behaviors are acceptable to most of its users, there are some corners of its functionality where such a universally pleasing approach doesn't exist. In those places, Subversion offers users the opportunity to tell it how they want it to behave.
In this chapter, we explored Subversion's runtime configuration system and other mechanisms by which users can control those configurable behaviors. If you are a developer, though, the next chapter will take you one step further. It describes how you can further customize your Subversion experience by writing your own software against Subversion's libraries.
[48] The APPDATA
environment variable
points to the Application Data
area,
so you can always refer to this folder as
%APPDATA%\Subversion
.
[49] Anyone for potluck dinner?
[50] The GNU diff manual page puts it this way: „An exit status of 0 means no differences were found, 1 means some differences were found, and 2 means trouble.“
Inhaltsverzeichnis
Subversion has a modular design: it's implemented as a collection of libraries written in C. Each library has a well-defined purpose and application programming interface (API), and that interface is available not only for Subversion itself to use, but for any software that wishes to embed or otherwise programmatically control Subversion. Additionally, Subversion's API is available not only to other C programs, but also to programs written in higher-level languages such as Python, Perl, Java, and Ruby.
This chapter is for those who wish to interact with Subversion through its public API or its various language bindings. If you wish to write robust wrapper scripts around Subversion functionality to simplify your own life, are trying to develop more complex integrations between Subversion and other pieces of software, or just have an interest in Subversion's various library modules and what they offer, this chapter is for you. If, however, you don't foresee yourself participating with Subversion at such a level, feel free to skip this chapter with the confidence that your experience as a Subversion user will not be affected.
Each of Subversion's core libraries can be said to exist in
one of three main layers—the Repository layer, the
Repository Access (RA) layer, or the Client layer (see Abbildung 1, „Die Architektur von Subversion“ in the Preface). We will examine
these layers shortly, but first, let's briefly summarize
Subversion's various libraries. For the sake of consistency, we
will refer to the libraries by their extensionless Unix library
names (libsvn_fs
, libsvn_wc
,
mod_dav_svn
, etc.).
Primary interface for client programs
Tree and byte-stream differencing routines
Contextual differencing and merging routines
Filesystem commons and module loader
The Berkeley DB filesystem backend
The native filesystem (FSFS) backend
Repository Access commons and module loader
The local Repository Access module
The WebDAV Repository Access module
Another (experimental) WebDAV Repository Access module
The custom protocol Repository Access module
Repository interface
Miscellaneous helpful subroutines
The working copy management library
Apache authorization module for Subversion repositories access via WebDAV
Apache module for mapping WebDAV operations to Subversion ones
The fact that the word „miscellaneous“ appears only once in the previous list is a good sign. The Subversion development team is serious about making sure that functionality lives in the right layer and libraries. Perhaps the greatest advantage of the modular design is its lack of complexity from a developer's point of view. As a developer, you can quickly formulate that kind of „big picture“ that allows you to pinpoint the location of certain pieces of functionality with relative ease.
Another benefit of modularity is the ability to replace a
given module with a whole new library that implements the same
API without affecting the rest of the code base. In some sense,
this happens within Subversion already. The
libsvn_ra_local
,
libsvn_ra_neon
,
libsvn_ra_serf
, and
libsvn_ra_svn
libraries each implement the
same interface, all working as plug-ins to
libsvn_ra
. And all four communicate with
the Repository layer—libsvn_ra_local
connects to the
repository directly; the other three do so over a network. The
libsvn_fs_base
and
libsvn_fs_fs
libraries are another pair of
libraries that implement the same functionality in different
ways—both are plug-ins to the common
libsvn_fs
library.
The client itself also highlights the benefits of modularity
in the Subversion design. Subversion's
libsvn_client
library is a one-stop shop
for most of the functionality necessary for designing a working
Subversion client (see „Client Layer“). So while the
Subversion distribution provides only the svn
command-line client program, several third-party
programs provide various forms of graphical client UIs.
These GUIs use the same APIs that the stock command-line client
does. This type of modularity has played a large role in the
proliferation of available Subversion clients and IDE
integrations and, by extension, to the tremendous adoption rate
of Subversion itself.
When referring to Subversion's Repository layer, we're
generally talking about two basic concepts—the versioned
filesystem implementation (accessed via
libsvn_fs
, and supported by its
libsvn_fs_base
and
libsvn_fs_fs
plug-ins), and the repository
logic that wraps it (as implemented in
libsvn_repos
). These libraries provide
the storage and reporting mechanisms for the various revisions
of your version-controlled data. This layer is connected to
the Client layer via the Repository Access layer, and is, from
the perspective of the Subversion user, the stuff at the
„other end of the line.“
The Subversion filesystem is not a kernel-level filesystem that one would install in an operating system (such as the Linux ext2 or NTFS), but instead is a virtual filesystem. Rather than storing „files“ and „directories“ as real files and directories (the kind you can navigate through using your favorite shell program), it uses one of two available abstract storage backends—either a Berkeley DB database environment or a flat-file representation. (To learn more about the two repository backends, see „Auswahl der Datenspeicherung“.) There has even been considerable interest by the development community in giving future releases of Subversion the ability to use other backend database systems, perhaps through a mechanism such as Open Database Connectivity (ODBC). In fact, Google did something similar to this before launching the Google Code Project Hosting service: they announced in mid-2006 that members of its open source team had written a new proprietary Subversion filesystem plug-in that used Google's ultra-scalable Bigtable database for its storage.
The filesystem API exported by
libsvn_fs
contains the kinds of
functionality you would expect from any other filesystem
API—you can create and remove files and directories,
copy and move them around, modify file contents, and so on.
It also has features that are not quite as common, such as the
ability to add, modify, and remove metadata
(„properties“) on each file or directory.
Furthermore, the Subversion filesystem is a versioning
filesystem, which means that as you make changes to your
directory tree, Subversion remembers what your tree looked
like before those changes. And before the previous changes.
And the previous ones. And so on, all the way back through
versioning time to (and just beyond) the moment you first
started adding things to the filesystem.
All the modifications you make to your tree are done within the context of a Subversion commit transaction. The following is a simplified general routine for modifying your filesystem:
Begin a Subversion commit transaction.
Make your changes (adds, deletes, property modifications, etc.).
Commit your transaction.
Once you have committed your transaction, your filesystem modifications are permanently stored as historical artifacts. Each of these cycles generates a single new revision of your tree, and each revision is forever accessible as an immutable snapshot of „the way things were.“
Most of the functionality the filesystem
interface provides deals with actions that occur on individual
filesystem paths. That is, from outside the filesystem, the
primary mechanism for describing and accessing the individual
revisions of files and directories comes through the use of
path strings such as /foo/bar
, just as though
you were addressing files and directories through your
favorite shell program. You add new files and directories by
passing their paths-to-be to the right API functions. You
query for information about them by the same mechanism.
Unlike most filesystems, though, a path alone is not enough information to identify a file or directory in Subversion. Think of a directory tree as a two-dimensional system, where a node's siblings represent a sort of left-and-right motion, and navigating into the node's subdirectories represents a downward motion. Abbildung 8.1, „Files and directories in two dimensions“ shows a typical representation of a tree as exactly that.
The difference here is that the Subversion filesystem has a
nifty third dimension that most filesystems do not
have—Time!
[51]
In the filesystem interface, nearly every function that has a
path
argument also expects a
root
argument. This
svn_fs_root_t
argument describes
either a revision or a Subversion transaction (which is simply
a revision in the making) and provides that third dimension
of context needed to understand the difference between
/foo/bar
in revision 32, and the same
path as it exists in revision 98. Abbildung 8.2, „Versioning time—the third dimension!“ shows revision
history as an added dimension to the Subversion filesystem
universe.
As we mentioned earlier, the
libsvn_fs
API looks and feels like any
other filesystem, except that it has this wonderful versioning
capability. It was designed to be usable by any program
interested in a versioning filesystem. Not coincidentally,
Subversion itself is interested in that functionality. But
while the filesystem API should be sufficient for basic file
and directory versioning support, Subversion wants
more—and that is where libsvn_repos
comes in.
The Subversion repository library
(libsvn_repos
) sits (logically speaking)
atop the libsvn_fs
API, providing
additional functionality beyond that of the underlying
versioned filesystem logic. It does not completely wrap each
and every filesystem function—only certain major steps
in the general cycle of filesystem activity are wrapped by the
repository interface. Some of these include the creation and
commit of Subversion transactions and the modification of
revision properties. These particular events are wrapped by
the repository layer because they have hooks associated with
them. A repository hook system is not strictly related to
implementing a versioning filesystem, so it lives in the
repository wrapper library.
The hooks mechanism is but one of the reasons for the
abstraction of a separate repository library from the rest of
the filesystem code. The libsvn_repos
API provides several other important utilities to Subversion.
These include the abilities to:
Create, open, destroy, and perform recovery steps on a Subversion repository and the filesystem included in that repository.
Describe the differences between two filesystem trees.
Query for the commit log messages associated with all (or some) of the revisions in which a set of files was modified in the filesystem.
Generate a human-readable „dump“ of the filesystem—a complete representation of the revisions in the filesystem.
Parse that dump format, loading the dumped revisions into a different Subversion repository.
As Subversion continues to evolve, the repository library will grow with the filesystem library to offer increased functionality and configurable option support.
If the Subversion Repository layer is at „the other
end of the line,“ the Repository Access (RA) layer is
the line itself. Charged with marshaling data between the
client libraries and the repository, this layer includes the
libsvn_ra
module loader library, the RA
modules themselves (which currently includes
libsvn_ra_neon
,
libsvn_ra_local
,
libsvn_ra_serf
, and
libsvn_ra_svn
), and any additional
libraries needed by one or more of those RA modules (such as
the mod_dav_svn
Apache module or
libsvn_ra_svn
's server,
svnserve).
Since Subversion uses URLs to identify its repository
resources, the protocol portion of the URL scheme (usually
file://
, http://
,
https://
, svn://
, or
svn+ssh://
) is used to determine which RA
module will handle the communications. Each module registers
a list of the protocols it knows how to „speak“
so that the RA loader can, at runtime, determine which module
to use for the task at hand. You can determine which RA
modules are available to the Subversion command-line client,
and what protocols they claim to support, by running
svn --version
:
$ svn --version svn, version 1.5.0 (r31699) compiled Jun 18 2008, 09:57:36 Copyright (C) 2000-2008 CollabNet. Subversion is open source software, see http://subversion.tigris.org/ This product includes software developed by CollabNet (http://www.Collab.Net/). The following repository access (RA) modules are available: * ra_neon : Module for accessing a repository via WebDAV protocol using Neon. - handles 'http' scheme - handles 'https' scheme * ra_svn : Module for accessing a repository using the svn network protocol. - handles 'svn' scheme * ra_local : Module for accessing a repository on local disk. - handles 'file' scheme * ra_serf : Module for accessing a repository via WebDAV protocol using serf. - handles 'http' scheme - handles 'https' scheme $
The public API exported by the RA layer contains
functionality necessary for sending and receiving versioned
data to and from the repository. And each of the available RA
plug-ins is able to perform that task using a specific
protocol—libsvn_ra_dav
speaks
HTTP/WebDAV (optionally using SSL encryption) with an Apache
HTTP Server that is running the
mod_dav_svn
Subversion server module;
libsvn_ra_svn
speaks a custom network
protocol with the svnserve program; and so
on.
For those who wish to access a Subversion repository using still another protocol, that is precisely why the Repository Access layer is modularized! Developers can simply write a new library that implements the RA interface on one side and communicates with the repository on the other. Your new library can use existing network protocols or you can invent your own. You could use interprocess communication (IPC) calls, or—let's get crazy, shall we?—you could even implement an email-based protocol. Subversion supplies the APIs; you supply the creativity.
On the client side, the Subversion working copy is where all the action takes place. The bulk of functionality implemented by the client-side libraries exists for the sole purpose of managing working copies—directories full of files and other subdirectories that serve as a sort of local, editable „reflection“ of one or more repository locations—and propagating changes to and from the Repository Access layer.
Subversion's working copy library,
libsvn_wc
, is directly responsible for
managing the data in the working copies. To accomplish this,
the library stores administrative information about each
working copy directory within a special subdirectory. This
subdirectory, named .svn
, is present in
each working copy directory and contains various other files
and directories that record state and provide a private
workspace for administrative action. For those familiar with
CVS, this .svn
subdirectory is similar in
purpose to the CVS
administrative
directories found in CVS working copies. For more information
about the .svn
administrative area, see
„Inside the Working Copy Administration Area“ later in this
chapter.
The Subversion client library,
libsvn_client
, has the broadest
responsibility; its job is to mingle the functionality of the
working copy library with that of the Repository Access layer,
and then to provide the highest-level API to any application
that wishes to perform general revision control actions. For
example, the function
svn_client_checkout()
takes a URL as an
argument. It passes this URL to the RA layer and opens an
authenticated session with a particular repository. It then
asks the repository for a certain tree, and sends this tree
into the working copy library, which then writes a full
working copy to disk (.svn
directories
and all).
The client library is designed to be used by any
application. While the Subversion source code includes a
standard command-line client, it should be very easy to write
any number of GUI clients on top of the client library. New
GUIs (or any new client, really) for Subversion need not be
clunky wrappers around the included command-line
client—they have full access via the
libsvn_client
API to the same functionality,
data, and callback mechanisms that the command-line client
uses. In fact, the Subversion source code tree contains a
small C program (which you can find at
tools/examples/minimal_client.c
) that
exemplifies how to wield the Subversion API to create a simple
client program.
As we mentioned earlier, each directory of a Subversion
working copy contains a special subdirectory called
.svn
that houses administrative data about
that working copy directory. Subversion uses the information in
.svn
to keep track of things such as:
Which repository location(s) are represented by the files and subdirectories in the working copy directory
What revision of each of those files and directories is currently present in the working copy
Any user-defined properties that might be attached to those files and directories
Pristine (unedited) copies of the working copy files
The Subversion working copy administration area's layout and contents are considered implementation details not really intended for human consumption. Developers are encouraged to use Subversion's public APIs, or the tools that Subversion provides, to access and manipulate the working copy data, instead of directly reading or modifying those files. The file formats employed by the working copy library for its administrative data do change from time to time—a fact that the public APIs do a great job of hiding from the average user. In this section, we expose some of these implementation details sheerly to appease your overwhelming curiosity.
Perhaps the single most important file in the
.svn
directory is the
entries
file. It
contains the bulk of the administrative
information about the versioned items in a working copy
directory. This one file tracks the repository
URLs, pristine revision, file checksums, pristine text and
property timestamps, scheduling and conflict state
information, last-known commit information (author, revision,
timestamp), local copy history—practically everything
that a Subversion client is interested in knowing about a
versioned (or to-be-versioned) resource!
Folks familiar with CVS's administrative directories will
have recognized at this point that Subversion's
.svn/entries
file serves the purposes of,
among other things, CVS's CVS/Entries
,
CVS/Root
, and
CVS/Repository
files combined.
The format of the .svn/entries
file
has changed over time. Originally an XML file, it now uses a
custom—though still human-readable—file format.
While XML was a great choice for early developers of
Subversion who were frequently debugging the file's contents
(and Subversion's behavior in light of them), the need for
easy developer debugging has diminished as Subversion has
matured and has been replaced by the user's need for snappier
performance. Be aware that Subversion's working copy library
automatically upgrades working copies from one format to
another—it reads the old formats and writes the
new—which saves you the hassle of checking out a new
working copy, but can also complicate situations where
different versions of Subversion might be trying to use the
same working copy.
As mentioned before, the .svn
directory also holds the pristine „text-base“
versions of files. You can find those in
.svn/text-base
. The benefits of these
pristine copies are multiple—network-free checks for
local modifications and difference reporting, network-free
reversion of modified or missing files, more efficient
transmission of changes to the server—but they come at the
cost of having each versioned file stored at least twice on
disk. These days, this seems to be a negligible penalty for
most files. However, the situation gets uglier as the size of
your versioned files grows. Some attention is being given to
making the presence of the „text-base“ an option.
Ironically, though, it is as your versioned files' sizes get
larger that the existence of the „text-base“
becomes more crucial—who wants to transmit a huge file
across a network just because she wants to commit a tiny
change to it?
Similar in purpose to the „text-base“ files
are the property files and their pristine
„prop-base“ copies, located in
.svn/props
and
.svn/prop-base
, respectively. Since
directories can have properties too, there are also
.svn/dir-props
and
.svn/dir-prop-base
files.
Developing applications against the Subversion library APIs
is fairly straightforward. Subversion is primarily a set of C
libraries, with header (.h
) files that live
in the subversion/include
directory of the
source tree. These headers are copied into your system
locations (e.g., /usr/local/include
)
when you build and install Subversion itself from source. These
headers represent the entirety of the functions and types meant
to be accessible by users of the Subversion libraries. The
Subversion developer community is meticulous about ensuring that
the public API is well documented—refer directly to the
header files for that documentation.
When examining the public header files, the first thing you
might notice is that Subversion's datatypes and functions are
namespace-protected. That is, every public Subversion symbol
name begins with svn_
, followed by a short
code for the library in which the symbol is defined (such as
wc
, client
,
fs
, etc.), followed by a single underscore
(_
), and then the rest of the symbol name.
Semipublic functions (used among source files of a given
library but not by code outside that library, and found inside
the library directories themselves) differ from this naming
scheme in that instead of a single underscore after the library
code, they use a double underscore
(_ _
). Functions that are private to
a given source file have no special prefixing and are declared
static
. Of course, a compiler isn't
interested in these naming conventions, but they help to clarify
the scope of a given function or datatype.
Another good source of information about programming against the Subversion APIs is the project's own hacking guidelines, which you can find at http://subversion.tigris.org/hacking.html. This document contains useful information, which, while aimed at developers and would-be developers of Subversion itself, is equally applicable to folks developing against Subversion as a set of third-party libraries. [52]
Along with Subversion's own datatypes, you will see many
references to datatypes that begin with
apr_
—symbols from the Apache Portable
Runtime (APR) library. APR is Apache's portability library,
originally carved out of its server code as an attempt to
separate the OS-specific bits from the OS-independent portions
of the code. The result was a library that provides a generic
API for performing operations that differ mildly—or
wildly—from OS to OS. While the Apache HTTP Server was
obviously the first user of the APR library, the Subversion
developers immediately recognized the value of using APR as
well. This means that there is practically no OS-specific
code in Subversion itself. Also, it means that the Subversion
client compiles and runs anywhere that the Apache HTTP Server
does. Currently, this list includes all flavors of Unix,
Win32, BeOS, OS/2, and Mac OS X.
In addition to providing consistent implementations of
system calls that differ across operating systems,
[53]
APR gives Subversion immediate access to many custom
datatypes, such as dynamic arrays and hash tables. Subversion
uses these types extensively. But
perhaps the most pervasive APR datatype, found in nearly every
Subversion API prototype, is the
apr_pool_t
—the APR memory pool.
Subversion uses pools internally for all its memory allocation
needs (unless an external library requires a different memory
management mechanism for data passed through its API),
[54]
and while a person coding against the Subversion APIs is not
required to do the same, she is
required to provide pools to the API functions that need them.
This means that users of the Subversion API must also link
against APR, must call apr_initialize()
to initialize the APR subsystem, and then must create and
manage pools for use with Subversion API calls, typically by
using svn_pool_create()
,
svn_pool_clear()
, and
svn_pool_destroy()
.
With remote version control operation as the whole point
of Subversion's existence, it makes sense that some attention
has been paid to internationalization (i18n) support. After
all, while „remote“ might mean „across the
office,“ it could just as well mean „across the
globe.“ To facilitate this, all of Subversion's public
interfaces that accept path arguments expect those paths to be
canonicalized—which is most easily accomplished by passing
them through the svn_path_canonicalize()
function—and encoded in UTF-8. This means, for example, that
any new client binary that drives the
libsvn_client
interface needs to first
convert paths from the locale-specific encoding to UTF-8
before passing those paths to the Subversion libraries, and
then reconvert any resultant output paths from Subversion
back into the locale's encoding before using those paths for
non-Subversion purposes. Fortunately, Subversion provides a
suite of functions (see
subversion/include/svn_utf.h
) that
any program can use to do these conversions.
Also, Subversion APIs require all URL parameters to be
properly URI-encoded. So, instead of passing
file:///home/username/My File.txt
as the URL of a
file named My File.txt
, you need to pass
file:///home/username/My%20File.txt
. Again,
Subversion supplies helper functions that your application can
use—svn_path_uri_encode()
and
svn_path_uri_decode()
, for URI encoding
and decoding, respectively.
If you are interested in using the Subversion libraries in
conjunction with something other than a C program—say, a
Python or Perl script—Subversion has some support for this
via the Simplified Wrapper and Interface Generator (SWIG). The
SWIG bindings for Subversion are located in
subversion/bindings/swig
. They are still
maturing, but they are usable. These bindings allow you
to call Subversion API functions indirectly, using wrappers that
translate the datatypes native to your scripting language into
the datatypes needed by Subversion's C libraries.
Significant efforts have been made toward creating functional SWIG-generated bindings for Python, Perl, and Ruby. To some extent, the work done preparing the SWIG interface files for these languages is reusable in efforts to generate bindings for other languages supported by SWIG (which include versions of C#, Guile, Java, MzScheme, OCaml, PHP, and Tcl, among others). However, some extra programming is required to compensate for complex APIs that SWIG needs some help translating between languages. For more information on SWIG itself, see the project's web site at http://www.swig.org/.
Subversion also has language bindings for Java. The
javahl bindings (located in
subversion/bindings/java
in the
Subversion source tree) aren't SWIG-based, but are instead a
mixture of Java and hand-coded JNI. Javahl covers most
Subversion client-side APIs and is specifically targeted at
implementors of Java-based Subversion clients and IDE
integrations.
Subversion's language bindings tend to lack the level of developer attention given to the core Subversion modules, but can generally be trusted as production-ready. A number of scripts and applications, alternative Subversion GUI clients, and other third-party tools are successfully using Subversion's language bindings today to accomplish their Subversion integrations.
It's worth noting here that there are other options for interfacing with Subversion using other languages: alternative bindings for Subversion that aren't provided by the Subversion development community at all. You can find links to these alternative bindings on the Subversion project's links page (at http://subversion.tigris.org/links.html), but there are a couple of popular ones we feel are especially noteworthy. First, Barry Scott's PySVN bindings (http://pysvn.tigris.org/) are a popular option for binding with Python. PySVN boasts of a more Pythonic interface than the more C-like APIs provided by Subversion's own Python bindings. And if you're looking for a pure Java implementation of Subversion, check out SVNKit (http://svnkit.com/), which is Subversion rewritten from the ground up in Java.
Beispiel 8.1, „Using the Repository Layer“
contains a code segment (written in C) that illustrates some
of the concepts we've been discussing. It uses both the
repository and filesystem interfaces (as can be determined by
the prefixes svn_repos_
and
svn_fs_
of the function names,
respectively) to create a new revision in which a directory is
added. You can see the use of an APR pool, which is passed
around for memory allocation purposes. Also, the code reveals
a somewhat obscure fact about Subversion error
handling—all Subversion errors must be explicitly
handled to avoid memory leakage (and in some cases,
application failure).
Beispiel 8.1. Using the Repository Layer
/* Convert a Subversion error into a simple boolean error code. * * NOTE: Subversion errors must be cleared (using svn_error_clear()) * because they are allocated from the global pool, else memory * leaking occurs. */ #define INT_ERR(expr) \ do { \ svn_error_t *__temperr = (expr); \ if (__temperr) \ { \ svn_error_clear(__temperr); \ return 1; \ } \ return 0; \ } while (0) /* Create a new directory at the path NEW_DIRECTORY in the Subversion * repository located at REPOS_PATH. Perform all memory allocation in * POOL. This function will create a new revision for the addition of * NEW_DIRECTORY. Return zero if the operation completes * successfully, nonzero otherwise. */ static int make_new_directory(const char *repos_path, const char *new_directory, apr_pool_t *pool) { svn_error_t *err; svn_repos_t *repos; svn_fs_t *fs; svn_revnum_t youngest_rev; svn_fs_txn_t *txn; svn_fs_root_t *txn_root; const char *conflict_str; /* Open the repository located at REPOS_PATH. */ INT_ERR(svn_repos_open(&repos, repos_path, pool)); /* Get a pointer to the filesystem object that is stored in REPOS. */ fs = svn_repos_fs(repos); /* Ask the filesystem to tell us the youngest revision that * currently exists. */ INT_ERR(svn_fs_youngest_rev(&youngest_rev, fs, pool)); /* Begin a new transaction that is based on YOUNGEST_REV. We are * less likely to have our later commit rejected as conflicting if we * always try to make our changes against a copy of the latest snapshot * of the filesystem tree. */ INT_ERR(svn_repos_fs_begin_txn_for_commit2(&txn, repos, youngest_rev, apr_hash_make(pool), pool)); /* Now that we have started a new Subversion transaction, get a root * object that represents that transaction. */ INT_ERR(svn_fs_txn_root(&txn_root, txn, pool)); /* Create our new directory under the transaction root, at the path * NEW_DIRECTORY. */ INT_ERR(svn_fs_make_dir(txn_root, new_directory, pool)); /* Commit the transaction, creating a new revision of the filesystem * which includes our added directory path. */ err = svn_repos_fs_commit_txn(&conflict_str, repos, &youngest_rev, txn, pool); if (! err) { /* No error? Excellent! Print a brief report of our success. */ printf("Directory '%s' was successfully added as new revision " "'%ld'.\n", new_directory, youngest_rev); } else if (err->apr_err == SVN_ERR_FS_CONFLICT) { /* Uh-oh. Our commit failed as the result of a conflict * (someone else seems to have made changes to the same area * of the filesystem that we tried to modify). Print an error * message. */ printf("A conflict occurred at path '%s' while attempting " "to add directory '%s' to the repository at '%s'.\n", conflict_str, new_directory, repos_path); } else { /* Some other error has occurred. Print an error message. */ printf("An error occurred while attempting to add directory '%s' " "to the repository at '%s'.\n", new_directory, repos_path); } INT_ERR(err); }
Note that in Beispiel 8.1, „Using the Repository Layer“, the code could
just as easily have committed the transaction using
svn_fs_commit_txn()
. But the filesystem
API knows nothing about the repository library's hook
mechanism. If you want your Subversion repository to
automatically perform some set of non-Subversion tasks every
time you commit a transaction (e.g., sending an
email that describes all the changes made in that transaction
to your developer mailing list), you need to use the
libsvn_repos
-wrapped version of that
function, which adds the hook triggering
functionality—in this case,
svn_repos_fs_commit_txn()
. (For more
information regarding Subversion's repository hooks, see „Erstellen von Repository-Hooks“.)
Now let's switch languages. Beispiel 8.2, „Using the Repository layer with Python“ is a sample program that uses Subversion's SWIG Python bindings to recursively crawl the youngest repository revision, and to print the various paths reached during the crawl.
Beispiel 8.2. Using the Repository layer with Python
#!/usr/bin/python """Crawl a repository, printing versioned object path names.""" import sys import os.path import svn.fs, svn.core, svn.repos def crawl_filesystem_dir(root, directory): """Recursively crawl DIRECTORY under ROOT in the filesystem, and return a list of all the paths at or below DIRECTORY.""" # Print the name of this path. print directory + "/" # Get the directory entries for DIRECTORY. entries = svn.fs.svn_fs_dir_entries(root, directory) # Loop over the entries. names = entries.keys() for name in names: # Calculate the entry's full path. full_path = directory + '/' + name # If the entry is a directory, recurse. The recursion will return # a list with the entry and all its children, which we will add to # our running list of paths. if svn.fs.svn_fs_is_dir(root, full_path): crawl_filesystem_dir(root, full_path) else: # Else it's a file, so print its path here. print full_path def crawl_youngest(repos_path): """Open the repository at REPOS_PATH, and recursively crawl its youngest revision.""" # Open the repository at REPOS_PATH, and get a reference to its # versioning filesystem. repos_obj = svn.repos.svn_repos_open(repos_path) fs_obj = svn.repos.svn_repos_fs(repos_obj) # Query the current youngest revision. youngest_rev = svn.fs.svn_fs_youngest_rev(fs_obj) # Open a root object representing the youngest (HEAD) revision. root_obj = svn.fs.svn_fs_revision_root(fs_obj, youngest_rev) # Do the recursive crawl. crawl_filesystem_dir(root_obj, "") if __name__ == "__main__": # Check for sane usage. if len(sys.argv) != 2: sys.stderr.write("Usage: %s REPOS_PATH\n" % (os.path.basename(sys.argv[0]))) sys.exit(1) # Canonicalize the repository path. repos_path = svn.core.svn_path_canonicalize(sys.argv[1]) # Do the real work. crawl_youngest(repos_path)
This same program in C would need to deal with APR's memory pool system. But Python handles memory usage automatically, and Subversion's Python bindings adhere to that convention. In C, you'd be working with custom datatypes (such as those provided by the APR library) for representing the hash of entries and the list of paths, but Python has hashes (called „dictionaries“) and lists as built-in datatypes, and it provides a rich collection of functions for operating on those types. So SWIG (with the help of some customizations in Subversion's language bindings layer) takes care of mapping those custom datatypes into the native datatypes of the target language. This provides a more intuitive interface for users of that language.
The Subversion Python bindings can be used for working
copy operations, too. In the previous section of this
chapter, we mentioned the libsvn_client
interface and how it exists for the sole purpose of
simplifying the process of writing a Subversion client. Beispiel 8.3, „A Python status crawler“ is a brief
example of how that library can be accessed via the SWIG
Python bindings to re-create a scaled-down version of the
svn status command.
Beispiel 8.3. A Python status crawler
#!/usr/bin/env python """Crawl a working copy directory, printing status information.""" import sys import os.path import getopt import svn.core, svn.client, svn.wc def generate_status_code(status): """Translate a status value into a single-character status code, using the same logic as the Subversion command-line client.""" code_map = { svn.wc.svn_wc_status_none : ' ', svn.wc.svn_wc_status_normal : ' ', svn.wc.svn_wc_status_added : 'A', svn.wc.svn_wc_status_missing : '!', svn.wc.svn_wc_status_incomplete : '!', svn.wc.svn_wc_status_deleted : 'D', svn.wc.svn_wc_status_replaced : 'R', svn.wc.svn_wc_status_modified : 'M', svn.wc.svn_wc_status_merged : 'G', svn.wc.svn_wc_status_conflicted : 'C', svn.wc.svn_wc_status_obstructed : '~', svn.wc.svn_wc_status_ignored : 'I', svn.wc.svn_wc_status_external : 'X', svn.wc.svn_wc_status_unversioned : '?', } return code_map.get(status, '?') def do_status(wc_path, verbose): # Build a client context baton. ctx = svn.client.svn_client_ctx_t() def _status_callback(path, status): """A callback function for svn_client_status.""" # Print the path, minus the bit that overlaps with the root of # the status crawl text_status = generate_status_code(status.text_status) prop_status = generate_status_code(status.prop_status) print '%s%s %s' % (text_status, prop_status, path) # Do the status crawl, using _status_callback() as our callback function. revision = svn.core.svn_opt_revision_t() revision.type = svn.core.svn_opt_revision_head svn.client.svn_client_status2(wc_path, revision, _status_callback, svn.core.svn_depth_infinity, verbose, 0, 0, 1, ctx) def usage_and_exit(errorcode): """Print usage message, and exit with ERRORCODE.""" stream = errorcode and sys.stderr or sys.stdout stream.write("""Usage: %s OPTIONS WC-PATH Options: --help, -h : Show this usage message --verbose, -v : Show all statuses, even uninteresting ones """ % (os.path.basename(sys.argv[0]))) sys.exit(errorcode) if __name__ == '__main__': # Parse command-line options. try: opts, args = getopt.getopt(sys.argv[1:], "hv", ["help", "verbose"]) except getopt.GetoptError: usage_and_exit(1) verbose = 0 for opt, arg in opts: if opt in ("-h", "--help"): usage_and_exit(0) if opt in ("-v", "--verbose"): verbose = 1 if len(args) != 1: usage_and_exit(2) # Canonicalize the repository path. wc_path = svn.core.svn_path_canonicalize(args[0]) # Do the real work. try: do_status(wc_path, verbose) except svn.core.SubversionException, e: sys.stderr.write("Error (%d): %s\n" % (e.apr_err, e.message)) sys.exit(1)
As was the case in Beispiel 8.2, „Using the Repository layer with Python“, this
program is pool-free and uses, for the most part, normal
Python datatypes. The call to
svn_client_ctx_t()
is deceiving because
the public Subversion API has no such function—this just
happens to be a case where SWIG's automatic language
generation bleeds through a little bit (the function is a sort
of factory function for Python's version of the corresponding
complex C structure). Also note that the path passed to this
program (like the last one) gets run through
svn_path_canonicalize()
, because to
not do so runs the risk of triggering the
underlying Subversion C library's assertions about such
things, which translates into rather immediate and
unceremonious program abortion.
One of Subversion's greatest features isn't something you get from running its command-line client or other tools. It's the fact that Subversion was designed modularly and provides a stable, public API so that others—like yourself, perhaps—can write custom software that drives Subversion's core logic.
In this chapter, we took a closer look at Subversion's architecture, examining its logical layers and describing that public API, the very same API that Subversion's own layers use to communicate with each other. Many developers have found interesting uses for the Subversion API, from simple repository hook scripts, to integrations between Subversion and some other application, to completely different version control systems. What unique itch will you scratch with it?
[51] We understand that this may come as a shock to sci-fi fans who have long been under the impression that Time was actually the fourth dimension, and we apologize for any emotional trauma induced by our assertion of a different theory.
[52] After all, Subversion uses Subversion's APIs, too.
[53] Subversion uses ANSI system calls and datatypes as much as possible.
[54] Neon and Berkeley DB are examples of such libraries.
Inhaltsverzeichnis
This chapter is intended to be a complete reference to using Subversion. This includes the command-line client (svn) and all its subcommands, as well as the repository administration programs (svnadmin and svnlook) and their respective subcommands.
To use the command-line client, type svn, the subcommand you wish to use, [55] and any options or targets that you wish to operate on—the subcommand and the options need not appear in a specific order. For example, all of the following are valid ways to use svn status:
$ svn -v status $ svn status -v $ svn status -v myfile
You can find many more examples of how to use most client commands in Kapitel 2, Grundlegende Benutzung and commands for managing properties in „Properties“.
While Subversion has different options for its
subcommands, all options exist in a single
namespace—that is, each option is guaranteed to mean the
same thing regardless of the subcommand you use it with. For
example, --verbose
(-v
)
always means „verbose output,“ regardless of the
subcommand you use it with.
The svn command-line client usually exits quickly with an error if you pass it an option which does not apply to the specified subcommand. But as of Subversion 1.5, several of the options which apply to all—or nearly all—of the subcommands have been deemed acceptable by all subcommands, even if they have no effect on some of them. They appear grouped together in the command-line client's usage messages as global options. This was done to assist folks who write scripts which wrap the command-line client. These global options are as follows:
--config-dir
DIR
Instructs Subversion to read configuration
information from the specified directory instead of the
default location (.subversion
in
the user's home directory).
--no-auth-cache
Prevents caching of authentication information (e.g., username and password) in the Subversion runtime configuration directories.
--non-interactive
Disables all interactive prompting. Some examples of interactive prompting include requests for authentication credentials and conflict resolution decisions. This is useful if you're running Subversion inside an automated script and it's more appropriate to have Subversion fail than to prompt for more information.
--password
PASSWD
Specifies the password to use when authenticating against a Subversion server. If not provided, or if incorrect, Subversion will prompt you for this information as needed.
--username
NAME
Specifies the username to use when authenticating against a Subversion server. If not provided, or if incorrect, Subversion will prompt you for this information as needed.
The rest of the options apply and are accepted by only a subset of the subcommand. They are as follows:
--accept
ACTION
Specifies an action for automatic conflict resolution.
Possible actions are postpone
,
base
, mine-full
,
theirs-full
, edit
, and
launch
.
--auto-props
Enables auto-props, overriding the
enable-auto-props
directive in the
config
file.
--change
(-c
)
ARG
Used as a means to refer to a specific „change“ (a.k.a. a revision). This option is syntactic sugar for „-r ARG-1:ARG“.
--changelist
ARG
Instructs Subversion to operate only on members of the changelist named
ARG
. You can use this option
multiple times to specify sets of changelists.
--cl
ARG
An alias for the
--changelist
option.
--depth
ARG
Instructs Subversion to limit the scope of an operation to a particular tree
depth. ARG
is one of
empty
, files
,
immediates
, or
infinity
.
--diff-cmd
CMD
Specifies an external program to use to show
differences between files. When svn
diff is invoked without this option, it uses
Subversion's internal diff engine, which provides
unified diffs by default. If you want to use an
external diff program, use --diff-cmd
.
You can pass options to the diff program with the
--extensions
option (more on that later
in this section).
--diff3-cmd
CMD
Specifies an external program to use to merge files.
--dry-run
Goes through all the motions of running a command, but makes no actual changes—either on disk or in the repository.
--editor-cmd
CMD
Specifies an external program to use to edit a log message
or a property value. See the editor-cmd
section in „Config“
for ways to specify a default editor.
--encoding
ENC
Tells Subversion that your commit message is encoded in the charset provided. The default is your operating system's native locale, and you should specify the encoding if your commit message is in any other encoding.
--extensions
(-x
)
ARGS
Specifies an argument or arguments that Subversion
should pass to an external diff command. This option is
valid only when used with the svn
diff or svn merge commands,
with the
--diff-cmd
option.
If you wish to pass multiple
arguments, you must enclose all of them in quotes (e.g.,
svn diff --diff-cmd /usr/bin/diff -x
"-b -E"
).
--file
(-F
)
FILENAME
Uses the contents of the named file for the specified subcommand, though different subcommands do different things with this content. For example, svn commit uses the content as a commit log, whereas svn propset uses it as a property value.
--force
Forces a particular command or operation to run. Subversion will prevent you from performing some operations in normal usage, but you can pass the force option to tell Subversion „I know what I'm doing as well as the possible repercussions of doing it, so let me at 'em.“ This option is the programmatic equivalent of doing your own electrical work with the power on—if you don't know what you're doing, you're likely to get a nasty shock.
--force-log
Forces a suspicious parameter passed to the
--message
(-m
) or
--file
(-F
) option to
be accepted as valid. By default, Subversion will
produce an error if parameters to these options look
like they might instead be targets of the subcommand.
For example, if you pass a versioned file's path to the
--file
(-F
) option,
Subversion will assume you've made a mistake, that the
path was instead intended as the target of the
operation, and that you simply failed to provide some
other—unversioned—file as the source of your
log message. To assert your intent and override these
types of errors, pass the --force-log
option to subcommands that accept log messages.
--help
(-h
) or
-?
)
If used with one or more subcommands, shows the built-in help text for each. If used alone, it displays the general client help text.
--ignore-ancestry
Tells Subversion to ignore ancestry when calculating differences (rely on path contents alone).
--ignore-externals
Tells Subversion to ignore externals definitions and the external working copies managed by them.
--incremental
Prints output in a format suitable for concatenation.
--keep-changelists
Tells Subversion not to delete changelists after committing.
--keep-local
Keeps the local copy of a file or directory (used with the svn delete command).
--limit
(-l
)
NUM
Shows only the first NUM
log messages.
--message
(-m
)
MESSAGE
Indicates that you will specify either a log message or a lock comment on the command line, following this option. For example:
$ svn commit -m "They don't make Sunday."
--new
ARG
Uses ARG
as the newer
target (for use with svn diff).
--no-auto-props
Disables auto-props, overriding the
enable-auto-props
directive in the
config
file.
--no-diff-deleted
Prevents Subversion from printing differences for deleted files. The default behavior when you remove a file is for svn diff to print the same differences that you would see if you had left the file but removed all the content.
--no-ignore
Shows files in the status listing that would
normally be omitted since they match a pattern in the
global-ignores
configuration option
or the svn:ignore
property. See „Config“ and „Ignoring Unversioned Items“ for more
information.
--no-unlock
Tells Subversion not to automatically unlock files (the default commit behavior is to unlock all files listed as part of the commit). See „Locking“ for more information.
--non-recursive
(-N
)Deprecated. Stops a subcommand from recursing into subdirectories. Most subcommands recurse by default, but some subcommands—usually those that have the potential to remove or undo your local modifications—do not.
--notice-ancestry
Pays attention to ancestry when calculating differences.
--old
ARG
Uses ARG
as the older
target (for use with svn diff).
--parents
Creates and adds nonexistent or nonversioned parent subdirectories to the working copy or repository as part of an operation. This is useful for automatically creating multiple subdirectories where none currently exist. If performed on a URL, all the directories will be created in a single commit.
--quiet
(-q
)Requests that the client print only essential information while performing an operation.
--record-only
Marks revisions as merged (for use with
--revision
).
--recursive
(-R
)Makes a subcommand recurse into subdirectories. Most subcommands recurse by default.
--reintegrate
Used with the svn merge subcommand, merges all of the source URL's changes into the working copy. See „Einen Zweig synchron halten“ for details.
--relocate
FROM TO
[PATH...]
Used with the svn switch subcommand, changes the location of the repository that your working copy references. This is useful if the location of your repository changes and you have an existing working copy that you'd like to continue to use. See svn switch for an example.
--remove
ARG
Disassociates ARG
from a
changelist
--revision
(-r
)
REV
Indicates that you're going to supply a revision (or range of revisions) for a particular operation. You can provide revision numbers, keywords, or dates (in curly braces) as arguments to the revision option. If you wish to offer a range of revisions, you can provide two revisions separated by a colon. For example:
$ svn log -r 1729 $ svn log -r 1729:HEAD $ svn log -r 1729:1744 $ svn log -r {2001-12-04}:{2002-02-17} $ svn log -r 1729:{2002-02-17}
See „Revision Keywords“ for more information.
--revprop
Operates on a revision property instead of a
property specific to a file or directory. This option
requires that you also pass a revision with the
--revision
(-r
)
option.
--set-depth
ARG
Sets the sticky depth on a directory in a working
copy to one of empty
,
files
, immediates
,
or infinity
.
--show-revs
ARG
Used to make svn mergeinfo
display either merged
or eligible
revisions.
--show-updates
(-u
)Causes the client to display information about which files in your working copy are out of date. This doesn't actually update any of your files—it just shows you which files will be updated if you then use svn update.
--stop-on-copy
Causes a Subversion subcommand that traverses the history of a versioned resource to stop harvesting that historical information when a copy—that is, a location in history where that resource was copied from another location in the repository—is encountered.
--strict
Causes Subversion to use strict semantics, a notion that is rather vague unless talking about specific subcommands (namely, svn propget).
--targets
FILENAME
Tells Subversion to get the list of files that you wish to operate on from the filename that you provide instead of listing all the files on the command line.
--use-merge-history
(-g
)Uses or displays additional information from merge history.
--verbose
(-v
)Requests that the client print out as much information as it can while running any subcommand. This may result in Subversion printing out additional fields, detailed information about every file, or additional information regarding its actions.
--version
Prints the client version info. This information
includes not only the version number of the client, but
also a listing of all repository access modules that the
client can use to access a Subversion repository.
With --quiet
(-q
) it
prints only the version number in a compact form.
--with-all-revprops
Used with the --xml
option to svn log,
will retrieve and display all revision
properties in the log output.
--with-revprop
ARG
When used with any command that writes to the
repository, sets the revision property, using the
NAME=VALUE
format,
NAME
to
VALUE
. When used with
svn log in --xml
mode, this displays the value of
ARG
in the log output.
--xml
Prints output in XML format.
Here are the various subcommands for the svn program. For the sake of brevity, we omit the global options (described in „svn Options“) from the subcommand descriptions which follow.
svn add — Add files, directories, or symbolic links.
Schedule files, directories, or symbolic links in your working copy for addition to the repository. They will be uploaded and added to the repository on your next commit. If you add something and change your mind before committing, you can unschedule the addition using svn revert.
--auto-props --depth ARG --force --no-auto-props --no-ignore --parents --quiet (-q) --targets FILENAME
To add a file to your working copy:
$ svn add foo.c A foo.c
When adding a directory, the default behavior of svn add is to recurse:
$ svn add testdir A testdir A testdir/a A testdir/b A testdir/c A testdir/d
You can add a directory without adding its contents:
$ svn add --depth=empty otherdir A otherdir
Normally, the command svn add *
will skip over any directories that are already under
version control. Sometimes, however, you may want to add
every unversioned object in your working copy, including
those hiding deeper. Passing the
--force
option makes svn
add recurse into versioned directories:
$ svn add * --force A foo.c A somedir/bar.c A (bin) otherdir/docs/baz.doc …
svn blame — Show author and revision information inline for the specified files or URLs.
Show author and revision information inline for the specified files or URLs. Each line of text is annotated at the beginning with the author (username) and the revision number for the last change to that line.
--extensions (-x) ARG --force --incremental --revision (-r) ARG --use-merge-history (-g) --verbose (-v) --xml
If you want to see blame-annotated source for
readme.txt
in your test
repository:
$ svn blame http://svn.red-bean.com/repos/test/readme.txt 3 sally This is a README file. 5 harry You should read this.
Even if svn blame says that Harry
last modified readme.txt
in revision
5, you'll have to examine exactly what the revision
changed to be sure that Harry changed
the context of the line—he may
have adjusted just the whitespace.
If you use the --xml
option, you can
get XML output describing the blame annotations, but not
the contents of the lines themselves:
$ svn blame --xml http://svn.red-bean.com/repos/test/readme.txt <?xml version="1.0"?> <blame> <target path="sandwich.txt"> <entry line-number="1"> <commit revision="3"> <author>sally</author> <date>2008-05-25T19:12:31.428953Z</date> </commit> </entry> <entry line-number="2"> <commit revision="5"> <author>harry</author> <date>2008-05-29T03:26:12.293121Z</date> </commit> </entry> </target> </blame>
svn cat — Output the contents of the specified files or URLs.
Output the contents of the specified files or URLs. For listing the contents of directories, see svn list later in this chapter.
If you want to view readme.txt
in
your repository without checking it out:
$ svn cat http://svn.red-bean.com/repos/test/readme.txt This is a README file. You should read this.
If your working copy is out of date (or you have
local modifications) and you want to see the
HEAD
revision of a file in your
working copy, svn cat -r HEAD FILENAME
will
automatically fetch the HEAD
revision
of the specified path:
$ cat foo.c This file is in my local working copy and has changes that I've made. $ svn cat -r HEAD foo.c Latest revision fresh from the repository!
svn changelist — Associate (or deassociate) local paths with a changelist.
Used for dividing files in a working copy into a changelist (logical named grouping) in order to allow users to easily work on multiple file collections within a single working copy.
Edit three files, add them to a changelist, then commit only files in that changelist:
$ svn cl issue1729 foo.c bar.c baz.c Path 'foo.c' is now a member of changelist 'issue1729'. Path 'bar.c' is now a member of changelist 'issue1729'. Path 'baz.c' is now a member of changelist 'issue1729'. $ svn status A someotherfile.c A test/sometest.c --- Changelist 'issue1729': A foo.c A bar.c A baz.c $ svn commit --changelist issue1729 -m "Fixing Issue 1729." Adding bar.c Adding baz.c Adding foo.c Transmitting file data ... Committed revision 2. $ svn status A someotherfile.c A test/sometest.c
Note that only the files in changelist
issue1729
were
committed.
svn checkout — Check out a working copy from a repository.
Check out a working copy from a repository. If
PATH
is omitted, the
basename of the URL will be used as the destination.
If multiple URLs are given, each will be checked out into a
subdirectory of PATH
, with the
name of the subdirectory being the basename of the
URL.
Check out a working copy into a directory called
mine
:
$ svn checkout file:///var/svn/repos/test mine A mine/a A mine/b A mine/c A mine/d Checked out revision 20. $ ls mine
Check out two different directories into two separate working copies:
$ svn checkout file:///var/svn/repos/test file:///var/svn/repos/quiz A test/a A test/b A test/c A test/d Checked out revision 20. A quiz/l A quiz/m Checked out revision 13. $ ls quiz test
Check out two different directories into two separate
working copies, but place both into a directory called
working-copies
:
$ svn checkout file:///var/svn/repos/test file:///var/svn/repos/quiz working-copies A working-copies/test/a A working-copies/test/b A working-copies/test/c A working-copies/test/d Checked out revision 20. A working-copies/quiz/l A working-copies/quiz/m Checked out revision 13. $ ls working-copies
If you interrupt a checkout (or something else interrupts your checkout, such as loss of connectivity, etc.), you can restart it either by issuing the identical checkout command again or by updating the incomplete working copy:
$ svn checkout file:///var/svn/repos/test mine A mine/a A mine/b ^C svn: The operation was interrupted svn: caught SIGINT $ svn checkout file:///var/svn/repos/test mine A mine/c ^C svn: The operation was interrupted svn: caught SIGINT $ svn update mine A mine/d Updated to revision 20.
If you wish to check out some revision other than the
most recent one, you can do so by providing the
--revision
(-r
) option
to the svn checkout command:
$ svn checkout -r 2 file:///var/svn/repos/test mine A mine/a Checked out revision 2.
svn cleanup — Recursively clean up the working copy
Recursively clean up the working copy, removing
working copy locks and resuming unfinished operations. If
you ever get a working copy locked
error, run this command to remove stale locks and get your
working copy into a usable state again.
If, for some reason, an svn update
fails due to a problem running an external diff program
(e.g., user input or network failure), pass the
--diff3-cmd
to allow cleanup to complete
any merging with your external diff program. You can also
specify any configuration directory with the
--config-dir
option, but you should need
these options extremely infrequently.
svn commit — Send changes from your working copy to the repository.
Send changes from your working copy to the
repository. If you do not supply a log message with your
commit by using either the --file
or
--message
option,
svn will launch your editor for you
to compose a commit message. See the
editor-cmd
list entry in „Config“.
svn commit will send any lock
tokens that it finds and will release locks on all
PATH
s committed (recursively)
unless --no-unlock
is passed.
If you begin a commit and Subversion launches your editor to compose the commit message, you can still abort without committing your changes. If you want to cancel your commit, just quit your editor without saving your commit message and Subversion will prompt you to either abort the commit, continue with no message, or edit the message again.
--changelist ARG --depth ARG --editor-cmd ARG --encoding ENC --file (-F) FILE --force-log --keep-changelists --message (-m) TEXT --no-unlock --quiet (-q) --targets FILENAME --with-revprop ARG
Commit a simple modification to a file with the
commit message on the command line and an implicit
target of your current directory
(„.
“):
$ svn commit -m "added howto section." Sending a Transmitting file data . Committed revision 3.
Commit a modification to the file
foo.c
(explicitly specified on the
command line) with the commit message in a file named
msg
:
$ svn commit -F msg foo.c Sending foo.c Transmitting file data . Committed revision 5.
If you want to use a file that's under version
control for your commit message with
--file
, you need to pass the
--force-log
option:
$ svn commit --file file_under_vc.txt foo.c svn: The log message file is under version control svn: Log message file is a versioned file; use '--force-log' to override $ svn commit --force-log --file file_under_vc.txt foo.c Sending foo.c Transmitting file data . Committed revision 6.
To commit a file scheduled for deletion:
$ svn commit -m "removed file 'c'." Deleting c Committed revision 7.
svn copy — Copy a file or directory in a working copy or in the repository.
Copy one or more files in a working copy or in the
repository. When copying multiple sources, they will be
added as children of DST
, which must be a directory.
SRC
and
DST
can each be either a
working copy (WC) path or URL:
Copy and schedule an item for addition (with history).
Immediately commit a copy of WC to URL.
Check out URL into WC and schedule it for addition.
Complete server-side copy. This is usually used to branch and tag.
When copying multiple sources, they will be added as
children of DST
, which must be
a directory.
If no peg revision (i.e.,
@REV
) is supplied, by default
the BASE
revision will be used for
files copied from the working copy, while the
HEAD
revision will be used for files
copied from a URL.
You can only copy files within a single repository. Subversion does not support cross-repository copying.
Yes, if source or destination is in the repository, or if needed to look up the source revision number.
--editor-cmd EDITOR --encoding ENC --file (-F) FILE --force-log --message (-m) TEXT --parents --quiet (-q) --revision (-r) REV --with-revprop ARG
Copy an item within your working copy (this schedules the copy—nothing goes into the repository until you commit):
$ svn copy foo.txt bar.txt A bar.txt $ svn status A + bar.txt
Copy several files in a working copy into a subdirectory:
$ svn cp bat.c baz.c qux.c src A src/bat.c A src/baz.c A src/qux.c
Copy revision 8 of bat.c
into your
working copy under a different name:
$ svn cp -r 8 bat.c ya-old-bat.c A ya-old-bat.c
Copy an item in your working copy to a URL in the repository (this is an immediate commit, so you must supply a commit message):
$ svn copy near.txt file:///var/svn/repos/test/far-away.txt -m "Remote copy." Committed revision 8.
Copy an item from the repository to your working copy (this just schedules the copy—nothing goes into the repository until you commit):
$ svn copy file:///var/svn/repos/test/far-away -r 6 near-here A near-here
This is the recommended way to resurrect a dead file in your repository!
And finally, copy between two URLs:
$ svn copy file:///var/svn/repos/test/far-away \ file:///var/svn/repos/test/over-there -m "remote copy." Committed revision 9.
$ svn copy file:///var/svn/repos/test/trunk \ file:///var/svn/repos/test/tags/0.6.32-prerelease -m "tag tree" Committed revision 12.
This is the easiest way to „tag“ a
revision in your repository—just svn
copy that revision (usually
HEAD
) into your tags
directory.
And don't worry if you forgot to tag—you can always specify an older revision and tag anytime:
$ svn copy -r 11 file:///var/svn/repos/test/trunk \ file:///var/svn/repos/test/tags/0.6.32-prerelease \ -m "Forgot to tag at rev 11" Committed revision 13.
svn delete — Delete an item from a working copy or the repository.
Items specified by PATH
are
scheduled for deletion upon the next commit. Files (and
directories that have not been committed) are immediately
removed from the working copy unless the
--keep-local
option is given. The
command will not remove any unversioned or modified items;
use the --force
option to override this
behavior.
Items specified by URL are deleted from the repository via an immediate commit. Multiple URLs are committed atomically.
--editor-cmd EDITOR --encoding ENC --file (-F) FILE --force --force-log --keep-local --message (-m) TEXT --quiet (-q) --targets FILENAME --with-revprop ARG
Using svn to delete a file from your working copy deletes your local copy of the file, but it merely schedules the file to be deleted from the repository. When you commit, the file is deleted in the repository.
$ svn delete myfile D myfile $ svn commit -m "Deleted file 'myfile'." Deleting myfile Transmitting file data . Committed revision 14.
Deleting a URL, however, is immediate, so you have to supply a log message:
$ svn delete -m "Deleting file 'yourfile'" \ file:///var/svn/repos/test/yourfile Committed revision 15.
Here's an example of how to force deletion of a file that has local mods:
$ svn delete over-there svn: Attempting restricted operation for modified resource svn: Use --force to override this restriction svn: 'over-there' has local modifications $ svn delete --force over-there D over-there
svn diff — This displays the differences between two revisions or paths.
diff [-c M | -r N[:M]] [TARGET[@REV]...]
diff [-r N[:M]] --old=OLD-TGT[@OLDREV] [--new=NEW-TGT[@NEWREV]] [PATH...]
diff OLD-URL[@OLDREV] NEW-URL[@NEWREV]
Display the differences between two paths. You can use svn diff in the following ways:
Use just svn diff to display local modifications in a working copy.
Display the changes made to
TARGET
s as they are seen in
REV
between two revisions.
TARGET
s may be all working copy
paths or all URL
s. If
TARGET
s are working copy paths,
N
defaults to
BASE
and M
to the working copy; if TARGET
s
are URL
s,
N
must be specified and
M
defaults to
HEAD
. The -c M
option
is equivalent to -r N:M
where N =
M-1
. Using -c -M
does the
reverse: -r M:N
where N =
M-1
.
Display the differences between
OLD-TGT
as it was seen in
OLDREV
and
NEW-TGT
as it was seen in
NEWREV
.
PATH
s, if given, are relative
to OLD-TGT
and
NEW-TGT
and restrict the output
to differences for those paths.
OLD-TGT
and
NEW-TGT
may be working copy
paths or URL[@REV]
.
NEW-TGT
defaults to
OLD-TGT
if not specified.
-r N
makes OLDREV
default to
N
; -r N:M
makes OLDREV
default to
N
and
NEWREV
default to
M
.
svn diff OLD-URL[@OLDREV]
NEW-URL[@NEWREV]
is shorthand for svn
diff --old=OLD-URL[@OLDREV]
--new=NEW-URL[@NEWREV].
svn diff -r N:M URL
is shorthand
for svn diff -r N:M --old=URL
--new=URL
.
svn diff [-r N[:M]] URL1[@N]
URL2[@M]
is shorthand for svn diff [-r
N[:M]] --old=URL1 --new=URL2
.
If TARGET
is a URL, then
revs N
and M
can be given either via the
--revision
option or by using the
„@“ notation as described earlier.
If TARGET
is a working copy
path, the default behavior (when no
--revision
option is provided) is to
display the differences between the base and working
copies of TARGET
. If a
--revision
option is specified in this
scenario, though, it means:
--revision N:M
The server compares
TARGET@N
and
TARGET@M
.
--revision N
The client compares
TARGET@N
against the working copy.
If the alternate syntax is used, the server compares
URL1
and
URL2
at revisions
N
and
M
, respectively. If either
N
or
M
is omitted, a value of
HEAD
is assumed.
By default, svn diff ignores the
ancestry of files and merely compares the contents of the
two files being compared. If you use
--notice-ancestry
, the ancestry of the
paths in question will be taken into consideration when
comparing revisions (i.e., if you run svn
diff on two files with identical contents but
different ancestry, you will see the entire contents of
the file as having been removed and added again).
For obtaining differences against anything but
BASE
revision in your working copy
--change (-c) ARG --changelist ARG --depth ARG --diff-cmd CMD --extensions (-x) "ARGS" --force --new ARG --no-diff-deleted --notice-ancestry --old ARG --revision (-r) ARG --summarize --xml
Compare BASE
and your working copy
(one of the most popular uses of svn
diff):
$ svn diff COMMITTERS Index: COMMITTERS =================================================================== --- COMMITTERS (revision 4404) +++ COMMITTERS (working copy)
See what changed in the file
COMMITTERS
revision 9115:
$ svn diff -c 9115 COMMITTERS Index: COMMITTERS =================================================================== --- COMMITTERS (revision 3900) +++ COMMITTERS (working copy)
See how your working copy's modifications compare against an older revision:
$ svn diff -r 3900 COMMITTERS Index: COMMITTERS =================================================================== --- COMMITTERS (revision 3900) +++ COMMITTERS (working copy)
Compare revision 3000 to revision 3500 using „@“ syntax:
$ svn diff http://svn.collab.net/repos/svn/trunk/COMMITTERS@3000 \ http://svn.collab.net/repos/svn/trunk/COMMITTERS@3500 Index: COMMITTERS =================================================================== --- COMMITTERS (revision 3000) +++ COMMITTERS (revision 3500) …
Compare revision 3000 to revision 3500 using range notation (pass only the one URL in this case):
$ svn diff -r 3000:3500 http://svn.collab.net/repos/svn/trunk/COMMITTERS Index: COMMITTERS =================================================================== --- COMMITTERS (revision 3000) +++ COMMITTERS (revision 3500)
Compare revision 3000 to revision 3500 of all the files in
trunk
using range notation:
$ svn diff -r 3000:3500 http://svn.collab.net/repos/svn/trunk
Compare revision 3000 to revision 3500 of only three
files in trunk
using range
notation:
$ svn diff -r 3000:3500 --old http://svn.collab.net/repos/svn/trunk \ COMMITTERS README HACKING
If you have a working copy, you can obtain the differences without typing in the long URLs:
$ svn diff -r 3000:3500 COMMITTERS Index: COMMITTERS =================================================================== --- COMMITTERS (revision 3000) +++ COMMITTERS (revision 3500)
Use --diff-cmd
CMD
-x
to
pass arguments directly to the external diff
program:
$ svn diff --diff-cmd /usr/bin/diff -x "-i -b" COMMITTERS Index: COMMITTERS =================================================================== 0a1,2 > This is a test >
Lastly, you can use the --xml
option
along with the --summarize
option to view
XML describing the changes that occurred between
revisions, but not the contents of the diff itself:
$ svn diff --summarize --xml http://svn.red-bean.com/repos/test@r2 \ http://svn.red-bean.com/repos/test <?xml version="1.0"?> <diff> <paths> <path props="none" kind="file" item="modified">http://svn.red-bean.com/repos/test/sandwich.txt</path> <path props="none" kind="file" item="deleted">http://svn.red-bean.com/repos/test/burrito.txt</path> <path props="none" kind="dir" item="added">http://svn.red-bean.com/repos/test/snacks</path> </paths> </diff>
svn export — Export a clean directory tree.
The first form exports a clean directory tree from the
repository specified by URL
—at revision
REV
if it is given; otherwise,
at HEAD
, into
PATH
. If
PATH
is omitted, the last
component of the URL
is used
for the local directory name.
The second form exports a clean directory tree from
the working copy specified by
PATH1
into
PATH2
. All local changes will
be preserved, but files not under version control will not
be copied.
Export from your working copy (doesn't print every file and directory):
$ svn export a-wc my-export Export complete.
Export directly from the repository (prints every file and directory):
$ svn export file:///var/svn/repos my-export A my-export/test A my-export/quiz … Exported revision 15.
When rolling operating-system-specific release
packages, it can be useful to export a tree that uses a
specific EOL character for line endings. The
--native-eol
option will do this, but it
affects only files that have svn:eol-style =
native
properties attached to them. For
example, to export a tree with all CRLF line endings
(possibly for a Windows .zip
file
distribution):
$ svn export file:///var/svn/repos my-export --native-eol CRLF A my-export/test A my-export/quiz … Exported revision 15.
You can specify LR
,
CR
, or CRLF
as a
line-ending type with the --native-eol
option.
svn help — Help!
svn import — Commit an unversioned file or tree into the repository.
Recursively commit a copy of
PATH
to
URL
. If
PATH
is omitted,
„.
“ is assumed. Parent
directories are created in the repository as necessary.
Unversionable items such as device files and pipes are
ignored even if --force
is
specified.
--auto-props --depth ARG --editor-cmd EDITOR --encoding ENC --file (-F) FILE --force --force-log --message (-m) TEXT --no-auto-props --no-ignore --quiet (-q) --with-revprop ARG
This imports the local directory
myproj
into
trunk/misc
in your repository. The
directory trunk/misc
need not exist
before you import into it—svn
import will recursively create directories for
you.
$ svn import -m "New import" myproj \ http://svn.red-bean.com/repos/trunk/misc Adding myproj/sample.txt … Transmitting file data ......... Committed revision 16.
Be aware that this will not
create a directory named myproj
in
the repository. If that's what you want, simply add
myproj
to the end of the URL:
$ svn import -m "New import" myproj \ http://svn.red-bean.com/repos/trunk/misc/myproj Adding myproj/sample.txt … Transmitting file data ......... Committed revision 16.
After importing data, note that the original tree is not under version control. To start working, you still need to svn checkout a fresh working copy of the tree.
svn info — Display information about a local or remote item.
Print information about the working copy paths or URLs specified. The information shown for both may include:
Path
Name
URL
Repository root
Repository UUID
Revision
Node kind
Last changed author
Last changed revision
Last changed date
Lock token
Lock owner
Lock created (date)
Lock expires (date)
Additional kinds of information available only for working copy paths are:
Schedule
Copied from URL
Copied from rev
Text last updated
Properties last updated
Checksum
Conflict previous base file
Conflict previous working file
Conflict current base file
Conflict properties file
--changelist ARG --depth ARG --incremental --recursive (-R) --revision (-r) REV --targets FILENAME --xml
svn info will show you all the useful information that it has for items in your working copy. It will show information for files:
$ svn info foo.c Path: foo.c Name: foo.c URL: http://svn.red-bean.com/repos/test/foo.c Repository Root: http://svn.red-bean.com/repos/test Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25 Revision: 4417 Node Kind: file Schedule: normal Last Changed Author: sally Last Changed Rev: 20 Last Changed Date: 2003-01-13 16:43:13 -0600 (Mon, 13 Jan 2003) Text Last Updated: 2003-01-16 21:18:16 -0600 (Thu, 16 Jan 2003) Properties Last Updated: 2003-01-13 21:50:19 -0600 (Mon, 13 Jan 2003) Checksum: d6aeb60b0662ccceb6bce4bac344cb66
It will also show information for directories:
$ svn info vendors Path: vendors URL: http://svn.red-bean.com/repos/test/vendors Repository Root: http://svn.red-bean.com/repos/test Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25 Revision: 19 Node Kind: directory Schedule: normal Last Changed Author: harry Last Changed Rev: 19 Last Changed Date: 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003) Properties Last Updated: 2003-01-16 23:39:02 -0600 (Thu, 16 Jan 2003)
svn info also acts on URLs (also
note that the file readme.doc
in
this example is locked, so lock information is also
provided):
$ svn info http://svn.red-bean.com/repos/test/readme.doc Path: readme.doc Name: readme.doc URL: http://svn.red-bean.com/repos/test/readme.doc Repository Root: http://svn.red-bean.com/repos/test Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25 Revision: 1 Node Kind: file Schedule: normal Last Changed Author: sally Last Changed Rev: 42 Last Changed Date: 2003-01-14 23:21:19 -0600 (Tue, 14 Jan 2003) Lock Token: opaquelocktoken:14011d4b-54fb-0310-8541-dbd16bd471b2 Lock Owner: harry Lock Created: 2003-01-15 17:35:12 -0600 (Wed, 15 Jan 2003) Lock Comment (1 line): My test lock comment
Lastly, svn info output is
available in XML format by passing
the--xml
option:
$ svn info --xml http://svn.red-bean.com/repos/test <?xml version="1.0"?> <info> <entry kind="dir" path="." revision="1"> <url>http://svn.red-bean.com/repos/test</url> <repository> <root>http://svn.red-bean.com/repos/test</root> <uuid>5e7d134a-54fb-0310-bd04-b611643e5c25</uuid> </repository> <wc-info> <schedule>normal</schedule> <depth>infinity</depth> </wc-info> <commit revision="1"> <author>sally</author> <date>2003-01-15T23:35:12.847647Z</date> </commit> </entry> </info>
svn list — List directory entries in the repository.
List each TARGET
file and
the contents of each TARGET
directory as they exist in the repository. If
TARGET
is a working copy path,
the corresponding repository URL will be used.
The default TARGET
is
„.
“, meaning the
repository URL of the current working copy
directory.
With --verbose
, svn
list shows the following fields for each
item:
Revision number of the last commit
Author of the last commit
If locked, the letter „O“ (see the preceding section on svn info for details).
Size (in bytes)
Date and time of the last commit
With --xml
, output is in XML format (with
a header and an enclosing document element unless
--incremental
is also specified). All of the
information is present; the --verbose
option
is not accepted.
svn list is most useful if you want to see what files a repository has without downloading a working copy:
$ svn list http://svn.red-bean.com/repos/test/support README.txt INSTALL examples/ …
You can pass the --verbose
option for
additional information, rather like the Unix command
ls -l:
$ svn list --verbose file:///var/svn/repos 16 sally 28361 Jan 16 23:18 README.txt 27 sally 0 Jan 18 15:27 INSTALL 24 harry Jan 18 11:27 examples/
You can also get svn list output in
XML format with the --xml
option:
$ svn list --xml http://svn.red-bean.com/repos/test <?xml version="1.0"?> <lists> <list path="http://svn.red-bean.com/repos/test"> <entry kind="dir"> <name>examples</name> <size>0</size> <commit revision="24"> <author>harry</author> <date>2008-01-18T06:35:53.048870Z</date> </commit> </entry> ... </list> </lists>
For further details, see the earlier section „svn list“.
svn lock — Lock working copy paths or URLs in the repository so that no other user can commit changes to them.
Lock each TARGET
. If any
TARGET
is already locked by
another user, print a warning and continue locking the
rest of the TARGET
s. Use
--force
to steal a lock from another user
or working copy.
Lock two files in your working copy:
$ svn lock tree.jpg house.jpg 'tree.jpg' locked by user 'harry'. 'house.jpg' locked by user 'harry'.
Lock a file in your working copy that is currently locked by another user:
$ svn lock tree.jpg svn: warning: Path '/tree.jpg is already locked by user 'sally in \ filesystem '/var/svn/repos/db' $ svn lock --force tree.jpg 'tree.jpg' locked by user 'harry'.
Lock a file without a working copy:
$ svn lock http://svn.red-bean.com/repos/test/tree.jpg 'tree.jpg' locked by user 'harry'.
For further details, see „Locking“.
svn log — Display commit log messages.
Shows log messages from the repository.
If no arguments are supplied, svn
log shows the log messages for all files and
directories inside (and including) the current working
directory of your working copy. You can refine the
results by specifying a path, one or more revisions, or
any combination of the two. The default revision range
for a local path is BASE:1
.
If you specify a URL alone, it prints log
messages for everything the URL contains. If you
add paths past the URL, only messages for those paths
under that URL will be printed. The default revision range
for a URL is HEAD:1
.
With --verbose
, svn log
will also print all affected paths with each log message.
With --quiet
, svn log
will not print the log message body itself (this is
compatible with --verbose
).
Each log message is printed just once, even if more
than one of the affected paths for that revision were
explicitly requested. Logs follow copy history by
default. Use --stop-on-copy
to disable
this behavior, which can be useful for determining branch
points.
--change (-c) ARG --incremental --limit (-l) NUM --quiet (-q) --revision (-r) REV --stop-on-copy --targets FILENAME --use-merge-history (-g) --verbose (-v) --with-all-revprops --with-revprop ARG --xml
You can see the log messages for all the paths that
changed in your working copy by running svn
log
from the top:
$ svn log ------------------------------------------------------------------------ r20 | harry | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line Tweak. ------------------------------------------------------------------------ r17 | sally | 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003) | 2 lines …
Examine all log messages for a particular file in your working copy:
$ svn log foo.c ------------------------------------------------------------------------ r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line Added defines. ------------------------------------------------------------------------ r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines …
If you don't have a working copy handy, you can log a URL:
$ svn log http://svn.red-bean.com/repos/test/foo.c ------------------------------------------------------------------------ r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line Added defines. ------------------------------------------------------------------------ r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines …
If you want several distinct paths underneath the
same URL, you can use the URL [PATH...]
syntax:
$ svn log http://svn.red-bean.com/repos/test/ foo.c bar.c ------------------------------------------------------------------------ r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line Added defines. ------------------------------------------------------------------------ r31 | harry | 2003-01-10 12:25:08 -0600 (Fri, 10 Jan 2003) | 1 line Added new file bar.c ------------------------------------------------------------------------ r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines …
The --verbose
option causes
svn log to include information about
the paths that were changed in each displayed revision.
These paths appear, one path per line of output, with
action codes that indicate what type of change was made to
the path.
$ svn log -v http://svn.red-bean.com/repos/test/ foo.c bar.c ------------------------------------------------------------------------ r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line Changed paths: M /foo.c Added defines. ------------------------------------------------------------------------ r31 | harry | 2003-01-10 12:25:08 -0600 (Fri, 10 Jan 2003) | 1 line Changed paths: A /bar.c Added new file bar.c ------------------------------------------------------------------------ r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines …
svn log uses just a handful of action codes, and they are similar to the ones the svn update command uses:
A
The item was added.
D
The item was deleted.
M
Properties or textual contents on the item were changed.
R
The item was replaced by a different one at the same location.
In addition to the action codes which precede the
changed paths, svn log with the --verbose
option will
note whether a path was added or replaced as the result of a copy
operation. It does so by printing (from
after such paths.COPY-FROM-PATH
:COPY-FROM-REV
)
When you're concatenating the results of multiple
calls to the log command, you may want to use the
--incremental
option. svn
log normally prints out a dashed line at the
beginning of a log message, after each subsequent log
message, and following the final log message. If you
ran svn log on a range of two
revisions, you would get this:
$ svn log -r 14:15 ------------------------------------------------------------------------ r14 | … ------------------------------------------------------------------------ r15 | … ------------------------------------------------------------------------
However, if you wanted to gather two nonsequential log messages into a file, you might do something like this:
$ svn log -r 14 > mylog $ svn log -r 19 >> mylog $ svn log -r 27 >> mylog $ cat mylog ------------------------------------------------------------------------ r14 | … ------------------------------------------------------------------------ ------------------------------------------------------------------------ r19 | … ------------------------------------------------------------------------ ------------------------------------------------------------------------ r27 | … ------------------------------------------------------------------------
You can avoid the clutter of the double dashed lines
in your output by using the --incremental
option:
$ svn log --incremental -r 14 > mylog $ svn log --incremental -r 19 >> mylog $ svn log --incremental -r 27 >> mylog $ cat mylog ------------------------------------------------------------------------ r14 | … ------------------------------------------------------------------------ r19 | … ------------------------------------------------------------------------ r27 | …
The --incremental
option provides
similar output control when using the
--xml
option:
$ svn log --xml --incremental -r 1 sandwich.txt <logentry revision="1"> <author>harry</author> <date>2008-06-03T06:35:53.048870Z</date> <msg>Initial Import.</msg> </logentry>
Sometimes when you run svn log on a specific path and a specific revision, you see no log information output at all, as in the following:
$ svn log -r 20 http://svn.red-bean.com/untouched.txt ------------------------------------------------------------------------
That just means the path wasn't modified in that revision. To get log information for that revision, either run the log operation against the repository's root URL, or specify a path that you happen to know was changed in that revision:
$ svn log -r 20 touched.txt ------------------------------------------------------------------------ r20 | sally | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line Made a change. ------------------------------------------------------------------------
svn merge — Apply the differences between two sources to a working copy path.
svn merge sourceURL1[@N] sourceURL2[@M] [WCPATH]
svn merge sourceWCPATH1@N sourceWCPATH2@M [WCPATH]
svn merge [[-c M]... | [-r N:M]...] [SOURCE[@REV] [WCPATH]]
In the first form, the source URLs are specified at
revisions N
and M
.
These are the two sources to be compared. The revisions
default to HEAD
if omitted.
In the second form, the URLs corresponding to the source working copy paths define the sources to be compared. The revisions must be specified.
In the third form, SOURCE
can be either a URL or a working copy path (in which case
its corresponding URL is used). If not specified,
SOURCE
will be the same as
WCPATH
.
SOURCE
in revision
REV
is compared as it existed
between revisions N
and
M
for each revision range
provided. If REV
is not
specified, HEAD
is assumed.
-c M
is equivalent to -r
<M-1>:M
, and -c -M
does
the reverse: -r M:<M-1>
. If no
revision ranges are specified, the default range of
1:HEAD
is used. Multiple
-c
and/or -r
instances may be specified, and mixing of forward and
reverse ranges is allowed—the ranges are internally
compacted to their minimum representation before merging
begins (which may result in no-op).
WCPATH
is the working copy
path that will receive the changes. If
WCPATH
is omitted, a default
value of „.
“ is assumed,
unless the sources have identical basenames that match a
file within „.
“. In
this case, the differences will be applied to that
file.
Subversion will internally track metadata about the merge operation only if the two sources are ancestrally related—if the first source is an ancestor of the second or vice versa. This is guaranteed to be the case when using the third form. Unlike svn diff, the merge command takes the ancestry of a file into consideration when performing a merge operation. This is very important when you're merging changes from one branch into another and you've renamed a file on one branch but not the other.
--accept ARG --change (-c) REV --depth ARG --diff3-cmd CMD --dry-run --extensions (-x) ARG --force --ignore-ancestry --quiet (-q) --record-only --reintegrate --revision (-r) REV
Merge a branch back into the trunk (assuming that you have an up-to-date working copy of the trunk):
$ svn merge --reintegrate \ http://svn.example.com/repos/calc/branches/my-calc-branch --- Merging differences between repository URLs into '.': U button.c U integer.c U Makefile U . $ # build, test, verify, ... $ svn commit -m "Merge my-calc-branch back into trunk!" Sending . Sending button.c Sending integer.c Sending Makefile Transmitting file data .. Committed revision 391.
To merge changes to a single file:
$ cd myproj $ svn merge -r 30:31 thhgttg.txt U thhgttg.txt
svn mergeinfo — Query merge-related information. See „Mergeinfo und Vorschauen“ for details.
Query information related to merges (or potential
merges) between SOURCE-URL
and
TARGET
. If
the --show-revs
option is not provided,
display revisions which have been merged
from SOURCE-URL
to TARGET
. Otherwise, display
either merged
or eligible
revisions as specified by
the --show-revs
option.
svn mkdir — Create a new directory under version control.
Create a directory with a name given by the final
component of the PATH
or URL
.
A directory specified by a working copy
PATH
is scheduled for addition
in the working copy. A directory specified by a URL is
created in the repository via an immediate commit.
Multiple directory URLs are committed atomically. In both
cases, all the intermediate directories must already exist
unless the --parents
option is
used.
svn move — Move a file or directory.
This command moves files or directories in your working copy or in the repository.
This command is equivalent to an svn copy followed by svn delete.
When moving multiple sources, they will be added as
children of DST
, which must be
a directory.
Subversion does not support moving between working copies and URLs. In addition, you can only move files within a single repository—Subversion does not support cross-repository moving. Subversion supports the following types of moves within a single repository:
Move and schedule a file or directory for addition (with history).
Complete server-side rename.
--editor-cmd EDITOR --encoding ENC --file (-F) FILE --force --force-log --message (-m) TEXT --parents --quiet (-q) --revision (-r) REV --with-revprop ARG
Move a file in your working copy:
$ svn move foo.c bar.c A bar.c D foo.c
Move several files in your working copy into a subdirectory:
$ svn move baz.c bat.c qux.c src A src/baz.c D baz.c A src/bat.c D bat.c A src/qux.c D qux.c
Move a file in the repository (this is an immediate commit, so it requires a commit message):
$ svn move -m "Move a file" http://svn.red-bean.com/repos/foo.c \ http://svn.red-bean.com/repos/bar.c Committed revision 27.
svn propdel — Remove a property from an item.
svn propedit — Edit the property of one or more items under version control. See svn propset later in this chapter.
Edit one or more properties using your favorite
editor. The first form edits versioned properties in
your working copy, and the second edits unversioned
remote properties on a repository revision
(TARGET
determines only which
repository to access).
--editor-cmd EDITOR --encoding ENC --file (-F) ARG --force --force-log --message (-m) ARG --revision (-r) REV --revprop --with-revprop ARG
svn propedit makes it easy to modify properties that have multiple values:
$ svn propedit svn:keywords foo.c <svn will launch your favorite editor here, with a buffer open containing the current contents of the svn:keywords property. You can add multiple values to a property easily here by entering one value per line.> Set new value for property 'svn:keywords' on 'foo.c'
svn propget — Print the value of a property.
Print the value of a property on files, directories, or revisions. The first form prints the versioned property of an item or items in your working copy, and the second prints unversioned remote properties on a repository revision. See „Properties“ for more information on properties.
Examine a property of a file in your working copy:
$ svn propget svn:keywords foo.c Author Date Rev
The same goes for a revision property:
$ svn propget svn:log --revprop -r 20 Began journal.
Lastly, you can get svn propget
output in XML format with the --xml
option:
$ svn propget --xml svn:ignore . <?xml version="1.0"?> <properties> <target path=""> <property name="svn:ignore">*.o </property> </target> </properties>
svn proplist — List all properties.
List all properties on files, directories, or
revisions. The first form lists versioned properties in
your working copy, and the second lists unversioned remote
properties on a repository revision
(TARGET
determines only which
repository to access).
--changelist ARG --depth ARG --quiet (-q) --recursive (-R) --revision (-r) REV --revprop --verbose (-v) --xml
You can use proplist to see the properties on an item in your working copy:
$ svn proplist foo.c Properties on 'foo.c': svn:mime-type svn:keywords owner
But with the --verbose
flag, svn
proplist is extremely handy as it also shows you the
values for the properties:
$ svn proplist --verbose foo.c Properties on 'foo.c': svn:mime-type : text/plain svn:keywords : Author Date Rev owner : sally
Lastly, you can get svn proplist
output in xml format with the --xml
option:
$ svn proplist --xml <?xml version="1.0"?> <properties> <target path="."> <property name="svn:ignore"/> </target> </properties>
svn propset — Set PROPNAME
to PROPVAL
on files, directories, or revisions.
svn propset PROPNAME [PROPVAL | -F VALFILE] PATH...
svn propset PROPNAME --revprop -r REV [PROPVAL | -F VALFILE] [TARGET]
Set PROPNAME
to
PROPVAL
on files, directories,
or revisions. The first example creates a versioned, local
property change in the working copy, and the second
creates an unversioned, remote property change on a
repository revision
(TARGET
determines only which
repository to access).
Subversion has a number of „special“ properties that affect its behavior. See „Subversion Properties“ later in this chapter for more on these properties.
--changelist ARG --depth ARG --encoding ENC --file (-F) FILE --force --quiet (-q) --recursive (-R) --revision (-r) REV --revprop --targets FILENAME
Set the MIME type for a file:
$ svn propset svn:mime-type image/jpeg foo.jpg property 'svn:mime-type' set on 'foo.jpg'
On a Unix system, if you want a file to have the executable permission set:
$ svn propset svn:executable ON somescript property 'svn:executable' set on 'somescript'
Perhaps you have an internal policy to set certain properties for the benefit of your coworkers:
$ svn propset owner sally foo.c property 'owner' set on 'foo.c'
If you made a mistake in a log message for a
particular revision and want to change it, use
--revprop
and set svn:log
to the new log message:
$ svn propset --revprop -r 25 svn:log "Journaled about trip to New York." property 'svn:log' set on repository revision '25'
Or, if you don't have a working copy, you can provide a URL:
$ svn propset --revprop -r 26 svn:log "Document nap." \ http://svn.red-bean.com/repos property 'svn:log' set on repository revision '25'
Lastly, you can tell propset to take its input from a file. You could even use this to set the contents of a property to something binary:
$ svn propset owner-pic -F sally.jpg moo.c property 'owner-pic' set on 'moo.c'
By default, you cannot modify revision properties
in a Subversion repository. Your repository
administrator must explicitly enable revision property
modifications by creating a hook named
pre-revprop-change
. See „Erstellen von Repository-Hooks“ for more information on
hook scripts.
svn resolve — Resolve conflicts on working copy files or directories.
Resolve „conflicted“ state on working
copy files or directories. This routine does not
semantically resolve conflict markers; however, it
replaces PATH
with the version
specified by the --accept
argument and
then removes conflict-related artifact files. This allows
PATH
to be committed
again—that is, it tells Subversion that the
conflicts have been
„resolved.“. You can pass the following
arguments to the --accept
command
depending on your desired resolution:
base
Choose the file that was the
BASE
revision before you updated
your working copy. That is, the file that you
checked out before you made your latest
edits.
working
Assuming that you've manually handled the conflict resolution, choose the version of the file as it currently stands in your working copy.
mine-full
Resolve all conflicted files with copies of the files as they stood immediately before you ran svn update.
theirs-full
Resolve all conflicted files with copies of the files that were fetched from the server when you ran svn update.
See „Konflikte auflösen (Änderungen anderer einarbeiten)“ for an in-depth look at resolving conflicts.
Here's an example where, after a postponed conflict
resolution during update, svn resolve
replaces the all conflicts in
file foo.c
with your edits:
$ svn up Conflict discovered in 'foo.c'. Select: (p) postpone, (df) diff-full, (e) edit, (h) help for more options: p C foo.c Updated to revision 5. $ svn resolve --accept mine-full foo.c Resolved conflicted state of 'foo.c'
svn resolved — Deprecated. Remove „conflicted“ state on working copy files or directories.
This command has been deprecated in favor of
running svn resolve --accept working
.
See svn resolve in the preceding section for
details.PATH
Remove „conflicted“ state on working copy
files or directories. This routine does not semantically
resolve conflict markers; it merely removes
conflict-related artifact files and allows
PATH
to be committed again;
that is, it tells Subversion that the conflicts have been
„resolved.“ See „Konflikte auflösen (Änderungen anderer einarbeiten)“ for an in-depth look at
resolving conflicts.
If you get a conflict on an update, your working copy will sprout three new files:
$ svn update C foo.c Updated to revision 31. $ ls foo.c foo.c.mine foo.c.r30 foo.c.r31
Once you've resolved the conflict and
foo.c
is ready to be committed, run
svn resolved to let your working copy
know you've taken care of everything.
You can just remove the conflict files and commit, but svn resolved fixes up some bookkeeping data in the working copy administrative area in addition to removing the conflict files, so we recommend that you use this command.
svn revert — Undo all local edits.
Reverts any local changes to a file or directory and resolves any conflicted states. svn revert will revert not only the contents of an item in your working copy, but also any property changes. Finally, you can use it to undo any scheduling operations that you may have performed (e.g., files scheduled for addition or deletion can be „unscheduled“).
Discard changes to a file:
$ svn revert foo.c Reverted foo.c
If you want to revert a whole directory of files,
use the --depth=infinity
option:
$ svn revert --depth=infinity . Reverted newdir/afile Reverted foo.c Reverted bar.txt
Lastly, you can undo any scheduling operations:
$ svn add mistake.txt whoops A mistake.txt A whoops A whoops/oopsie.c $ svn revert mistake.txt whoops Reverted mistake.txt Reverted whoops $ svn status ? mistake.txt ? whoops
svn revert is inherently dangerous, since its entire purpose is to throw away data—namely, your uncommitted changes. Once you've reverted, Subversion provides no way to get back those uncommitted changes.
If you provide no targets to svn revert, it will do nothing—to protect you from accidentally losing changes in your working copy, svn revert requires you to provide at least one target.
svn status — Print the status of working copy files and directories.
Print the status of working copy files and
directories. With no arguments, it prints only locally
modified items (no repository access). With
--show-updates
, it adds working revision
and server out-of-date information. With
--verbose
, it prints full revision
information on every item. With --quiet
,
it prints only summary information about locally modified
items.
The first six columns in the output are each one character wide, and each column gives you information about different aspects of each working copy item.
The first column indicates that an item was added, deleted, or otherwise changed:
' '
No modifications.
'A'
Item is scheduled for addition.
'D'
Item is scheduled for deletion.
'M'
Item has been modified.
'R'
Item has been replaced in your working copy. This means the file was scheduled for deletion, and then a new file with the same name was scheduled for addition in its place.
'C'
The contents (as opposed to the properties) of the item conflict with updates received from the repository.
'X'
Item is present because of an externals definition.
'I'
Item is being ignored (e.g., with the
svn:ignore
property).
'?'
Item is not under version control.
'!'
Item is missing (e.g., you moved or deleted it without using svn). This also indicates that a directory is incomplete (a checkout or update was interrupted).
'~'
Item is versioned as one kind of object (file, directory, link), but has been replaced by a different kind of object.
The second column tells the status of a file's or directory's properties:
' '
No modifications.
'M'
Properties for this item have been modified.
'C'
Properties for this item are in conflict with property updates received from the repository.
The third column is populated only if the working copy directory is locked (see „Manchmal müssen Sie einfach nur aufräumen“):
' '
Item is not locked.
'L'
Item is locked.
The fourth column is populated only if the item is scheduled for addition-with-history:
' '
No history scheduled with commit.
'+'
History scheduled with commit.
The fifth column is populated only if the item is switched relative to its parent (see „Zweige durchlaufen“):
' '
Item is a child of its parent directory.
'S'
Item is switched.
The sixth column is populated with lock information:
' '
When --show-updates
is used,
the file is not locked. If
--show-updates
is
not used, this merely means that
the file is not locked in this working copy.
File is locked in this working copy.
File is locked either by another user or in
another working copy. This appears only when
--show-updates
is used.
File was locked in this working copy, but the
lock has been „stolen“ and is invalid.
The file is currently locked in the repository. This
appears only when --show-updates
is
used.
File was locked in this working copy, but the
lock has been „broken“ and is invalid.
The file is no longer locked. This appears only when
--show-updates
is used.
The out-of-date information appears in the seventh
column (only if you pass the
--show-updates
option):
' '
The item in your working copy is up to date.
'*'
A newer revision of the item exists on the server.
The remaining fields are variable width and
delimited by spaces. The working revision is the next
field if the --show-updates
or
--verbose
option is passed.
If the --verbose
option is passed,
the last committed revision and last committed author
are displayed next.
The working copy path is always the final field, so it can include spaces.
--changelist ARG --depth ARG --ignore-externals --incremental --no-ignore --quiet (-q) --show-updates (-u) --verbose (-v) --xml
This is the easiest way to find out what changes you have made to your working copy:
$ svn status wc M wc/bar.c A + wc/qax.c
If you want to find out what files in your working
copy are out of date, pass the
--show-updates
option (this will
not make any changes to your
working copy). Here you can see that
wc/foo.c
has changed in the
repository since we last updated our working
copy:
$ svn status --show-updates wc M 965 wc/bar.c * 965 wc/foo.c A + 965 wc/qax.c Status against revision: 981
--show-updates
only places an asterisk next to
items that are out of date (i.e., items that will be
updated from the repository if you later use svn
update). --show-updates
does
not cause the status listing to
reflect the repository's version of the item (although
you can see the revision number in the repository by
passing the --verbose
option).
The most information you can get out of the status subcommand is as follows:
$ svn status --show-updates --verbose wc M 965 938 sally wc/bar.c * 965 922 harry wc/foo.c A + 965 687 harry wc/qax.c 965 687 harry wc/zig.c Head revision: 981
Lastly, you can get svn status
output in XML format with the --xml
option:
$ svn status --xml wc <?xml version="1.0"?> <status> <target path="wc"> <entry path="qax.c"> <wc-status props="none" item="added" revision="0"> </wc-status> </entry> <entry path="bar.c"> <wc-status props="normal" item="modified" revision="965"> <commit revision="965"> <author>sally</author> <date>2008-05-28T06:35:53.048870Z</date> </commit> </wc-status> </entry> </target> </status>
For many more examples of svn status, see „Verschaffen Sie sich einen Überblick über Ihre Änderungen“.
svn switch — Update working copy to a different URL.
The first variant of this subcommand (without the
--relocate
option) updates your working
copy to point to a new URL—usually a URL that
shares a common ancestor with your working copy, although
not necessarily. This is the Subversion way to move a
working copy to a new branch. If specified,
PEGREV
determines in which
revision the target is first looked up. See „Zweige durchlaufen“ for an in-depth look
at switching.
If --force
is used, unversioned
obstructing paths in the working copy do not automatically
cause a failure if the switch attempts to add the same
path. If the obstructing path is the same type (file or
directory) as the corresponding path in the repository, it
becomes versioned but its contents are left untouched in
the working copy. This means that an obstructing
directory's unversioned children may also obstruct and
become versioned. For files, any content differences
between the obstruction and the repository are treated
like a local modification to the working copy. All
properties from the repository are applied to the
obstructing path.
As with most subcommands, you can limit the scope of
the switch operation to a particular tree depth using the
--depth
option. Alternatively, you can
use the --set-depth
option to set a new
„sticky“ working copy depth on the switch
target. Currently, the depth of a working copy directory
can only be increased (telescoped more deeply); you cannot
make a directory more shallow.
The --relocate
option causes
svn switch to do something different:
it updates your working copy to point to the
same repository directory, only at a different
URL (typically because an administrator has moved the
repository to another server, or to another URL on the
same server).
--accept ARG --depth ARG --diff3-cmd CMD --force --ignore-externals --quiet (-q) --relocate --revision (-r) REV --set-depth ARG
If you're currently inside the directory
vendors
, which was branched to
vendors-with-fix
, and you'd like to
switch your working copy to that branch:
$ svn switch http://svn.red-bean.com/repos/branches/vendors-with-fix . U myproj/foo.txt U myproj/bar.txt U myproj/baz.c U myproj/qux.c Updated to revision 31.
To switch back, just provide the URL to the location in the repository from which you originally checked out your working copy:
$ svn switch http://svn.red-bean.com/repos/trunk/vendors . U myproj/foo.txt U myproj/bar.txt U myproj/baz.c U myproj/qux.c Updated to revision 31.
You can switch just part of your working copy to a branch if you don't want to switch your entire working copy.
Sometimes an administrator might change the location
(or apparent location) of your repository—in other
words, the content of the repository doesn't change, but
the repository's root URL does. For example, the hostname
may change, the URL scheme may change, or any part of the
URL that leads to the repository itself may change.
Rather than check out a new working copy, you can have the
svn switch command
„rewrite“ your working copy's administrative
metadata to refer to the new repository location. If you
use the --relocate
option to svn
switch, Subversion will contact the repository
to validate the relocation request (looking for the
repository at the new URL, of course), and then do this
metadata rewriting. No file contents will be changed as
the result of this type of switch operation—this is
a metadata-only modification to the working copy.
$ svn checkout file:///var/svn/repos test A test/a A test/b … $ mv repos newlocation $ cd test/ $ svn update svn: Unable to open an ra_local session to URL svn: Unable to open repository 'file:///var/svn/repos' $ svn switch --relocate file:///var/svn/repos file:///tmp/newlocation . $ svn update At revision 3.
Be careful when using the
--relocate
option. If you mistype the
argument, you might end up creating nonsensical URLs
within your working copy that render the whole workspace
unusable and tricky to fix. It's also important to
understand exactly when one should or shouldn't use
--relocate
. Here's the rule of
thumb:
If the working copy needs to reflect a new directory within the repository, use just svn switch.
If the working copy still reflects the
same repository directory, but the location of the
repository itself has changed, use svn
switch with the --relocate
option.
svn unlock — Unlock working copy paths or URLs.
Unlock each TARGET
. If any
TARGET
is locked by
another user or no valid lock token exists in the working
copy, print a warning and continue unlocking the rest of
the TARGET
s. Use
--force
to break a lock belonging to
another user or working copy.
Unlock two files in your working copy:
$ svn unlock tree.jpg house.jpg 'tree.jpg' unlocked. 'house.jpg' unlocked.
Unlock a file in your working copy that is currently locked by another user:
$ svn unlock tree.jpg svn: 'tree.jpg' is not locked in this working copy $ svn unlock --force tree.jpg 'tree.jpg' unlocked.
Unlock a file without a working copy:
$ svn unlock http://svn.red-bean.com/repos/test/tree.jpg 'tree.jpg unlocked.
For further details, see „Locking“.
svn update — Update your working copy.
svn update brings changes from the
repository into your working copy. If no revision is given,
it brings your working copy up to date with the
HEAD
revision. Otherwise, it
synchronizes the working copy to the revision given by the
--revision
option. As part of the
synchronization, svn update also
removes any stale locks (see „Manchmal müssen Sie einfach nur aufräumen“) found in the
working copy.
For each updated item, it prints a line that starts with a character reporting the action taken. These characters have the following meaning:
A
Added
B
Broken lock (third column only)
D
Deleted
U
Updated
C
Conflicted
G
Merged
E
Existed
A character in the first column signifies an update to the actual file, whereas updates to the file's properties are shown in the second column. Lock information is printed in the third column.
As with most subcommands, you can limit the scope of
the update operation to a particular tree depth using the
--depth
option. Alternatively, you can
use the --set-depth
option to set a new
„sticky“ working copy depth on the update
target. Currently, the depth of a working copy directory
can only be increased (telescoped more deeply); you cannot
make a directory more shallow.
--accept ARG --changelist --depth ARG --diff3-cmd CMD --editor-cmd ARG --force --ignore-externals --quiet (-q) --revision (-r) REV --set-depth ARG
Pick up repository changes that have happened since your last update:
$ svn update A newdir/toggle.c A newdir/disclose.c A newdir/launch.c D newdir/README Updated to revision 32.
You can also „update“ your working copy to an older revision (Subversion doesn't have the concept of „sticky“ files like CVS does; see Anhang B, Subversion for CVS Users):
$ svn update -r30 A newdir/README D newdir/toggle.c D newdir/disclose.c D newdir/launch.c U foo.c Updated to revision 30.
If you want to examine an older revision of a single file, you may want to use svn cat instead—it won't change your working copy.
svnadmin is the administrative tool for monitoring and repairing your Subversion repository. For detailed information on repository administration, see the maintenance section for „svnadmin“.
Since svnadmin works via direct repository access (and thus can only be used on the machine that holds the repository), it refers to the repository with a path, not a URL.
Options in svmadin are global, just as they are in svn:
--bdb-log-keep
(Berkeley DB-specific.) Disable automatic log removal of database logfiles. Having these logfiles around can be convenient if you need to restore from a catastrophic repository failure.
--bdb-txn-nosync
(Berkeley DB-specific.) Disables fsync when
committing database transactions. Used with the
svnadmin create command to create a
Berkeley DB-backed repository with
DB_TXN_NOSYNC
enabled (which improves
speed but has some risks associated with it).
--bypass-hooks
Bypass the repository hook system.
--clean-logs
Remove unused Berkeley DB logs.
--force-uuid
By default, when loading data into repository that
already contains revisions, svnadmin
will ignore the UUID
from the dump
stream. This option will cause the repository's
UUID
to be set to the
UUID
from the stream.
--ignore-uuid
By default, when loading an empty repository,
svnadmin will ignore the
UUID
from the dump stream. This
option will force that UUID to be ignored (useful for
overriding your configuration file if it has
--force-uuid
set).
--incremental
Dump a revision only as a diff against the previous revision, instead of the usual fulltext.
--parent-dir
DIR
When loading a dump file, root paths at
DIR
instead of
/
.
--pre-1.4-compatible
When creating a new repository, use a format that is compatible with versions of Subversion earlier than Subversion 1.4.
--pre-1.5-compatible
When creating a new repository, use a format that is compatible with versions of Subversion earlier than Subversion 1.5.
--revision
(-r
)
ARG
Specify a particular revision to operate on.
--quiet
Do not show normal progress—show only errors.
--use-post-commit-hook
When loading a dump file, runs the repository's
post-commit
hook after finalizing each newly loaded
revision.
--use-post-revprop-change-hook
When changing a revision property, runs the
repository's post-revprop-change
hook after changing the
revision property.
--use-pre-commit-hook
When loading a dump file, runs the repository's
pre-commit
hook before finalizing each newly loaded
revision. If the hook fails, aborts the commit and
terminates the load process.
--use-pre-revprop-change-hook
When changing a revision property, runs the
repository's pre-revprop-change
hook before changing the
revision property. If the hook fails, aborts the
modification and terminates.
Here are the various subcommands for the svnadmin program.
svnadmin crashtest — Simulate a process that crashes.
svnadmin create — Create a new, empty repository.
Create a new, empty repository at the path provided.
If the provided directory does not exist, it will be
created for you.
[56]
As of Subversion 1.2, svnadmin
creates new repositories with the
FSFS
filesystem backend by
default.
While svnadmin create will create
the base directory for a new repository, it will not
create intermediate directories. For example, if you
have an empty directory named
/var/svn
, creating
/var/svn/repos
will work, while
attempting to create
/var/svn/subdirectory/repos
will
fail with an error.
--bdb-log-keep --bdb-txn-nosync --config-dir DIR --fs-type TYPE --pre-1.4-compatible --pre-1.5-compatible
Creating a new repository is this easy:
$ svnadmin create /var/svn/repos
In Subversion 1.0, a Berkeley DB repository is always
created. In Subversion 1.1, a Berkeley DB repository is
the default repository type, but an FSFS repository can be
created using the --fs-type
option:
$ svnadmin create /var/svn/repos --fs-type fsfs
svnadmin deltify — Deltify changed paths in a revision range.
svnadmin deltify exists in current versions of Subversion only for historical reasons. This command is deprecated and no longer needed.
It dates from a time when Subversion offered administrators greater control over compression strategies in the repository. This turned out to be a lot of complexity for very little gain, and this „feature“ was deprecated.
svnadmin dump — Dump the contents of the filesystem to stdout
.
Dump the contents of the filesystem to stdout
in a
„dump file“ portable format, sending feedback
to stderr
. Dump revisions
LOWER
rev through
UPPER
rev. If no revisions are
given, dump all revision trees. If only
LOWER
is given, dump that one
revision tree. See „Repository-Daten woandershin verschieben“
for a practical use.
By default, the Subversion dump stream contains a single revision (the first revision in the requested revision range) in which every file and directory in the repository in that revision is presented as though that whole tree was added at once, followed by other revisions (the remainder of the revisions in the requested range), which contain only the files and directories that were modified in those revisions. For a modified file, the complete full-text representation of its contents, as well as all of its properties, are presented in the dump file; for a directory, all of its properties are presented.
Two useful options modify the dump file
generator's behavior. The first is the
--incremental
option, which simply causes
that first revision in the dump stream to contain only
the files and directories modified in that revision,
instead of being presented as the addition of a new tree,
and in exactly the same way that every other revision in
the dump file is presented. This is useful for generating
a relatively small dump file to be loaded into another
repository that already has the files and directories
that exist in the original repository.
The second useful option is --deltas
.
This option causes svnadmin dump to,
instead of emitting full-text representations of file
contents and property lists, emit only deltas of those
items against their previous versions. This reduces (in
some cases, drastically) the size of the dump file that
svnadmin dump creates. There are, however,
disadvantages to using this option—deltified
dump files are more CPU-intensive to create, cannot be
operated on by svndumpfilter, and tend
not to compress as well as their nondeltified counterparts
when using third-party tools such as gzip
and bzip2.
svnadmin help — Help!
svnadmin hotcopy — Make a hot copy of a repository.
This subcommand makes a full „hot“ backup
of your repository, including all hooks, configuration
files, and, of course, database files. If you pass the
--clean-logs
option,
svnadmin will perform a hot copy of your
repository, and then remove unused Berkeley DB logs from
the original repository. You can run this command at any
time and make a safe copy of the repository, regardless of
whether other processes are using the repository.
--clean-logs
As described in „Berkeley DB“, hot-copied Berkeley DB repositories are not portable across operating systems, nor will they work on machines with a different „endianness“ than the machine where they were created.
svnadmin list-dblogs — Ask Berkeley DB which logfiles exist for a
given Subversion repository (applies only to repositories
using the bdb
backend).
Berkeley DB creates logs of all changes to the
repository, which allow it to recover in the face of
catastrophe. Unless you enable
DB_LOG_AUTOREMOVE
, the logfiles
accumulate, although most are no longer used and can be
deleted to reclaim disk space. See „Plattenplatzverwaltung“ for more
information.
svnadmin list-unused-dblogs — Ask Berkeley DB which logfiles can be safely
deleted (applies only to repositories using the
bdb
backend).
Berkeley DB creates logs of all changes to the
repository, which allow it to recover in the face of
catastrophe. Unless you enable
DB_LOG_AUTOREMOVE
, the logfiles
accumulate, although most are no longer used and can be
deleted to reclaim disk space. See „Plattenplatzverwaltung“ for more
information.
svnadmin load — Read a
repository dump stream from
stdin
.
Read a repository dump stream from
stdin
, committing new revisions into the repository's
filesystem. Send progress feedback to stdout
.
--force-uuid --ignore-uuid --parent-dir --quiet (-q) --use-post-commit-hook --use-pre-commit-hook
This shows the beginning of loading a repository from a backup file (made, of course, with svnadmin dump):
$ svnadmin load /var/svn/restored < repos-backup <<< Started new txn, based on original revision 1 * adding path : test ... done. * adding path : test/a ... done. …
Or if you want to load into a subdirectory:
$ svnadmin load --parent-dir new/subdir/for/project \ /var/svn/restored < repos-backup <<< Started new txn, based on original revision 1 * adding path : test ... done. * adding path : test/a ... done. …
svnadmin lslocks — Print descriptions of all locks.
Print descriptions of all locks in
repository REPOS_PATH
underneath the
path PATH-IN-REPOS
.
If PATH-IN-REPOS
is not
provided, it defaults to the root directory of the
repository.
This lists the one locked file in the repository at
/var/svn/repos
:
$ svnadmin lslocks /var/svn/repos Path: /tree.jpg UUID Token: opaquelocktoken:ab00ddf0-6afb-0310-9cd0-dda813329753 Owner: harry Created: 2005-07-08 17:27:36 -0500 (Fri, 08 Jul 2005) Expires: Comment (1 line): Rework the uppermost branches on the bald cypress in the foreground.
svnadmin lstxns — Print the names of all uncommitted transactions.
Print the names of all uncommitted transactions. See „Entfernen unvollendeter Transaktionen“ for information on how uncommitted transactions are created and what you should do with them.
svnadmin recover — Bring a repository database back into a
consistent state (applies only to repositories using the
bdb
backend). In addition, if
repos/conf/passwd
does not exist, it
will create a default passwordfile .
Run this command if you get an error indicating that your repository needs to be recovered.
Recover a hung repository:
$ svnadmin recover /var/svn/repos/ Repository lock acquired. Please wait; recovering the repository may take some time... Recovery completed. The latest repos revision is 34.
Recovering the database requires an exclusive lock on the repository. (This is a „database lock“; see the sidebar The Three Meanings of „Lock“.) If another process is accessing the repository, then svnadmin recover will error:
$ svnadmin recover /var/svn/repos svn: Failed to get exclusive repository access; perhaps another process such as httpd, svnserve or svn has it open? $
The --wait
option, however, will
cause svnadmin recover to wait
indefinitely for other processes to disconnect:
$ svnadmin recover /var/svn/repos --wait Waiting on repository lock; perhaps another process has it open? ### time goes by… Repository lock acquired. Please wait; recovering the repository may take some time... Recovery completed. The latest repos revision is 34.
svnadmin rmtxns — Delete transactions from a repository.
Delete outstanding transactions from a repository. This is covered in detail in „Entfernen unvollendeter Transaktionen“.
svnadmin setlog — Set the log message on a revision.
Set the log message on
revision REVISION
to the
contents of FILE
.
This is similar to using svn propset
with the --revprop
option to set the svn:log
property
on a revision, except that you can also use the option
--bypass-hooks
to avoid running any pre-
or post-commit hooks, which is useful if the modification
of revision properties has not been enabled in
the pre-revprop-change
hook.
Revision properties are not under version control, so this command will permanently overwrite the previous log message.
svnadmin setrevprop — Set a property on a revision.
svnadmin setuuid — Reset the repository UUID.
Reset the repository UUID for the repository located
at REPOS_PATH
.
If NEW_UUID
is provided, use
that as the new repository UUID; otherwise, generate a
brand-new UUID for the repository.
If you've svnsynced /var/svn/repos
to /var/svn/repos-new
and intend to use repos-new
as your
canonical repository, you may want to change the UUID for
repos-new
to the UUID of repos
so that your users don't
have to check out a new working copy to accommodate the
change:
$ svnadmin setuuid /var/svn/repos-new 2109a8dd-854f-0410-ad31-d604008985ab
As you can see, svnadmin setuuid has no output upon success.
svnadmin upgrade — Upgrade a repository to the latest supported schema version.
Upgrade the repository located
at REPOS_PATH
to the latest
supported schema version.
This functionality is provided as a convenience for repository administrators who wish to make use of new Subversion functionality without having to undertake a potentially costly full repository dump and load operation. As such, the upgrade performs only the minimum amount of work needed to accomplish this while still maintaining the integrity of the repository. While a dump and subsequent load guarantee the most optimized repository state, svnadmin upgrade does not.
You should always back up your repository before upgrading.
svnadmin verify — Verify the data stored in the repository.
Run this command if you wish to verify the integrity of your repository. This basically iterates through all revisions in the repository by internally dumping all revisions and discarding the output—it's a good idea to run this on a regular basis to guard against latent hard disk failures and „bitrot.“ If this command fails—which it will do at the first sign of a problem—that means your repository has at least one corrupted revision, and you should restore the corrupted revision from a backup (you did make a backup, didn't you?).
svnlook is a command-line utility for examining different aspects of a Subversion repository. It does not make any changes to the repository—it's just used for „peeking.“ svnlook is typically used by the repository hooks, but a repository administrator might find it useful for diagnostic purposes.
Since svnlook works via direct repository access (and thus can be used only on the machine that holds the repository), it refers to the repository with a path, not a URL.
If no revision or transaction is specified, svnlook defaults to the youngest (most recent) revision of the repository.
Options in svnlook are global, just as they are in svn and svnadmin; however, most options apply to only one subcommand since the functionality of svnlook is (intentionally) limited in scope:
--copy-info
Causes svnlook changed to show detailed copy source information.
--no-diff-deleted
Prevents svnlook diff from printing differences for deleted files. The default behavior when a file is deleted in a transaction/revision is to print the same differences that you would see if you had left the file but removed all the content.
--no-diff-added
Prevents svnlook diff from printing differences for added files. The default behavior when you add a file is to print the same differences that you would see if you had added the entire contents of an existing (empty) file.
--revision
(-r
)Specifies a particular revision number that you wish to examine.
--revprop
Operates on a revision property instead of a
property specific to a file or directory. This option
requires that you also pass a revision with the
--revision
(-r
)
option.
--transaction
(-t
)Specifies a particular transaction ID that you wish to examine.
--show-ids
Shows the filesystem node revision IDs for each path in the filesystem tree.
Here are the various subcommands for the svnlook program.
svnlook cat — Print the contents of a file.
This shows the contents of a file in transaction
ax8
, located at
/trunk/README
:
$ svnlook cat -t ax8 /var/svn/repos /trunk/README Subversion, a version control system. ===================================== $LastChangedDate: 2003-07-17 10:45:25 -0500 (Thu, 17 Jul 2003) $ Contents: I. A FEW POINTERS II. DOCUMENTATION III. PARTICIPATING IN THE SUBVERSION COMMUNITY …
svnlook changed — Print the paths that were changed.
Print the paths that were changed in a particular revision or transaction, as well as „svn update-style“ status letters in the first two columns:
'A '
Item added to repository
'D '
Item deleted from repository
'U '
File contents changed
'_U'
Properties of item changed; note the leading underscore
'UU'
File contents and properties changed
Files and directories can be distinguished, as
directory paths are displayed with a
trailing „/
“
character.
This shows a list of all the changed files and
directories in revision 39 of a test repository. Note
that the first changed item is a directory, as evidenced
by the trailing /
:
$ svnlook changed -r 39 /var/svn/repos A trunk/vendors/deli/ A trunk/vendors/deli/chips.txt A trunk/vendors/deli/sandwich.txt A trunk/vendors/deli/pickle.txt U trunk/vendors/baker/bagel.txt _U trunk/vendors/baker/croissant.txt UU trunk/vendors/baker/pretzel.txt D trunk/vendors/baker/baguette.txt
Here's an example that shows a revision in which a file was renamed:
$ svnlook changed -r 64 /var/svn/repos A trunk/vendors/baker/toast.txt D trunk/vendors/baker/bread.txt
Unfortunately, nothing in the preceding output reveals
the connection between the deleted and added files. Use
the --copy-info
option to make this
relationship more apparent:
$ svnlook changed -r 64 --copy-info /var/svn/repos A + trunk/vendors/baker/toast.txt (from trunk/vendors/baker/bread.txt:r63) D trunk/vendors/baker/bread.txt
svnlook diff — Print differences of changed files and properties.
--diff-copy-from --no-diff-added --no-diff-deleted --revision (-r) REV --transaction (-t) TXN
This shows a newly added (empty) file, a deleted file, and a copied file:
$ svnlook diff -r 40 /var/svn/repos/ Copied: egg.txt (from rev 39, trunk/vendors/deli/pickle.txt) Added: trunk/vendors/deli/soda.txt ============================================================================== Modified: trunk/vendors/deli/sandwich.txt ============================================================================== --- trunk/vendors/deli/sandwich.txt (original) +++ trunk/vendors/deli/sandwich.txt 2003-02-22 17:45:04.000000000 -0600 @@ -0,0 +1 @@ +Don't forget the mayo! Modified: trunk/vendors/deli/logo.jpg ============================================================================== (Binary files differ) Deleted: trunk/vendors/deli/chips.txt ============================================================================== Deleted: trunk/vendors/deli/pickle.txt ==============================================================================
If a file has a nontextual
svn:mime-type
property, the
differences are not explicitly shown.
svnlook dirs-changed — Print the directories that were themselves changed.
svnlook help — Help!
svnlook history — Print information about the history of a path in the repository (or the root directory if no path is supplied).
Print information about the history of a path in the repository (or the root directory if no path is supplied).
This shows the history output for the path
/branches/bookstore
as of revision 13 in our
sample repository:
$ svnlook history -r 13 /var/svn/repos /branches/bookstore --show-ids REVISION PATH <ID> -------- --------- 13 /branches/bookstore <1.1.r13/390> 12 /branches/bookstore <1.1.r12/413> 11 /branches/bookstore <1.1.r11/0> 9 /trunk <1.0.r9/551> 8 /trunk <1.0.r8/131357096> 7 /trunk <1.0.r7/294> 6 /trunk <1.0.r6/353> 5 /trunk <1.0.r5/349> 4 /trunk <1.0.r4/332> 3 /trunk <1.0.r3/335> 2 /trunk <1.0.r2/295> 1 /trunk <1.0.r1/532>
svnlook info — Print the author, datestamp, log message size, and log message.
svnlook lock — If a lock exists on a path in the repository, describe it.
Print all information available for the lock at
PATH_IN_REPOS
. If
PATH_IN_REPOS
is not locked,
print nothing.
This describes the lock on the file
tree.jpg
:
$ svnlook lock /var/svn/repos tree.jpg UUID Token: opaquelocktoken:ab00ddf0-6afb-0310-9cd0-dda813329753 Owner: harry Created: 2005-07-08 17:27:36 -0500 (Fri, 08 Jul 2005) Expires: Comment (1 line): Rework the uppermost branches on the bald cypress in the foreground.
svnlook proplist — Print the names and values of versioned file and directory properties.
List the properties of a path in the repository. With
--verbose
, show the property values too.
This shows the names of properties set on the file
/trunk/README
in the
HEAD
revision:
$ svnlook proplist /var/svn/repos /trunk/README original-author svn:mime-type
This is the same command as in the preceding example, but this time showing the property values as well:
$ svnlook --verbose proplist /var/svn/repos /trunk/README original-author : harry svn:mime-type : text/plain
svnlook tree — Print the tree.
Print the tree, starting at
PATH_IN_REPOS
(if supplied; at
the root of the tree otherwise), optionally showing node
revision IDs.
This shows the tree output (with nodeIDs) for revision 13 in our sample repository:
$ svnlook tree -r 13 /var/svn/repos --show-ids / <0.0.r13/811> trunk/ <1.0.r9/551> button.c <2.0.r9/238> Makefile <3.0.r7/41> integer.c <4.0.r6/98> branches/ <5.0.r13/593> bookstore/ <1.1.r13/390> button.c <2.1.r12/85> Makefile <3.0.r7/41> integer.c <4.1.r13/109>
svnsync is the Subversion remote repository mirroring tool. Put simply, it allows you to replay the revisions of one repository into another one.
In any mirroring scenario, there are two repositories: the source repository, and the mirror (or „sink“) repository. The source repository is the repository from which svnsync pulls revisions. The mirror repository is the destination for the revisions pulled from the source repository. Each of the repositories may be local or remote—they are only ever addressed by their URLs.
The svnsync process requires only read access to the source repository; it never attempts to modify it. But obviously, svnsync requires both read and write access to the mirror repository.
svnsync is very sensitive to changes made in the mirror repository that weren't made as part of a mirroring operation. To prevent this from happening, it's best if the svnsync process is the only process permitted to modify the mirror repository.
Options in svnsync are global, just as they are in svn and svnadmin:
--config-dir
DIR
Instructs Subversion to read configuration
information from the specified directory instead of the
default location (.subversion
in
the user's home directory).
--no-auth-cache
Prevents caching of authentication information (e.g., username and password) in the Subversion runtime configuration directories.
--non-interactive
In the case of an authentication failure or insufficient credentials, prevents prompting for credentials (e.g., username or password). This is useful if you're running Subversion inside an automated script and it's more appropriate to have Subversion fail than to prompt for more information.
--quiet
(-q
)Requests that the client print only essential information while performing an operation.
--source-password
PASSWD
Specifies the password for the Subversion server from which you are syncing. If not provided, or if incorrect, Subversion will prompt you for this information as needed.
--source-username
NAME
Specifies the username for the Subversion server from which you are syncing. If not provided, or if incorrect, Subversion will prompt you for this information as needed.
--sync-password
PASSWD
Specifies the password for the Subversion server to which you are syncing. If not provided, or if incorrect, Subversion will prompt you for this information as needed.
--sync-username
NAME
Specifies the username for the Subversion server to which you are syncing. If not provided, or if incorrect, Subversion will prompt you for this information as needed.
Here are the various subcommands for the svnsync program.
svnsync copy-revprops — Copy all revision properties for a particular revision (or range of revisions) from the source repository to the mirror repository.
Because Subversion revision properties can be changed at any time, it's possible that the properties for some revision might be changed after that revision has already been synchronized to another repository. Because the svnsync synchronize command operates only on the range of revisions that have not yet been synchronized, it won't notice a revision property change outside that range. Left as is, this causes a deviation in the values of that revision's properties between the source and mirror repositories. svnsync copy-revprops is the answer to this problem. Use it to resynchronize the revision properties for a particular revision or range of revisions.
svnsync help — Help!
This subcommand is useful when you're trapped in a foreign prison with neither a Net connection nor a copy of this book, but you do have a local Wi-Fi network running and you'd like to sync a copy of your repository over to the backup server that Ira The Knife is running over in cell block D.
svnsync initialize — Initialize a mirror repository for synchronization from the source repository.
svnsync initialize verifies that a repository meets the requirements of a new mirror repository—that it has no previous existing version history and that it allows revision property modifications—and records the initial administrative information that associates the mirror repository with the source repository. This is the first svnsync operation you run on a would-be mirror repository.
--config-dir DIR --no-auth-cache --non-interactive --quiet (-q) --source-password ARG --source-username ARG --sync-password ARG --sync-username ARG
Fail to initialize a mirror repository due to inability to modify revision properties:
$ svnsync initialize file:///var/svn/repos-mirror http://svn.example.com/repos svnsync: Repository has not been enabled to accept revision propchanges; ask the administrator to create a pre-revprop-change hook $
Initialize a repository as a mirror, having already
created a pre-revprop-change
hook that
permits all revision property changes:
$ svnsync initialize file:///var/svn/repos-mirror http://svn.example.com/repos Copied properties for revision 0. $
svnsync synchronize — Transfer all pending revisions from the source repository to the mirror repository.
The svnsync synchronize command does all the heavy lifting of a repository mirroring operation. After consulting with the mirror repository to see which revisions have already been copied into it, it then begins to copy any not-yet-mirrored revisions from the source repository.
svnsync synchronize can be gracefully canceled and restarted.
As of Subversion 1.5, you can limit svnsync to a
subdirectory of the source repository by specifying the
subdirectory as part of
the SOURCE_URL
.
--config-dir DIR --no-auth-cache --non-interactive --quiet (-q) --source-password ARG --source-username ARG --sync-password ARG --sync-username ARG
Copy unsynchronized revisions from the source repository to the mirror repository:
$ svnsync synchronize file:///var/svn/repos-mirror Committed revision 1. Copied properties for revision 1. Committed revision 2. Copied properties for revision 2. Committed revision 3. Copied properties for revision 3. … Committed revision 45. Copied properties for revision 45. Committed revision 46. Copied properties for revision 46. Committed revision 47. Copied properties for revision 47. $
svnserve allows access to Subversion repositories using Subversion's custom network protocol.
You can run svnserve as a standalone
server process (for clients that are using the
svn://
access method); you can have a daemon
such as inetd or xinetd
launch it for you on demand (also for
svn://
), or you can have
sshd launch it on demand for the
svn+ssh://
access method.
Regardless of the access method, once the client has
selected a repository by transmitting its URL,
svnserve reads a file named
conf/svnserve.conf
in the repository
directory to determine repository-specific settings such as
what authentication database to use and what authorization
policies to apply. See „svnserve, ein maßgefertigter Server“ for details of the
svnserve.conf
file.
Unlike the previous commands we've described, svnserve has no subcommands—it is controlled exclusively by options.
--daemon
(-d
)Causes svnserve to run in daemon
mode. svnserve backgrounds itself
and accepts and serves TCP/IP connections on
the svn
port (3690, by
default).
--foreground
When used together with -d
,
causes svnserve to stay in the
foreground. This is mainly useful for debugging.
--inetd
(-i
)Causes svnserve to use the
stdin
and stdout
file descriptors, as is appropriate for a
daemon running out of inetd.
--help
(-h
)Displays a usage summary and exits.
--listen-host
=HOST
Causes svnserve to listen on the
interface specified by HOST
,
which may be either a hostname or an IP address.
--listen-once
(-X
)Causes svnserve to accept one
connection on the svn
port, serve it,
and exit. This option is mainly useful for
debugging.
--listen-port
=PORT
Causes svnserve to listen on
PORT
when run in daemon mode.
(FreeBSD daemons listen only on tcp6 by default—this
option tells them to also listen on tcp4.)
--pid-file FILENAME
Causes svnserve to write its
process ID to FILENAME
, which
must be writable by the user under
which svnserve is running.
--root
=ROOT
(-r
=ROOT
)Sets the virtual root for repositories served by svnserve. The pathname in URLs provided by the client will be interpreted relative to this root and will not be allowed to escape this root.
--threads
(-T
)When running in daemon mode, causes svnserve to spawn a thread instead of a process for each connection (e.g., for when running on Windows). The svnserve process still backgrounds itself at startup time.
--tunnel
(-t
)Causes svnserve to run in tunnel
mode, which is just like the inetd
mode of operation (both modes serve one connection over
stdin
/stdout
, and then exit), except that the connection
is considered to be preauthenticated with the username
of the current UID. This flag is automatically passed
for you by the client when running over a tunnel agent
such as ssh. That means there's
rarely any need for you to pass
this option to svnserve. So, if you
find yourself
typing svnserve --tunnel
on the
command line and wondering what to do next, see
„Tunneling over SSH“.
--tunnel-user NAME
Used in conjunction with the --tunnel
option, tells svnserve to assume that
NAME
is the authenticated
user, rather than the UID of the svnserve
process. This is useful for users wishing to share a single
system account over SSH, but to maintain separate commit
identities.
--version
Displays version information and a list of repository backend modules available, and then exits.
svndumpfilter is a command-line utility for removing history from a Subversion dump file by either excluding or including paths beginning with one or more named prefixes. For details, see „svndumpfilter“.
Options in svndumpfilter are global, just as they are in svn and svnadmin:
--drop-empty-revs
If filtering causes any revision to be empty (i.e., causes no change to the repository), removes these revisions from the final dump file.
--renumber-revs
Renumbers revisions that remain after filtering.
--skip-missing-merge-sources
Skips merge sources that have been removed as part of the filtering. Without this option, svndumpfilter will exit with an error if the merge source for a retained path is removed by filtering.
--preserve-revprops
If all nodes in a revision are removed by filtering
and --drop-empty-revs
is not passed,
the default behavior of svndumpfilter
is to remove all revision properties except for the date
and the log message (which will merely indicate that the
revision is empty). Passing this option will preserve
existing revision properties (which may or may not make
sense since the related content is no longer present in
the dump file).
--quiet
Does not display filtering statistics.
Here are the various subcommands for the svndumpfilter program.
svndumpfilter exclude — Filter out nodes with given prefixes from the dump stream.
This can be used to exclude nodes that begin with one or
more PATH_PREFIX
es from a
filtered dump file.
If we have a dump file from a repository with a number of
different picnic-related directories in it, but we want to keep
everything except
the sandwiches
part of the repository,
we'll exclude only that path:
$ svndumpfilter exclude sandwiches < dumpfile > filtered-dumpfile Excluding prefixes: '/sandwiches' Revision 0 committed as 0. Revision 1 committed as 1. Revision 2 committed as 2. Revision 3 committed as 3. Revision 4 committed as 4. Dropped 1 node(s): '/sandwiches'
svndumpfilter include — Filter out nodes without given prefixes from dump stream.
Can be used to include nodes that begin with one or
more PATH_PREFIX
es in a
filtered dump file (thus excluding all other paths).
If we have a dump file from a repository with a number of
different picnic-related directories in it, but want to
keep only the sandwiches
part of the
repository, we'll include only that path:
$ svndumpfilter include sandwiches < dumpfile > filtered-dumpfile Including prefixes: '/sandwiches' Revision 0 committed as 0. Revision 1 committed as 1. Revision 2 committed as 2. Revision 3 committed as 3. Revision 4 committed as 4. Dropped 3 node(s): '/drinks' '/snacks' '/supplies'
svnversion — Summarize the local revision(s) of a working copy.
svnversion is a program for summarizing the revision mixture of a working copy. The resultant revision number, or revision range, is written to standard output.
It's common to use this output in your build process when defining the version number of your program.
TRAIL_URL
, if present, is the
trailing portion of the URL used to determine whether
WC_PATH
itself is switched
(detection of switches within
WC_PATH
does not rely on
TRAIL_URL
).
When WC_PATH
is not defined,
the current directory will be used as the working copy path.
TRAIL_URL
cannot be defined if
WC_PATH
is not explicitly
given.
Like svnserve, svnversion has no subcommands—only options:
--no-newline
(-n
)Omits the usual trailing newline from the output.
--committed
(-c
)Uses the last-changed revisions rather than the current (i.e., highest locally available) revisions.
--help
(-h
)Prints a help summary.
--version
Prints the version of svnversion and exit with no error.
If the working copy is all at the same revision (e.g., immediately after an update), then that revision is printed out:
$ svnversion 4168
You can add TRAIL_URL
to make
sure the working copy is not switched from what you
expect. Note that the WC_PATH
is required in this command:
$ svnversion . /var/svn/trunk 4168
For a mixed-revision working copy, the range of revisions present is printed:
$ svnversion 4123:4168
If the working copy contains modifications, a trailing "M" is added:
$ svnversion 4168M
If the working copy is switched, a trailing "S" is added:
$ svnversion 4168S
Thus, here is a mixed-revision, switched working copy containing some local modifications:
$ svnversion 4212:4168MS
If invoked on a directory that is not a working copy, svnversion assumes it is an exported working copy and prints "exported":
$ svnversion exported
mod_dav_svn Configuration Directives — Apache configuration directives for serving Subversion repositories through the Apache HTTP Server.
This section briefly describes each Subversion Apache configuration directive. For an in-depth description of configuring Apache with Subversion, see „httpd, the Apache HTTP Server“.)
These are the httpd.conf
directives
that apply to mod_dav_svn:
DAV svn
Must be included in any
Directory
or
Location
block for a Subversion
repository. It tells httpd to use the Subversion
backend for mod_dav
to handle all
requests.
SVNAllowBulkUpdates On|Off
Toggles support for all-inclusive
responses to update-style REPORT
requests. Subversion clients use
REPORT
requests to get information
about directory tree checkouts and updates from
mod_dav_svn. They can ask the
server to send that information in one of two ways:
with the entirety of the tree's information in one
massive response, or with a
skelta (a skeletal
representation of a tree delta) which contains just
enough information for the client to know what
additional data to request from
the server. When this directive is included with a
value of Off
,
mod_dav_svn will only ever respond
to these REPORT
requests with
skelta responses, regardless of the type of responses
requested by the client.
Most folks won't need to use this directive at
all. It primarily exists for administrators who
wish—for security or auditing reasons—to
force Subversion clients to fetch individually all the
files and directories needed for updates and
checkouts, thus leaving an audit trail of
GET
and PROPFIND
requests in Apache's logs. The default value of this
directive is On
.
SVNAutoversioning On|Off
When its value is
On
, allows write requests from
WebDAV clients to result in automatic commits. A
generic log message is auto-generated and attached to
each revision. If you enable autoversioning, you'll
likely want to set ModMimeUsePathInfo
On
so that mod_mime
can
set svn:mime-type
to the correct
MIME type automatically (as best as
mod_mime
is able to, of course).
For more information, see Anhang C, WebDAV and Autoversioning. The default value of this
directive is Off
.
SVNPath
directory-path
Specifies the location in the
filesystem for a Subversion repository's files. In a
configuration block for a Subversion repository,
either this directive or
SVNParentPath
must be present, but
not both.
SVNSpecialURI
component
Specifies the URI component (namespace) for
special Subversion resources. The default is
!svn
, and most
administrators will never use this directive. Set
this only if there is a pressing need to have a file
named !svn
in your repository.
If you change this on a server already in use, it will
break all of the outstanding working copies, and your
users will hunt you down with pitchforks and flaming
torches.
SVNReposName
name
Specifies the name of a Subversion repository for
use in HTTP GET
responses. This
value will be prepended to the title of all directory
listings (which are served when you navigate to a
Subversion repository with a web browser). This
directive is optional.
SVNIndexXSLT
directory-path
Specifies the URI of an XSL transformation for directory indexes. This directive is optional.
SVNParentPath
directory-path
Specifies the location in the filesystem of a
parent directory whose child directories are
Subversion repositories. In a configuration block for
a Subversion repository, either this directive or
SVNPath
must be present, but not
both.
SVNPathAuthz On|Off|short_circuit
Controls path-based authorization by enabling
subrequests (On
), disabling
subrequests (Off
; see „Disabling path-based checks“),
or querying mod_authz_svn directly
(short_circuit
). The default
value of this directive is On
.
SVNListParentPath On|Off
When set to On
, allows
a GET
of SVNParentPath
, which results in
a listing of all repositories under that path. The
default setting is
Off
.
SVNMasterURI
url
Specifies a URI to the master Subversion repository (used for a write-through proxy).
SVNActivitiesDB
directory-path
Specifies the location in the filesystem where the
activities database should be stored. By default,
mod_dav_svn creates and uses a directory in the
repository
called dav/activities.d
. The
path specified with this option must be an absolute
path.
If specified for
an SVNParentPath
area, mod_dav_svn
appends the basename of the repository to the path
specified here. For example:
<Location /svn> DAV svn # any "/svn/foo" URL will map to a repository in # /net/svn.nfs/repositories/foo SVNParentPath "/net/svn.nfs/repositories" # any "/svn/foo" URL will map to an activities db in # /var/db/svn/activities/foo SVNActivitiesDB "/var/db/svn/activities" </Location>
This is a list of Subversion action log messages produced by Apache's high-level logging mechanism, followed by an example of the log message. See „Apache logging“ for details on logging.
checkout-or-export /path r62
depth=infinity
commit harry r100
diff /path r15:20 depth=infinity ignore-ancestry
diff /path1@15 /path2@20 depth=infinity ignore-ancestry
get-dir /trunk r17 text
get-file /path r20 props
get-file-revs /path r12:15 include-merged-revisions
get-mergeinfo (/path1 /path2)
lock /path steal
log (/path1,/path2,/path3) r20:90
discover-changed-paths revprops=()
replay /path r19
change-rev-prop r50
propertyname
rev-proplist r34
status /path r62
depth=infinity
switch /pathA /pathB@50 depth=infinity
unlock /path break
update /path r17 send-copyfrom-args
mod_authz_svn Configuration Directives — Apache configuration directives for configuring path-based authorization for Subversion repositories served through the Apache HTTP Server.
This section briefly describes each Apache configuration directive offered by mod_authz_svn. For an in-depth description of using path-based authorization in Subversion, see „Path-Based Authorization“.)
These are the httpd.conf
directives
that apply to mod_authz_svn:
AuthzSVNAccessFile
file-path
Consult file-path
for
access rules describing the permissions for paths in
Subversion repository.
AuthzSVNAnonymous On|Off
Set to Off
to disable two
special-case behaviours of this module: interaction
with the Satisfy Any
directive and
enforcement of the authorization policy even when no
Require
directives are present.
The default value of this directive is
On
.
AuthzSVNAuthoritative On|Off
Set to Off
to allow access
control to be passed along to lower modules. The
default value of this directive is
On
.
AuthzSVNNoAuthWhenAnonymousAllowed On|Off
Set to On
to suppress
authentication and authorization for requests which
anonymous users are allowed to perform. The default
value of this directive is
On
.
Subversion allows users to invent arbitrarily named
versioned properties on files and directories, as well as
unversioned properties on revisions. The only restriction is on
properties whose names begin with svn:
(those
are reserved for Subversion's own use). While these properties
may be set by users to control Subversion's behavior, users may
not invent new svn:
properties.
These are the versioned properties that Subversion reserves for its own use:
svn:executable
If present on a file, the client will make the file executable in Unix-hosted working copies. See „File Executability“.
svn:mime-type
If present on a file, the value indicates the file's MIME type. This allows the client to decide whether line-based contextual merging is safe to perform during updates, and can also affect how the file behaves when fetched via a web browser. See „File Content Type“.
svn:ignore
If present on a directory, the value is a list of unversioned file patterns to be ignored by svn status and other subcommands. See „Ignoring Unversioned Items“.
svn:keywords
If present on a file, the value tells the client how to expand particular keywords within the file. See „Keyword Substitution“.
svn:eol-style
If present on a file, the value tells the client how to manipulate the file's line-endings in the working copy and in exported trees. See „End-of-Line Character Sequences“ and svn export earlier in this chapter.
svn:externals
If present on a directory, the value is a multiline list of other paths and URLs the client should check out. See „Externals Definitions“.
svn:special
If present on a file, indicates that the file is not an ordinary file, but a symbolic link or other special object. [57]
svn:needs-lock
If present on a file, tells the client to make the file read-only in the working copy, as a reminder that the file should be locked before editing begins. See „Lock Communication“.
svn:mergeinfo
Used by Subversion to track merge data. See „Mergeinfo und Vorschauen“ for details, but you should never edit this property unless you really know what you're doing.
These are the unversioned properties that Subversion reserves for its own use:
svn:author
If present, contains the authenticated username of the person who created the revision. (If not present, the revision was committed anonymously.)
svn:date
Contains the UTC time the revision was created, in ISO 8601 format. The value comes from the server machine's clock, not the client's.
svn:log
Contains the log message describing the revision.
svn:autoversioned
If present, the revision was created via the autoversioning feature. See „Autoversioning“.
These are the repository hooks that Subversion provides:
start-commit — Notification of the beginning of a commit.
The start-commit hook is run before the commit transaction is even created. It is typically used to decide whether the user has commit privileges at all.
If the start-commit hook program returns a nonzero exit
value, the commit is stopped before the commit transaction
is even created, and anything printed to stderr
is
marshalled back to the client.
pre-commit — Notification just prior to commit completion.
The pre-commit
hook is run just
before a commit transaction is promoted to a new revision.
Typically, this hook is used to protect against commits that
are disallowed due to content or location (e.g., your
site might require that all commits to a certain branch
include a ticket number from the bug tracker, or that the
incoming log message is nonempty).
If the pre-commit
hook program
returns a nonzero exit value, the commit is aborted, the
commit transaction is removed, and anything printed to
stderr
is marshalled back to the client.
post-commit — Notification of a successful commit.
The post-commit
hook is run after the
transaction is committed and a new revision is created. Most
people use this hook to send out descriptive emails about
the commit or to notify some other tool (such as an issue
tracker) that a commit has happened. Some configurations
also use this hook to trigger backup processes.
If the post-commit
hook returns a
nonzero exit status, the commit will
not be aborted since it has already
completed. However, anything that the hook printed
to stderr
will be marshalled back to the
client, making it easier to diagnose hook failures.
pre-revprop-change — Notification of a revision property change attempt.
The pre-revprop-change
hook is run
immediately prior to the modification of a revision property
when performed outside the scope of a normal commit. Unlike
the other hooks, the default state of this one is to deny
the proposed action. The hook must actually exist and
return a zero exit value before a revision property
modification can happen.
If the pre-revprop-change
hook
doesn't exist, isn't executable, or returns a nonzero exit
value, no change to the property will be made, and anything
printed to stderr
is marshalled back to the client.
The command-line arguments passed to the hook program, in order, are:
Repository path
Revision whose property is about to be modified
Authenticated username attempting the property change
Name of the property changed
Change description: A
(added),
D
(deleted), or M
(modified)
Additionally, Subversion passes the intended new value of the property to the hook program via standard input.
post-revprop-change — Notification of a successful revision property change.
The post-revprop-change
hook is run
immediately after the modification of a revision property
when performed outside the scope of a normal commit. As you can
derive from the description of its counterpart, the
pre-revprop-change
hook, this hook will
not run at all unless
the pre-revprop-change
hook is
implemented. It is typically used to send email
notification of the property change.
If the post-revprop-change
hook returns a
nonzero exit status, the change will
not be aborted since it has already
completed. However, anything that the hook printed
to stderr
will be marshalled back to the
client, making it easier to diagnose hook failures.
The command-line arguments passed to the hook program, in order, are:
Repository path
Revision whose property was modified
Authenticated username of the person making the change
Name of the property changed
Change description: A
(added),
D
(deleted), or M
(modified)
Additionally, Subversion passes to the hook program, via standard input, the previous value of the property.
pre-lock — Notification of a path lock attempt.
The pre-lock
hook runs whenever
someone attempts to lock a path. It can be used to prevent
locks altogether or to create a more complex policy
specifying exactly which users are allowed to lock
particular paths. If the hook notices a preexisting lock,
it can also decide whether a user is allowed
to „steal“ the existing lock.
If the pre-lock
hook program returns
a nonzero exit value, the lock action is aborted and
anything printed to stderr
is marshalled back to the
client.
post-lock — Notification of a successful path lock.
The post-lock
hook runs after one or
more paths have been locked. It is typically used to send
email notification of the lock event.
If the post-lock
hook returns a
nonzero exit status, the lock will
not be aborted since it has already
completed. However, anything that the hook printed
to stderr
will be marshalled back to the
client, making it easier to diagnose hook failures.
pre-unlock — Notification of a path unlock attempt.
The pre-unlock
hook runs whenever
someone attempts to remove a lock on a file. It can be used
to create policies that specify which users are allowed to
unlock particular paths. It's particularly important for
determining policies about lock breakage. If user A locks a
file, is user B allowed to break the lock? What if the lock
is more than a week old? These sorts of things can be
decided and enforced by the hook.
If the pre-unlock
hook program
returns a nonzero exit value, the unlock action is aborted
and anything printed to stderr
is marshalled back to the
client.
post-unlock — Notification of a successful path unlock.
The post-unlock
hook runs after one
or more paths have been unlocked. It is typically used to
send email notification of the unlock event.
If the post-unlock
hook returns a
nonzero exit status, the unlock will
not be aborted since it has already
completed. However, anything that the hook printed
to stderr
will be marshalled back to the
client, making it easier to diagnose hook failures.
[55] Well, you don't need a subcommand to use the
--version
option, but we'll get to that in
just a minute.
[56] Remember, svnadmin works only with local paths, not URLs.
[57] As of this writing, symbolic links are indeed the only „special“ objects. But there might be more in future releases of Subversion.
Inhaltsverzeichnis
If you're eager to get Subversion up and running (and you enjoy learning by experimentation), this appendix will show you how to create a repository, import code, and then check it back out again as a working copy. Along the way, we give links to the relevant chapters of this book.
If you're new to the entire concept of version control or to the „copy-modify-merge“ model used by both CVS and Subversion, you should read Kapitel 1, Grundlegende Konzepte before going any further.
Subversion is built on a portability layer called APR—the Apache Portable Runtime library. The APR library provides all the interfaces that Subversion needs to function on different operating systems: disk access, network access, memory management, and so on. While Subversion is able to use Apache as one of its network server programs, its dependence on APR does not mean that Apache is a required component. APR is a standalone library usable by any application. It does mean, however, that like Apache, Subversion clients and servers run on any operating system that the Apache httpd server runs on: Windows, Linux, all flavors of BSD, Mac OS X, NetWare, and others.
The easiest way to get Subversion is to download a binary package built for your operating system. Subversion's web site (http://subversion.tigris.org) often has these packages available for download, posted by volunteers. The site usually contains graphical installer packages for users of Microsoft operating systems. If you run a Unix-like operating system, you can use your system's native package distribution system (RPMs, DEBs, the ports tree, etc.) to get Subversion.
Alternatively, you can build Subversion directly from source
code, though it's not always an easy task. (If you're not
experienced at building open source software packages, you're
probably better off downloading a binary distribution instead!)
From the Subversion web site, download the latest source code
release. After unpacking it, follow the instructions in
the INSTALL
file to build it. Note that a
released source package may not contain everything you need to
build a command-line client capable of talking to a remote
repository. Starting with Subversion 1.4 and later, the
libraries Subversion depends on (apr, apr-util, and neon) are
distributed in a separate source package suffixed
with -deps
. These libraries are now common
enough that they may already be installed on your system. If
not, you'll need to unpack the dependency package into the same
directory where you unpacked the main Subversion source.
Regardless, it's possible that you may want to fetch other
optional dependencies such as Berkeley DB and possibly Apache
httpd. If you want to do a complete build,
make sure you have all of the packages documented in
the INSTALL
file.
If you're one of those folks that likes to use bleeding-edge software, you can also get the Subversion source code from the Subversion repository in which it lives. Obviously, you'll need to already have a Subversion client on hand to do this. But once you do, you can check out a working copy of the Subversion source repository from http://svn.collab.net/repos/svn/trunk/: [58]
$ svn checkout http://svn.collab.net/repos/svn/trunk subversion A subversion/HACKING A subversion/INSTALL A subversion/README A subversion/autogen.sh A subversion/build.conf …
The preceding command will create a working copy of the
latest (unreleased) Subversion source code into a subdirectory
named subversion
in your current working
directory. You can adjust that last argument as you see fit.
Regardless of what you call the new working copy directory,
though, after this operation completes, you will now have the
Subversion source code. Of course, you will still need to fetch
a few helper libraries (apr, apr-util, etc.)—see the
INSTALL
file in the top level of the
working copy for details.
„Please make sure your seat backs are in their full, upright position and that your tray tables are stored. Flight attendants, prepare for take-off….“
What follows is a quick tutorial that walks you through some basic Subversion configuration and operation. When you finish it, you should have a general understanding of Subversion's typical usage.
The examples used in this appendix assume that you have
svn, the Subversion command-line client,
and svnadmin, the administrative tool,
ready to go on a Unix-like operating system. (This tutorial
also works at the Windows command-line prompt, assuming you
make some obvious tweaks.) We also assume you are using
Subversion 1.2 or later (run svn --version
to check.)
Subversion stores all versioned data in a central repository. To begin, create a new repository:
$ svnadmin create /var/svn/repos $ ls /var/svn/repos conf/ dav/ db/ format hooks/ locks/ README.txt
This command creates a new directory,
/var/svn/repos
, which contains a Subversion
repository. This new directory contains (among other things) a
collection of database files. You won't see your versioned
files if you peek inside. For more information about repository
creation and maintenance, see Kapitel 5, Verwaltung des Repositorys.
Subversion has no concept of a „project.“ The repository is just a virtual versioned filesystem, a large tree that can hold anything you wish. Some administrators prefer to store only one project in a repository, and others prefer to store multiple projects in a repository by placing them into separate directories. We discuss the merits of each approach in „Planung der Organisation Ihres Repositorys“. Either way, the repository manages only files and directories, so it's up to humans to interpret particular directories as „projects.“ So while you might see references to projects throughout this book, keep in mind that we're only ever talking about some directory (or collection of directories) in the repository.
In this example, we assume you already have some sort
of project (a collection of files and directories) that you wish
to import into your newly created Subversion repository. Begin
by organizing your data into a single directory called
myproject
(or whatever you wish). For
reasons explained in Kapitel 4, Verzweigen und Zusammenführen, your
project's tree structure should contain three top-level
directories named branches
,
tags
, and trunk
. The
trunk
directory should contain all of your
data, and the branches
and
tags
directories should be empty:
/tmp/myproject/branches/ /tmp/myproject/tags/ /tmp/myproject/trunk/ foo.c bar.c Makefile …
The branches
, tags
,
and trunk
subdirectories aren't actually
required by Subversion. They're merely a popular convention
that you'll most likely want to use later on.
Once you have your tree of data ready to go, import it into the repository with the svn import command (see „Wie Sie Daten in Ihr Repository bekommen“):
$ svn import /tmp/myproject file:///var/svn/repos/myproject -m "initial import" Adding /tmp/myproject/branches Adding /tmp/myproject/tags Adding /tmp/myproject/trunk Adding /tmp/myproject/trunk/foo.c Adding /tmp/myproject/trunk/bar.c Adding /tmp/myproject/trunk/Makefile … Committed revision 1. $
Now the repository contains this tree of data. As mentioned
earlier, you won't see your files by directly peeking into the
repository; they're all stored within a database. But the
repository's imaginary filesystem now contains a top-level
directory named myproject
, which in turn
contains your data.
Note that the original /tmp/myproject
directory is unchanged; Subversion is unaware of it. (In fact,
you can even delete that directory if you wish.) To
start manipulating repository data, you need to create a new
„working copy“ of the data, a sort of private
workspace. Ask Subversion to „check out“ a working
copy of the myproject/trunk
directory in
the repository:
$ svn checkout file:///var/svn/repos/myproject/trunk myproject A myproject/foo.c A myproject/bar.c A myproject/Makefile … Checked out revision 1.
Now you have a personal copy of part of the repository in a
new directory named myproject
. You can edit
the files in your working copy and then commit those changes
back into the repository.
Enter your working copy and edit a file's contents.
Run svn diff
to see unified diff
output of your changes.
Run svn commit
to commit the new
version of your file to the repository.
Run svn update
to bring your working
copy „up to date“ with the repository.
For a full tour of all the things you can do with your working copy, read Kapitel 2, Grundlegende Benutzung.
At this point, you have the option of making your repository available to others over a network. See Kapitel 6, Die Administration eines Subversion-Servers to learn about the different sorts of server processes available and how to configure them.
[58] Note that the URL checked out in the example ends not
with svn
, but with a subdirectory thereof
called trunk
. See our discussion of
Subversion's branching and tagging model for the reasoning
behind this.
Inhaltsverzeichnis
This appendix is a guide for CVS users new to Subversion. It's essentially a list of differences between the two systems as „viewed from 10,000 feet.“ For each section, we provide references to relevant chapters when possible.
Although the goal of Subversion is to take over the current and future CVS user base, some new features and design changes were required to fix certain „broken“ behaviors that CVS had. This means that, as a CVS user, you may need to break habits—ones that you forgot were odd to begin with.
In CVS, revision numbers are per file. This is because CVS stores its data in RCS files; each file has a corresponding RCS file in the repository, and the repository is roughly laid out according to the structure of your project tree.
In Subversion, the repository looks like a single filesystem. Each commit results in an entirely new filesystem tree; in essence, the repository is an array of trees. Each of these trees is labeled with a single revision number. When someone talks about „revision 54“, he's talking about a particular tree (and indirectly, the way the filesystem looked after the 54th commit).
Technically, it's not valid to talk about „revision 5
of foo.c
.“ Instead, one would say
„foo.c
as it appears in revision
5.“ Also, be careful when making assumptions about the
evolution of a file. In CVS, revisions 5 and 6 of
foo.c
are always different. In Subversion,
it's most likely that foo.c
did
not change between revisions 5 and
6.
Similarly, in CVS, a tag or branch is an annotation on the
file or on the version information for that individual file,
whereas in Subversion, a tag or branch is a copy of an entire
tree (by convention, into the /branches
or /tags
directories that appear at the top
level of the repository, beside /trunk
). In
the repository as a whole, many versions of each file may be
visible: the latest version on each branch, every tagged
version, and of course the latest version on the trunk
itself. So, to refine the terms even further, one would often
say „foo.c
as it appears in
/branches/REL1
in revision
5.“
For more details on this topic, see „Revisionen“.
Subversion tracks tree structures, not just file contents. It's one of the biggest reasons Subversion was written to replace CVS.
Here's what this means to you, as a former CVS user:
The svn add and svn
delete commands work on directories now, just as
they work on files. So do svn copy and
svn move. However, these commands do
not cause any kind of immediate change
in the repository. Instead, the working items are simply
„scheduled“ for addition or deletion. No
repository changes happen until you run svn
commit
.
Directories aren't dumb containers anymore; they have
revision numbers like files. (Or more properly, it's
correct to talk about „directory
foo/
in revision 5.“)
Let's talk more about that last point. Directory versioning is a hard problem; because we want to allow mixed-revision working copies, there are some limitations on how far we can abuse this model.
From a theoretical point of view, we define „revision
5 of directory foo
“ to mean a
specific collection of directory entries and properties. Now
suppose we start adding and removing files from
foo
, and then commit. It would be a lie
to say that we still have revision 5 of
foo
. However, if we bumped
foo
's revision number after the commit,
that would be a lie too; there may be other changes to
foo
we haven't yet received, because we
haven't updated yet.
Subversion deals with this problem by quietly tracking
committed adds and deletes in the .svn
area. When you eventually run svn update
,
all accounts are settled with the repository, and the
directory's new revision number is set correctly.
Therefore, only after an update is it truly safe to
say that you have a „perfect“ revision of a
directory. Most of the time, your working copy will
contain „imperfect“ directory revisions.
Similarly, a problem arises if you attempt to commit property changes on a directory. Normally, the commit would bump the working directory's local revision number. But again, that would be a lie, as there may be adds or deletes that the directory doesn't yet have, because no update has happened. Therefore, you are not allowed to commit property changes on a directory unless the directory is up to date.
For more discussion about the limitations of directory versioning, see „Arbeitskopien mit gemischten Revisionen“.
In recent years, disk space has become outrageously cheap and abundant, but network bandwidth has not. Therefore, the Subversion working copy has been optimized around the scarcer resource.
The .svn
administrative directory
serves the same purpose as the CVS
directory, except that it also stores read-only,
„pristine“ copies of your files. This allows you
to do many things offline:
Shows you any local changes you've made (see „Verschaffen Sie sich einen Überblick über Ihre Änderungen“)
Shows you the details of your changes (see „Untersuchen Sie die Details Ihrer lokalen Änderungen“)
Removes your local changes (see „Zurücknehmen von Änderungen in der Arbeitskopie“)
Also, the cached pristine files allow the Subversion client to send differences when committing, which CVS cannot do.
The last subcommand in the list—svn
revert—is new. It will not only remove local
changes, but also unschedule operations such as adds and
deletes. Although deleting the file and then running svn
update
will still work, doing so distorts the true
purpose of updating. And, while we're on this subject…
Subversion attempts to erase a lot of the confusion between the cvs status and cvs update commands.
The cvs status command has two purposes:
first, to show the user any local modifications in the working
copy, and second, to show the user which files are out of date.
Unfortunately, because of CVS's hard-to-read status output, many
CVS users don't take advantage of this command at all. Instead,
they've developed a habit of running cvs
update
or cvs -n update
to quickly
see their changes. If users forget to use
the -n
option, this has the side effect of
merging repository changes they may not be ready to deal
with.
Subversion removes this muddle by making the output of svn status easy to read for both humans and parsers. Also, svn update prints only information about files that are updated, not local modifications.
svn status prints all files that have local modifications. By default, the repository is not contacted. While this subcommand accepts a fair number of options, the following are the most commonly used ones:
-u
Contact the repository to determine, and then display, out-of-dateness information.
-v
Show all entries under version control.
-N
Run nonrecursively (do not descend into subdirectories).
The svn status command has two output formats. In the default „short“ format, local modifications look like this:
$ svn status M foo.c M bar/baz.c
If you specify the --show-updates
(-u
) option, a longer output format is
used:
$ svn status -u M 1047 foo.c * 1045 faces.html * bloo.png M 1050 bar/baz.c Status against revision: 1066
In this case, two new columns appear. The second column
contains an asterisk if the file or directory is out of date.
The third column shows the working copy's revision number of the
item. In the previous example, the asterisk indicates that
faces.html
would be patched if we updated,
and that bloo.png
is a newly added file in
the repository. (The absence of any revision number next to
bloo.png
means that it doesn't yet exist in
the working copy.)
At this point, you should take a quick look at the list of all possible status codes in svn status. Here are a few of the more common status codes you'll see:
A Resource is scheduled for Addition D Resource is scheduled for Deletion M Resource has local Modifications C Resource has Conflicts (changes have not been completely merged between the repository and working copy version) X Resource is eXternal to this working copy (may come from another repository). See „Externals Definitions“ ? Resource is not under version control ! Resource is missing or incomplete (removed by a tool other than Subversion)
For a more detailed discussion of svn status, see „Verschaffen Sie sich einen Überblick über Ihre Änderungen“.
svn update updates your working copy, and prints only information about files that it updates.
Subversion has combined CVS's P
and
U
codes into just U
. When
a merge or conflict occurs, Subversion simply prints
G
or C
, rather than a
whole sentence about it.
For a more detailed discussion of svn update, see „Aktualisieren Sie Ihre Arbeitskopie“.
Subversion doesn't distinguish between filesystem space and „branch“ space; branches and tags are ordinary directories within the filesystem. This is probably the single biggest mental hurdle that a CVS user will need to cross. Read all about it in Kapitel 4, Verzweigen und Zusammenführen.
Since Subversion treats branches and tags as ordinary directories, your project's various lines of development probably live in subdirectories of the main project directory. So remember to check out using the URL of the subdirectory that contains the particular line of development you want, not the project's root URL. If you make the mistake of checking out the root of the project, you may very well wind up with a working copy that contains a complete copy of your project's content for each and every one of its branches and tags. [59]
A new feature of Subversion is that you can attach arbitrary metadata (or „properties“) to files and directories. Properties are arbitrary name/value pairs associated with files and directories in your working copy.
To set or get a property name, use the svn propset and svn propget subcommands. To list all properties on an object, use svn proplist.
For more information, see „Properties“.
CVS marks conflicts with inline „conflict
markers,“ and then prints a C
during
an update or merge operation. Historically, this has caused
problems, because CVS isn't doing enough. Many users forget
about (or don't see) the C
after it whizzes
by on their terminal. They often forget that the conflict
markers are even present, and then accidentally commit files
containing those conflict markers.
Subversion solves this problem in a pair of ways. First, when a conflict occurs in a file, Subversion records the fact that the file is in a state of conflict, and won't allow you to commit changes to that file until you explicitly resolve the conflict. Second, Subversion 1.5 provides interactive conflict resolution, which allows you to resolve conflicts as they happen instead of having to go back and do so after the update or merge operation completes. See „Konflikte auflösen (Änderungen anderer einarbeiten)“ for more about conflict resolution in Subversion.
In the most general sense, Subversion handles binary files more gracefully than CVS does. Because CVS uses RCS, it can only store successive full copies of a changing binary file. Subversion, however, expresses differences between files using a binary differencing algorithm, regardless of whether they contain textual or binary data. That means all files are stored differentially (compressed) in the repository.
CVS users have to mark binary files with
-kb
flags to prevent data from being
garbled (due to keyword expansion and line-ending translations).
They sometimes forget to do this.
Subversion takes the more paranoid route. First, it never performs any kind of keyword or line-ending translation unless you explicitly ask it to do so (see „Keyword Substitution“ and „End-of-Line Character Sequences“ for more details). By default, Subversion treats all file data as literal byte strings, and files are always stored in the repository in an untranslated state.
Second, Subversion maintains an internal notion of whether a file is „text“ or „binary“ data, but this notion is only extant in the working copy. During an svn update, Subversion will perform contextual merges on locally modified text files, but will not attempt to do so for binary files.
To determine whether a contextual merge is possible,
Subversion examines the svn:mime-type
property. If the file has no svn:mime-type
property, or has a MIME type that is textual (e.g.,
text/*
),
Subversion assumes it is text. Otherwise, Subversion assumes
the file is binary. Subversion also helps users by running a
binary-detection algorithm in the svn import
and svn add commands. These commands will
make a good guess and then (possibly) set a binary
svn:mime-type
property on the file being
added. (If Subversion guesses wrong, the user can always remove
or hand-edit the property.)
Unlike CVS, a Subversion working copy is aware that it has checked out a module. That means if somebody changes the definition of a module (e.g., adds or removes components), a call to svn update will update the working copy appropriately, adding and removing components.
Subversion defines modules as a list of directories within a directory property; see „Externals Definitions“.
With CVS's pserver, you are required to log in to the server (using the cvs login command) before performing any read or write operation—you sometimes even have to log in for anonymous operations. With a Subversion repository using Apache httpd or svnserve as the server, you don't provide any authentication credentials at the outset—if an operation that you perform requires authentication, the server will challenge you for your credentials (whether those credentials are username and password, a client certificate, or even both). So if your repository is world-readable, you will not be required to authenticate at all for read operations.
As with CVS, Subversion still caches your credentials on
disk (in your ~/.subversion/auth/
directory) unless you tell it not to by using the
--no-auth-cache
option.
The exception to this behavior, however, is in the case of
accessing an svnserve server over an SSH
tunnel, using the svn+ssh://
URL scheme. In
that case, the ssh program unconditionally
demands authentication just to start the tunnel.
Perhaps the most important way to familiarize CVS users with Subversion is to let them continue to work on their projects using the new system. And while that can be somewhat accomplished using a flat import into a Subversion repository of an exported CVS repository, the more thorough solution involves transferring not just the latest snapshot of their data, but all the history behind it as well, from one system to another. This is an extremely difficult problem to solve; it involves deducing changesets in the absence of atomicity and translating between the systems' completely orthogonal branching policies, among other complications. Still, a handful of tools claim to at least partially support the ability to convert existing CVS repositories into Subversion ones.
The most popular (and mature) conversion tool is cvs2svn (http://cvs2svn.tigris.org/), a Python program originally created by members of Subversion's own development community. This tool is meant to run exactly once: it scans your CVS repository multiple times and attempts to deduce commits, branches, and tags as best it can. When it finishes, the result is either a Subversion repository or a portable Subversion dump file representing your code's history. See the web site for detailed instructions and caveats.
Inhaltsverzeichnis
WebDAV is an extension to HTTP, and it is growing more and more popular as a standard for file sharing. Today's operating systems are becoming extremely web-aware, and many now have built-in support for mounting „shares“ exported by WebDAV servers.
If you use Apache as your Subversion network server, to some extent you are also running a WebDAV server. This appendix gives some background on the nature of this protocol, how Subversion uses it, and how well Subversion interoperates with other software that is WebDAV-aware.
DAV stands for „Distributed Authoring and Versioning.“ RFC 2518 defines a set of concepts and accompanying extension methods to HTTP 1.1 that make the Web a more universal read/write medium. The basic idea is that a WebDAV-compliant web server can act like a generic file server; clients can „mount“ shared folders over HTTP that behave much like other network filesystems (such as NFS or SMB).
The tragedy, though, is that despite the acronym, the RFC specification doesn't actually describe any sort of version control. Basic WebDAV clients and servers assume that only one version of each file or directory exists, and that it can be repeatedly overwritten.
Because RFC 2518 left out versioning concepts, another committee was left with the responsibility of writing RFC 3253 a few years later. The new RFC adds versioning concepts to WebDAV, placing the „V“ back in „DAV“—hence the term „DeltaV.“ WebDAV/DeltaV clients and servers are often called just „DeltaV“ programs, since DeltaV implies the existence of basic WebDAV.
The original WebDAV standard has been widely successful. Every modern computer operating system has a general WebDAV client built in (details to follow), and a number of popular standalone applications are also able to speak WebDAV—Microsoft Office, Dreamweaver, and Photoshop, to name a few. On the server end, Apache HTTP Server has been able to provide WebDAV services since 1998 and is considered the de facto open source standard. Several other commercial WebDAV servers are available, including Microsoft's own IIS.
DeltaV, unfortunately, has not been so successful. It's very difficult to find any DeltaV clients or servers. The few that do exist are relatively unknown commercial products, and thus it's very difficult to test interoperability. It's not entirely clear as to why DeltaV has remained stagnant. Some opine that the specification is just too complex. Others argue that while WebDAV's features have mass appeal (even the least technical users appreciate network file sharing), its version control features just aren't interesting or necessary for most users. Finally, some believe that DeltaV remains unpopular because there's still no open source server product that implements it well.
When Subversion was still in its design phase, it seemed like a great idea to use Apache as a network server. It already had a module to provide WebDAV services. DeltaV was a relatively new specification. The hope was that the Subversion server module (mod_dav_svn) would eventually evolve into an open source DeltaV reference implementation. Unfortunately, DeltaV has a very specific versioning model that doesn't quite line up with Subversion's model. Some concepts were mappable; others were not.
What does this mean, then?
First, the Subversion client is not a fully implemented
DeltaV client. It needs certain types of things from the server
that DeltaV itself cannot provide, and thus is largely dependent
on a number of Subversion-specific
HTTP REPORT
requests that
only mod_dav_svn understands.
Second, mod_dav_svn is not a fully realized DeltaV server. Many portions of the DeltaV specification were irrelevant to Subversion, and thus were left unimplemented.
There is still some debate in the developer community as to whether or not it's worthwhile to remedy either of these situations. It's fairly unrealistic to change Subversion's design to match DeltaV, so there's probably no way the client can ever learn to get everything it needs from a general DeltaV server. On the other hand, mod_dav_svn could be further developed to implement all of DeltaV, but it's hard to find motivation to do so—there are almost no DeltaV clients to interoperate with.
While the Subversion client is not a full DeltaV client, and the Subversion server is not a full DeltaV server, there's still a glimmer of WebDAV interoperability to be happy about: autoversioning.
Autoversioning is an optional feature defined in the DeltaV
standard. A typical DeltaV server will reject an ignorant
WebDAV client attempting to do a PUT
to a
file that's under version control. To change a
version-controlled file, the server expects a series of proper
versioning requests: something like
MKACTIVITY
, CHECKOUT
,
PUT
, CHECKIN
. But if the
DeltaV server supports autoversioning, write requests from
basic WebDAV clients are accepted. The server behaves as though the
client had issued the proper series of
versioning requests, performing a commit under the hood. In
other words, it allows a DeltaV server to interoperate with
ordinary WebDAV clients that don't understand versioning.
Because so many operating systems already have integrated WebDAV clients, the use case for this feature can be incredibly appealing to administrators working with non-technical users. Imagine an office of ordinary users running Microsoft Windows or Mac OS. Each user „mounts“ the Subversion repository, which appears to be an ordinary network folder. They use the shared folder as they always do: open files, edit them, and save them. Meanwhile, the server is automatically versioning everything. Any administrator (or knowledgeable user) can still use a Subversion client to search history and retrieve older versions of data.
This scenario isn't fiction—it's real and it works, as
of Subversion 1.2 and later. To activate autoversioning in
mod_dav_svn, use the
SVNAutoversioning
directive within the
httpd.conf
Location
block, like so:
<Location /repos> DAV svn SVNPath /var/svn/repository SVNAutoversioning on </Location>
When Subversion autoversioning is active, write requests from WebDAV clients result in automatic commits. A generic log message is automatically generated and attached to each revision.
Before activating this feature, however, understand what
you're getting into. WebDAV clients tend to do
many write requests, resulting in a huge
number of automatically committed revisions. For example, when
saving data, many clients will do a PUT
of a
0-byte file (as a way of reserving a name) followed by another
PUT
with the real file data. The single
file-write results in two separate commits. Also consider that
many applications auto-save every few minutes, resulting in even
more commits.
If you have a post-commit hook program that sends email, you
may want to disable email generation either altogether or on
certain sections of the repository; it depends on whether you
think the influx of emails will still prove to be valuable
notifications or not. Also, a smart post-commit hook program
can distinguish between a transaction created via autoversioning
and one created through a normal Subversion commit operation.
The trick is to look for a revision property
named svn:autoversioned
. If present, the
commit was made by a generic WebDAV client.
Another feature that may be a useful complement for
Subversion's autoversioning comes from Apache's
mod_mime
module. If a WebDAV client adds a
new file to the repository, there's no opportunity for the user
to set the the svn:mime-type
property. This
might cause the file to appear as a generic icon when viewed
within a WebDAV shared folder, not having an association with
any application. One remedy is to have a sysadmin (or other
Subversion-knowledgeable person) check out a working copy and
manually set the svn:mime-type
property on
necessary files. But there's potentially no end to such cleanup
tasks. Instead, you can use the
ModMimeUsePathInfo
directive in your
Subversion <Location>
block:
<Location /repos> DAV svn SVNPath /var/svn/repository SVNAutoversioning on ModMimeUsePathInfo on </Location>
This directive allows mod_mime
to attempt
automatic deduction of the MIME type on new files that enter the
repository via autoversioning. The module looks at the file's
named extension and possibly the contents as well; if the file
matches some common patterns, the
file's svn:mime-type
property will be set
automatically.
All WebDAV clients fall into one of three categories—standalone applications, file-explorer extensions, or filesystem implementations. These categories broadly define the types of WebDAV functionality available to users. Tabelle C.1, „Common WebDAV clients“ gives our categorization as well as a quick description of some common pieces of WebDAV-enabled software. You can find more details about these software offerings, as well as their general category, in the sections that follow.
Tabelle C.1. Common WebDAV clients
Software | Type | Windows | Mac | Linux | Description |
---|---|---|---|---|---|
Adobe Photoshop | Standalone WebDAV application | X | Image editing software, allowing direct opening from, and writing to, WebDAV URLs | ||
cadaver | Standalone WebDAV application | X | X | Command-line WebDAV client supporting file transfer, tree, and locking operations | |
DAV Explorer | Standalone WebDAV application | X | X | X | Java GUI tool for exploring WebDAV shares |
Macromedia Dreamweaver | Standalone WebDAV application | X | Web production software able to directly read from and write to WebDAV URLs | ||
Microsoft Office | Standalone WebDAV application | X | Office productivity suite with several components able to directly read from and write to WebDAV URLs | ||
Microsoft Web Folders | File-explorer WebDAV extension | X | GUI file explorer program able to perform tree operations on a WebDAV share | ||
GNOME Nautilus | File-explorer WebDAV extension | X | GUI file explorer able to perform tree operations on a WebDAV share | ||
KDE Konqueror | File-explorer WebDAV extension | X | GUI file explorer able to perform tree operations on a WebDAV share | ||
Mac OS X | WebDAV filesystem implementation | X | Operating system that has built-in support for mounting WebDAV shares. | ||
Novell NetDrive | WebDAV filesystem implementation | X | Drive-mapping program for assigning Windows drive letters to a mounted remote WebDAV share | ||
SRT WebDrive | WebDAV filesystem implementation | X | File transfer software, which, among other things, allows the assignment of Windows drive letters to a mounted remote WebDAV share | ||
davfs2 | WebDAV filesystem implementation | X | Linux filesystem driver that allows you to mount a WebDAV share |
A WebDAV application is a program that speaks WebDAV protocols with a WebDAV server. We'll cover some of the most popular programs with this kind of WebDAV support.
On Windows, several well-known applications contain integrated WebDAV client functionality, such as Microsoft's Office, [60] Adobe's Photoshop, and Macromedia's Dreamweaver programs. They're able to directly open and save to URLs, and tend to make heavy use of WebDAV locks when editing a file.
Note that while many of these programs also exist for Mac OS X, they do not appear to support WebDAV directly on that platform. In fact, on Mac OS X, the
dialog box doesn't allow one to type a path or URL at all. It's likely that the WebDAV features were deliberately left out of Macintosh versions of these programs, since OS X already provides such excellent low-level filesystem support for WebDAV.cadaver is a bare-bones Unix command-line program for browsing and changing WebDAV shares. Like the Subversion client, it uses the neon HTTP library—not surprisingly, since both neon and cadaver are written by the same author. cadaver is free software (GPL license) and is available at http://www.webdav.org/cadaver/.
Using cadaver is similar to using a command-line FTP program, and thus it's extremely useful for basic WebDAV debugging. It can be used to upload or download files in a pinch, to examine properties, and to copy, move, lock, or unlock files:
$ cadaver http://host/repos dav:/repos/> ls Listing collection `/repos/': succeeded. Coll: > foobar 0 May 10 16:19 > playwright.el 2864 May 4 16:18 > proofbypoem.txt 1461 May 5 15:09 > westcoast.jpg 66737 May 5 15:09 dav:/repos/> put README Uploading README to `/repos/README': Progress: [=============================>] 100.0% of 357 bytes succeeded. dav:/repos/> get proofbypoem.txt Downloading `/repos/proofbypoem.txt' to proofbypoem.txt: Progress: [=============================>] 100.0% of 1461 bytes succeeded.
DAV Explorer is another standalone WebDAV client, written in Java. It's under a free Apache-like license and is available at http://www.ics.uci.edu/~webdav/. It does everything cadaver does, but has the advantages of being portable and being a more user-friendly GUI application. It's also one of the first clients to support the new WebDAV Access Control Protocol (RFC 3744).
Of course, DAV Explorer's ACL support is useless in this
case, since mod_dav_svn doesn't support
it. The fact that both cadaver and DAV Explorer support
some limited DeltaV commands isn't particularly useful
either, since they don't allow MKACTIVITY
requests. But it's not relevant anyway; we're assuming all
of these clients are operating against an autoversioning
repository.
Some popular file explorer GUI programs support WebDAV extensions that allow a user to browse a DAV share as though it was just another directory on the local computer, and to perform basic tree editing operations on the items in that share. For example, Windows Explorer is able to browse a WebDAV server as a „network place.“ Users can drag files to and from the desktop, or can rename, copy, or delete files in the usual way. But because it's only a feature of the file explorer, the DAV share isn't visible to ordinary applications. All DAV interaction must happen through the explorer interface.
Microsoft was one of the original backers of the WebDAV specification, and first started shipping a client in Windows 98, which was known as Web Folders. This client was also shipped in Windows NT 4.0 and Windows 2000.
The original Web Folders client was an extension to Explorer, the main GUI program used to browse filesystems. It works well enough. In Windows 98, the feature might need to be explicitly installed if Web Folders aren't already visible inside My Computer. In Windows 2000, simply add a new „network place,“ enter the URL, and the WebDAV share will pop up for browsing.
With the release of Windows XP, Microsoft started shipping
a new implementation of Web Folders, known as the WebDAV
Mini-Redirector. The new implementation is a
filesystem-level client, allowing WebDAV shares to be mounted
as drive letters. Unfortunately, this implementation is
incredibly buggy. The client usually tries to convert HTTP
URLs (http://host/repos
) into UNC share
notation (\\host\repos
); it also often
tries to use Windows Domain authentication to respond to
basic-auth HTTP challenges, sending usernames as
HOST\username
. These interoperability
problems are severe and are documented in numerous places around
the Web, to the frustration of many users. Even Greg Stein,
the original author of Apache's WebDAV module, bluntly
states that XP Web Folders simply can't operate against an Apache
server.
Windows Vista's initial implementation of Web Folders seems to be almost the same as XP's, so it has the same sort of problems. With luck, Microsoft will remedy these issues in a Vista Service Pack.
However, there seem to be workarounds for both XP and Vista that allow Web Folders to work against Apache. Users have mostly reported success with these techniques, so we'll relay them here.
On Windows XP, you have two options. First, search
Microsoft's web site for update KB90730, „Software
Update for Web Folders.“ This may fix all your
problems. If it doesn't, it seems that the original pre-XP
Web Folders implementation is still buried within the
system. You can unearth it by going to Network
Places and adding a new network place. When prompted,
enter the URL of the repository, but include a
port number in the URL. For
example, you should enter http://host/repos
as http://host:80/repos
instead.
Respond to any authentication prompts with your Subversion
credentials.
On Windows Vista, the same KB90730 update may clear
everything up. But there may still be other issues. Some
users have reported that Vista considers
all http://
connections insecure, and thus
will always fail any authentication challenges from Apache
unless the connection happens
over https://
. If you're unable to connect
to the Subversion repository via SSL, you can tweak the
system registry to turn off this behavior. Just change the
value of the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\WebClient\Parameters\BasicAuthLevel
key from 1
to 2
. A final warning: be sure to set up the Web
Folder to point to the repository's root directory
(/
), rather than some subdirectory
such as /trunk
. Vista Web Folders
seems to work only against repository roots.
In general, while these workarounds may function for you, you might get a better overall experience using a third-party WebDAV client such as WebDrive or NetDrive.
Nautilus is the official file manager/browser for the GNOME desktop (http://www.gnome.org), and Konqueror is the manager/browser for the KDE desktop (http://www.kde.org). Both of these applications have an explorer-level WebDAV client built in, and they operate just fine against an autoversioning repository.
In GNOME's Nautilus, select the
menu item and enter the URL in the dialog box presented. The repository should then be displayed like any other filesystem.In KDE's Konqueror, you need to use the
webdav://
scheme when entering the URL in
the location bar. If you enter
an http://
URL, Konqueror will behave
like an ordinary web browser. You'll likely see the generic
HTML directory listing produced
by mod_dav_svn. When you enter
webdav://host/repos
instead of
http://host/repos
, Konqueror becomes a
WebDAV client and displays the repository as a
filesystem.
The WebDAV filesystem implementation is arguably the best sort of WebDAV client. It's implemented as a low-level filesystem module, typically within the operating system's kernel. This means that the DAV share is mounted like any other network filesystem, similar to mounting an NFS share on Unix or attaching an SMB share as a drive letter in Windows. As a result, this sort of client provides completely transparent read/write WebDAV access to all programs. Applications aren't even aware that WebDAV requests are happening.
Both WebDrive and NetDrive are excellent commercial products that allow a WebDAV share to be attached as drive letters in Windows. As a result, you can operate on the contents of these WebDAV-backed pseudodrives as easily as you can against real local hard drives, and in the same ways. You can purchase WebDrive from South River Technologies (http://www.southrivertech.com). Novell's NetDrive is freely available online, but requires users to have a NetWare license.
Apple's OS X operating system has an integrated
filesystem-level WebDAV client. From the Finder, select the
webdav
filesystem type with the
mount command:
$ mount -t webdav http://svn.example.com/repos/project /some/mountpoint $
Note that if your mod_dav_svn is older than version 1.2, OS X will refuse to mount the share as read/write; it will appear as read-only. This is because OS X insists on locking support for read/write shares, and the ability to lock files first appeared in Subversion 1.2.
Also, OS X's WebDAV client can sometimes be overly
sensitive to HTTP redirects. If OS X is unable to mount the
repository at all, you may need to enable the BrowserMatch
directive in the Apache server's
httpd.conf
:
BrowserMatch "^WebDAVFS/1.[012]" redirect-carefully
Linux davfs2 is a filesystem module for the Linux kernel, whose development is organized at http://dav.sourceforge.net/. Once you install davfs2, you can mount a WebDAV network share using the usual Linux mount command:
$ mount.davfs http://host/repos /mnt/dav
[60] WebDAV support was removed from Microsoft Access for some reason, but it exists in the rest of the Office suite.
Copyright (c) 2002-2008 Ben Collins-Sussman, Brian W. Fitzpatrick, C. Michael Pilato. This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit http://creativecommons.org/licenses/by/2.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA. A summary of the license is given below, followed by the full legal text. -------------------------------------------------------------------- You are free: * to copy, distribute, display, and perform the work * to make derivative works * to make commercial use of the work Under the following conditions: Attribution. You must give the original author credit. * For any reuse or distribution, you must make clear to others the license terms of this work. * Any of these conditions can be waived if you get permission from the author. Your fair use and other rights are in no way affected by the above. The above is a summary of the full license below. ==================================================================== Creative Commons Legal Code Attribution 2.0 CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM ITS USE. License THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS. 1. Definitions a. "Collective Work" means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in unmodified form, along with a number of other contributions, constituting separate and independent works in themselves, are assembled into a collective whole. A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License. b. "Derivative Work" means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment, condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes a Collective Work will not be considered a Derivative Work for the purpose of this License. For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered a Derivative Work for the purpose of this License. c. "Licensor" means the individual or entity that offers the Work under the terms of this License. d. "Original Author" means the individual or entity who created the Work. e. "Work" means the copyrightable work of authorship offered under the terms of this License. f. "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation. 2. Fair Use Rights. Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws. 3. License Grant. Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below: a. to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works; b. to create and reproduce Derivative Works; c. to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works; d. to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission Derivative Works. e. For the avoidance of doubt, where the work is a musical composition: i. Performance Royalties Under Blanket Licenses. Licensor waives the exclusive right to collect, whether individually or via a performance rights society (e.g. ASCAP, BMI, SESAC), royalties for the public performance or public digital performance (e.g. webcast) of the Work. ii. Mechanical Rights and Statutory Royalties. Licensor waives the exclusive right to collect, whether individually or via a music rights agency or designated agent (e.g. Harry Fox Agency), royalties for any phonorecord You create from the Work ("cover version") and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions). f. Webcasting Rights and Statutory Royalties. For the avoidance of doubt, where the Work is a sound recording, Licensor waives the exclusive right to collect, whether individually or via a performance-rights society (e.g. SoundExchange), royalties for the public digital performance (e.g. webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions). The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. All rights not expressly granted by Licensor are hereby reserved. 4. Restrictions.The license granted in Section 3 above is expressly made subject to and limited by the following restrictions: a. You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Work that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License. If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any reference to such Licensor or the Original Author, as requested. If You create a Derivative Work, upon notice from any Licensor You must, to the extent practicable, remove from the Derivative Work any reference to such Licensor or the Original Author, as requested. b. If you distribute, publicly display, publicly perform, or publicly digitally perform the Work or any Derivative Works or Collective Works, You must keep intact all copyright notices for the Work and give the Original Author credit reasonable to the medium or means You are utilizing by conveying the name (or pseudonym if applicable) of the Original Author if supplied; the title of the Work if supplied; to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and in the case of a Derivative Work, a credit identifying the use of the Work in the Derivative Work (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). Such credit may be implemented in any reasonable manner; provided, however, that in the case of a Derivative Work or Collective Work, at a minimum such credit will appear where any other comparable authorship credit appears and in a manner at least as prominent as such other comparable authorship credit. 5. Representations, Warranties and Disclaimer UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. 6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 7. Termination a. This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Derivative Works or Collective Works from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License. b. Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above. 8. Miscellaneous a. Each time You distribute or publicly digitally perform the Work or a Collective Work, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License. b. Each time You distribute or publicly digitally perform a Derivative Work, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License. c. If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable. d. No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent. e. This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You. Creative Commons is not a party to this License, and makes no warranty whatsoever in connection with the Work. Creative Commons will not be liable to You or any party on any legal theory for any damages whatsoever, including without limitation any general, special, incidental or consequential damages arising in connection to this license. Notwithstanding the foregoing two (2) sentences, if Creative Commons has expressly identified itself as the Licensor hereunder, it shall have all rights and obligations of Licensor. Except for the limited purpose of indicating to the public that the Work is licensed under the CCPL, neither party will use the trademark "Creative Commons" or any related trademark or logo of Creative Commons without the prior written consent of Creative Commons. Any permitted use will be in compliance with Creative Commons' then-current trademark usage guidelines, as may be published on its website or otherwise made available upon request from time to time. Creative Commons may be contacted at http://creativecommons.org/. ====================================================================