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 Versionskontrollsystem 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
$
.
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 – bestimmte
Schlüsselworte werden 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 fünf Schlüsselworte, von denen einige Aliasnamen besitzen, die Sie auch verwenden können.
Date
Dieses Schlüsselwort beschreibt den letzten bekannten
Zeitpunkt einer Änderung dieser Datei im Projektarchiv und
hat das Format $Date: 2006-07-22 21:42:37 -0700
(Sat, 22 Jul 2006) $
. Es kann auch als
LastChangedDate
angegeben werden.
Anders als das Schlüsselwort Id
, das
UTC verwendet, zeigt das Schlüsselwort
Date
Zeitpunkte in der örtlichen
Zeitzone an.
Revision
Dieses Schlüsselwort beschreibt die letzte bekannte
Revision einer Änderung dieser Datei im Projektarchiv und
sieht etwa so aus: $Revision: 144 $
. Es
kann auch als LastChangedRevision
oder
Rev
angegeben werden.
Author
Dieses Schlüsselwort beschreibt den letzten bekannten
Autor einer Änderung dieser Datei im Projektarchiv und sieht
etwa so aus: $Author: harry $
. Es kann
auch als LastChangedBy
angegeben
werden.
HeadURL
Dieses Schlüsselwort beschreibt den vollständigen URL
zur letzten Version der Datei im Projektarchiv und sieht
etwa so aus: $HeadURL:
http://svn.collab.net/repos/trunk/README $
.
Es kann zu URL
abgekürzt werden.
Id
Dieses Schlüsselwort ist eine komprimierte Kombination
aus den anderen Schlüsselworten. Seine Ersetzung sieht
etwa so aus: $Id: calc.c 148 2006-07-28 21:30:43Z
sally $
, und sie bedeutet, dass die Datei
calc.c
zuletzt in Revision 148 am
Abend des 28. Juli 2006 von sally
geändert wurde. Der angegebene Zeitpunkt ist in UTC,
anders als beim Schlüsselwort Date
(das
die örtliche Zeitzone verwendet).
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.
Einfach einen Schlüsselwort-Anker in Ihre Datei einzufügen, bewirkt nichts. Subversion wird niemals versuchen, eine Textersetzung in Ihren Dateiinhalten vorzunehmen, falls Sie es nicht ausdrücklich dazu auffordern. Schließlich könnten Sie ja ein Dokument [13] über die Verwendung von Schlüsselworten schreiben und deshalb nicht wollen, dass Subversion Ihre schönen Beispiele nicht ersetzter Schlüsselwort-Anker 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 (Sat, 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.
Subversion 1.2 führte eine neue Variante der
Schlüsselwort-Syntax ein, die eine zusätzliche nützliche
– wenn auch vielleicht atypische – Funktionsweise
mitbrachte. Sie können Subversion nun 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 (Wed, 15 Mar 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 (etwa für Dokumente in Microsoft Office ).
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. |