Subversion ist in der Lage, Schlüsselworte – nützliche dynamische Informationshäppchen zu einer versionierten Datei – im Dateiinhalt zu ersetzen. Schlüsselworte liefern im Allgemeinen Informationen zur letzten Änderung an der Datei. Da diese Information sich mit jeder Änderung der Datei auch ändert, noch wichtiger, nachdem sich die Datei ändert, ist es für jeden Prozess außer dem Versions-Kontroll-System ein ziemlicher Aufwand, die Daten vollständig aktuell zu halten. Würde das den Autoren überlassen, veralteten die Informationen unausweichlich.

Nehmen wir beispielsweise an, dass Sie ein Dokument haben, in dem das Datum der letzten Änderung angezeigt werden soll. Sie könnten natürlich jedem Bearbeiter auferlegen, kurz vor dem Übertragen ihrer Änderungen, den Teil des Dokumentes, der das Änderungsdatum enthält, entsprechend anzupassen. Früher oder später jedoch wird jemand vergessen, das zu tun. Teilen Sie stattdessen Subversion mit, eine Schlüsselwort-Ersetzung mit dem Schlüsselwort LastChangedDate vorzunehmen. Sie kontrollieren, wo das Schlüsselwort in Ihrem Dokument eingefügt wird, indem Sie einen Schlüsselwort-Anker an die gewünschte Stelle der Datei setzen. Dieser Anker ist einfach eine Zeichenkette, die formatiert ist wie $KeywordName$.

Das alleinige Hinzufügen von Schlüsselworten zu Ihren Dateien als Ankertext bewirkt nichts besonderes. Subversion wird niemals versuchen, textuelle Ersetzungen an Ihren Dateiinhalten vorzunehmen, wenn Sie es nicht ausdrücklich dazu auffordern. Schließlich kann es sein, dass Sie ein Dokument^[27] über die Verwendung von Schlüsselworten verfassen und Sie wollen nicht, dass Subversion Ihre wunderschönen Beispiele von nicht-ersetzten Schlüsselwort-Ankern ersetzt.

Um Subversion mitzuteilen, ob Schlüsselworte in einer bestimmten Datei ersetzt werden sollen, wenden wir uns wiederum den Unterbefehlen zu, die mit Eigenschaften zu tun haben. Die Eigenschaft svn:keywords an einer versionierten Datei kontrolliert, welche Schlüsselworte in dieser Datei ersetzt werden. Der Wert ist eine durch Leerzeichen getrennte Liste aus Schlüsselwort-Namen oder deren Aliasnamen.

Nehmen wir an, sie haben eine versionierte Datei namens weather.txt, die folgendermaßen aussieht:

Hier ist der neueste Bericht von der vordersten Front.
$LastChangedDate$
$Rev$
Cumulus-Wolken entstehen öfter, wenn der Sommer naht.

Ohne die Eigenschaft svn:keywords auf dieser Datei wird Subversion nichts Besonderes machen. Nun schalten wir die Ersetzung des Schlüsselwortes LastChangedDate ein.

$ svn propset svn:keywords "Date Author" weather.txt 
Eigenschaft »svn:keywords« für »weather.txt« gesetzt
$

Nun haben Sie eine lokale Änderung an einer Eigenschaft der Datei weather.txt vorgenommen. Sie werden keine Änderungen am Dateiinhalt erkennen können (es sei denn, sie hätten einige vor dem Setzen der Eigenschaft gemacht). Beachten Sie, dass die Datei einen Anker für das Schlüsselwort Rev enthielt, wir dieses Schlüsselwort jedoch nicht in den Wert der von uns gesetzten Eigenschaft aufnahmen. Es ist Subversion ein Vergnügen, alle Aufforderungen zu ignorieren, Schlüsselworte zu ersetzen, die nicht in der Datei oder im Wert der Eigenschaft svn:keywords vorhanden sind.

Unmittelbar nachdem Sie diese Änderung der Eigenschaft übertragen haben, wird Subversion Ihre Arbeitsdatei mit dem neuen Ersatztext aktualisieren. Statt des Schlüsselwort-Ankers $LastChangedDate$ werden Sie das Ergebnis der Ersetzung sehen. Das Ergebnis enthält auch das Schlüsselwort und wird weiterhin durch die Dollarzeichen ($) begrenzt. Und wie wir vorhergesehen hatten, wurde das Schlüsselwort Rev nicht ersetzt, da wir es nicht wollten.

Beachten Sie auch, dass wir die Eigenschaft svn:keywords auf Date Author setzten, der Schlüsselwort-Anker aber das Alias $LastChangedDate$ verwendete und trotzdem korrekt erweitert wurde:

Hier ist der neueste Bericht von der vordersten Front.
$LastChangedDate: 2006-07-22 21:42:37 -0700 (Sa, 22. Jul 2006) $
$Rev$
Cumulus-Wolken entstehen öfter, wenn der Sommer naht.

Falls nun jemand anderes eine Änderung an weather.txt überträgt, wird Ihre Kopie der Datei den gleichen ersetzten Wert des Schlüsselwortes anzeigen wie vorher – bis Sie Ihre Arbeitskopie aktualisieren. Zu diesem Zeitpunkt werden die Schlüsselworte in Ihrer Datei weather.txt mit Informationen ersetzt, die der letzten bekannten Übertragung dieser Datei entsprechen.

Bei allen Schlüsselworten, die als Anker in Dateien verwendet werden, ist die Groß- und Kleinschreibung relevant. Sie müssen die korrekte Schreibung verwenden, damit das Schlüsselwort ersetzt wird. Sie sollten davon ausgehen, dass auch die Groß- und Kleinschreibung der Eigenschaftswerte von svn:keywords relevant ist – aus Gründen der Rückwärtskompatibilität werden bestimmte Schlüsselworte dessen ungeachtet erkannt, jedoch wird abgeraten, von diesem Verhalten auszugehen.

Subversion definiert die Liste der Schlüsselworte, die für die Ersetzung verfügbar sind. Diese Liste enthält die folgenden Schlüsselworte, von denen einige Aliasnamen besitzen, die Sie auch verwenden können.

Einige der vorangegangenen Beschreibungen verwenden Formulierungen wie „letzte bekannte“ oder Ähnliches. Denken Sie daran, dass die Schlüsselwort-Ersetzung vom Client vorgenommen wird und dieser nur Änderungen „kennt“, die im Projektarchiv stattgefunden haben, als Sie Ihre Arbeitskopie aktualisiert haben, um diese Änderungen zu bekommen. Falls Sie Ihre Arbeitskopie nie aktualisieren, werden Ihre Schlüsselworte niemals durch andere Werte ersetzt werden, auch wenn diese Dateien regelmäßig im Projektarchiv geändert werden.

Zusätzlich zur früheren Menge von Standard-Schlüsselwort-Definitionen und Aliasen, gibt Subversion 1.8 Ihnen die Freiheit, maßgeschneiderte Schlüsselworte zu definieren und verwenden. Um ein maßgeschneidertes Schlüsselwort zu definieren, fügen Sie dem Wert der Eigenschaft svn:keywords eine Zeichenkette im Format MyKeyword=FORMAT, hinzu, wobei MyKeyword der Name des Schlüsselwortes ist (den Sie im Schlüsselwort-Anker verwenden) und FORMAT eine Format-Zeichenkette ist, in die die Information übertragen wird, wenn das Schlüsselwort in Ihrer Datei ersetzt wird.

Die Syntax für die Format-Zeichenkette bei maßgeschneiderten Schlüsselworten unterstützt die folgenden Format-Codes:

Wie Sie sehen können, dienen viele der individuellen Format-Codes als Platzhalter für dieselben Informationen, die über die Standard-Schlüsselworte verfügbar sind. Natürlich erlaubt Ihnen das Format für maßgeschneiderte Schlüsselworte aber verschiedene Informationsschnipsel flexibel zu kombinieren. Sie möchten beispielsweise ein einzelnes Schlüsselwort in Ihren Dateien haben, mit dem der relative Pfad der Datei im Projektarchiv und die zuletzt geänderte Revision in einem angenehmen, menschenlesbaren Format anzeigt wird. Hierzu definieren Sie zunächst Ihr maßgeschneidertes Schlüsselwort:

$ svn pset svn:keywords "PathRev=%P,%_r%r" calc/button.c
Eigenschaft »svn:keywords« für »button.c« gesetzt
$

Als nächstes ändern Sie den Dateiinhalt, indem Sie den Anker für Ihr maßgeschneidertes Schlüsselwort hinzufügen, der in diesem Fall $PathRev$ ist. Nach der Übertragung dieser Änderungen zeigt sich bei Betrachtung des Dateiinhaltes, dass Ihr maßgeschneidertes Schlüsselwort wie erwartet ersetzt wurde – wo vorher $PathRev$ stand, steht nun $PathRev: trunk/calc/button.c, r23 $.

	Anmerkung
	Subversion schneidet automatisch alle Ersetzungen ab, die 255 Bytes an Länge überschreiten. Auch maßgeschneiderte Schlüsselworte, deren Namen länger als 255 Bytes sind, werden vollständig ignoriert.

Sie können Subversion mitteilen, eine feste Länge (die Anzahl verwendeter Bytes) für ein ersetztes Schlüsselwort vorzuhalten. Indem ein doppelter Doppelpunkt (::) nach dem Namen des Schlüsselwortes geschrieben wird, dem eine Anzahl von Leerzeichen folgt, definieren Sie diese feste Breite. Wenn Subversion nun dieses Schlüsselwort durch das Schlüsselwort und seinen Wert ersetzt, werden im Wesentlichen nur die Leerzeichen ersetzt, so dass die Gesamtbreite des Schlüsselwort-Felds unverändert bleibt. Falls der ersetzte Wert kürzer als das definierte Feld ist, werden am Ende des ersetzten Feldes zusätzliche Füllzeichen (Leerzeichen) eingefügt; falls er zu lang ist, wird er mit einem speziellen Nummernzeichen (#) unmittelbar vor dem letzten Dollarzeichen abgeschnitten.

Nehmen wir zum Beispiel an, Sie hätten ein Dokument, in dem sich ein tabellarischer Abschnitt mit den Subversion-Schlüsselworten befindet. Mit der originalen Syntax für die Schlüsselwort-Ersetzung von Subversion würde die Datei etwa so aussehen:

$Rev$:     Revision der letzten Übertragung
$Author$:  Autor der letzten Übertragung
$Date$:    Datum der letzten Übertragung

Zu Beginn sieht das noch hübsch aus. Wenn Sie die Datei dann allerdings (natürlich mit aktivierter Schlüsselwort-Ersetzung) übertragen, sehen Sie:

$Rev: 12 $:     Revision der letzten Übertragung
$Author: harry $:  Autor der letzten Übertragung
$Date: 2006-03-15 02:33:03 -0500 (Mi, 15. Mär 2006) $:    Datum der letzten Übertragung

Das Ergebnis ist weniger hübsch. Vielleicht sind Sie versucht, die Datei zu korrigieren, so dass es wieder tabellarisch aussieht. Allerdings hält das nur so lange vor, wie die Werte der Schlüsselworte die gleiche Länge haben. Falls die Revision der letzten Änderung eine weitere Stelle einnimmt (etwa von 99 auf 100) oder eine Person mit einem längeren Benutzernamen die Datei überträgt, sieht alles wieder schief aus. Wenn Sie jedoch Subversion 1.2 oder neuer verwenden, können Sie die neue Schlüsselwort-Syntax mit fester Länge verwenden und vernünftige Feldlängen definieren, etwa:

$Rev::               $:  Revision der letzten Übertragung
$Author::            $:  Autor der letzten Übertragung
$Date::              $:  Datum der letzten Übertragung

Sie übertragen diese Änderung an Ihrer Datei. Diesmal bemerkt Subversion die neue Schlüsselwort-Syntax mit fester Länge und behält die Breite der Felder bei, die Sie durch die Füllzeichen zwischen den doppelten Doppelpunkten und dem abschließenden Dollarzeichen definiert haben. Nach Ersetzung ist die Breite der Felder völlig unverändert – die kurzen Werte für Rev und Author sind mit Leerzeichen aufgefüllt und das lange Feld Date wird mit einem Nummernzeichen abgeschnitten:

$Rev:: 13            $:  Revision der letzten Übertragung
$Author:: harry      $:  Autor der letzten Übertragung
$Date:: 2006-03-15 0#$:  Datum der letzten Übertragung

Die Verwendung von Schlüsselworten fester Länge ist besonders praktisch, wenn Ersetzungen in komplexe Dateiformate vorgenommen werden sollen, die ihrerseits Felder fester Länge für Daten verwenden oder deren Größe für ein Datenfeld sich außerhalb der Anwendung nur sehr schwer ändern lässt. Was natürlich binäre Formate angeht, müssen Sie stets große Sorgfalt walten lassen, damit irgendeine Schlüsselwortersetzung, fester Länge oder sonst wie, die Integrität des Formates nicht verletzt. Obwohl das ziemlich einfach klingt, kann das für die meisten heutzutage verwendeten binären Dateiformate eine überraschend schwierige Aufgabe sein, und nichts, was sich Mutlose antun sollten.

Warnung

Denken Sie daran, dass die Möglichkeit besteht, dass aus Multibyte-Zeichen bestehende Werte korrumpiert werden können, da die Breite eines Schlüsselwort-Feldes in Bytes gemessen wird. Ein Benutzername, der einige Multibyte-UTF-8-Zeichen enthält könnte mitten in einer Zeichenfolge abgeschnitten werden, die eines dieser Zeichen repräsentiert. Auf Byte-Ebene handelt es sich dabei bloß um eine Kürzung, ein UTF-8-Text wird jedoch wahrscheinlich als Zeichenkette mit einem falschen oder missratenen letzten Zeichen wiedergegeben. Es ist denkbar, dass bestimmte Anwendungen beim Versuch, die Datei zu laden, den fehlerhaften UTF-8-Text erkennen, die gesamte Datei als fehlerhaft einstufen und deren Bearbeitung vollständig verweigern. Falls Sie also Schlüsselworte auf eine feste Länge beschränken, sollten Sie eine Größe wählen, die diese Art der Ersetzung berücksichtigt.