Erstellen von Patches

Das Erstellen von Patches – Dateien, die Unterschiede zwischen anderen Dateien enthalten – ist die Hauptaufgabe von Vergleichsprogrammen. Es gibt viele Programme mit dieser Funktionalität; manche als eigenständiges Programm (diff), manche integriert in Entwicklungsumgebungen (Eclipse, XCode) oder Versionsverwaltungssystemen (cvs). Diff kann auf den meisten *nix Systemen gefunden werden. Es ist ebenfalls in den freien XCode Developers Tools für Mac verfügbar und ist in UnxUtils und Cygwin für Windows integriert.

Diese Seite behandelt nur ein paar grundlegende Prinzipien der Verwendung des Kommandozeilenprogramms diff (und des ihm verwandten cvs diff). Es gibt auch ein kurzes Video-Tutorial, Rolling Patches in Drupal (englisch). Auf der Seite Submitting Patches (englisch) sind Richtlinien zum Einstellen von Patches in die Fehlerverfolgung (issue tracker) zu finden.
Um ...

CVS diff vs. diff

Diff vergleicht zwei Dateien. Der Befehl cvs diff vergleicht eine lokal bearbeitete Datei mit der Version im CVS Repository, wenn die veränderte Datei aus dem CVS ausgechecked wurde. Der reguläre diff Befehl vergleicht zwei lokale Dateien (das Original und die veränderte Version) um einen Patch zu erstellen. Dieser Befehl kann verwendet werden, wenn keine Verbindung zum Internet besteht oder CVS auf dem Computer nicht eingerichtet ist (mehr Informationen zu CVS gibt es im Handbuch zu CVS (englisch)). Beide Befehle werden mit den gleichen Optionen verwendet und erzeugen benutzbare Patches.

Verzeichnis überprüfen

Der wichtigste Punkt um sicherzustellen, dass ein Patch verwendbar ist, ist dass der diff-Befehl in dem Verzeichnis innerhalb der Drupal Struktur ausgeführt wird, wo Dateien verändert (gepatched) werden. Idealerweise sollte diff im Drupal Stammverzeichnis (enthält index.php, cron.php, etc.) ausgeführt werden. Wenn Drupal beispielsweise auf localhost in einem Verzeichnis namens drupaltest (z.B. /www/htdocs/drupaltest) installiert ist, sollte in das Verzeichnis drupaltest gewechselt werden, bevor diff ausgeführt wird. Diff kann auch ausserhalb der Drupal Verzeichnisstruktur ausgeführt und ein Patch erstellt werden. Jedoch wird dieser Patch nicht für andere Personen anwendbar sein, da sie nicht die gleiche Verzeichnisstruktur haben werden. Patches für den Drupal Kern müssen immer ausgehend vom Drupal Stammverzeichnis erstellt werden.

Bei der Erstellung von Patches von Nicht-Kern Modulen/Themes sollte im Gegensatz zur Erstellung von Kern-Patches bedacht werden, dass nicht jeder sein Module in die gleiche Struktur ablegt. Aus diesem Grund sollte in diesem Fall diff innerhalb des Modul-/Themeverzeichnisses ausgeführt werden, anstatt im Drupal Stammverzeichnis.

Lesbarkeit

Die Lesbarkeit von Patches ist sehr wichtig für den Review Prozess. Ein Patch bei dem dies nicht bedacht wurde, wird wahrscheinlich zurückgewiesen werden. Die beiden besten Optionen um eine gute Lesbarkeit zu erreichen, sind die Option -u für eine vereinheitlichte Formatierung und -p um die Funktion, in der die Änderung gemacht wurde, zu zeigen.

Änderungen und Leerzeichen trennen

Jede logische Änderung sollte in einen eigenständigen Patch einfliessen. Wenn eine Änderung beispielsweise die Behebung von Fehlern und Verbesserungen der Performance beinhaltet, sollte dies in zwei oder mehr separate Patches aufgeteilt werden. Genauso sollten Änderungen bzgl. Code Stil und Leerzeichen in einen eigenen Patch gebracht werden und nicht mit funktionalen Änderungen vermischt werden. Beim Thema Leerzeichen sollte auch beachtet werden, dass bei der Verwendung von Editoren, die Leerzeichen automatisch entfernen, diese Option bei der Erstellung von Patches ausgeschaltet werden sollte, da sonst ohne Absicht ein Patch erstellt wird, der unlesbar wird.

Zeilenumbrüche und Verzeichnistrennzeichen

Es sollten Unix Zeilenumbrüche (LF) und Verzeichnistennzeichen (/) verwendet werden. Zeilenumbrüche können manuell mit vielen Texteditoren oder mit Hilfe eines dos2unix Programms umgewandelt werden.

Der Befehl

Der grundsätzliche Befehl, der zu verwenden ist, ist:
cvs diff -up original.php > dateiname.patch
oder
diff -up original.php neu.php > dateiname.patch

Das Symbol > leitet die Ausgabe des Befehls in die Datei dateiname.patch um. Es ist sinnvoll, den Patch so zu benennen, dass man anhand des Namens den Grund des Patches erkennen kann, z.B. modulename_code_cleanup.patch. Wenn > dateiname.patch nicht mit dem Befehl aufgerufen wird, werden die Änderungen auf der Standardausgabe des Systems ausgegeben (in den meisten Fällen der Monitor). Auf diesem Weg lässt sich schon vorab überprüfen, wie der Patch aussieht. Der Patch kann natürlich auch an einem anderen Ort, wie z.B. dem Desktop oder einem anderen Verzeichnis, erstellt werden. Dies wird erreicht, indem einfach der Pfad dem Dateinamen vorangestellt wird, z.B. /Pfad/zum/Desktop/dateiname.patch.

Wenn mehrere Dateien geändert wurden, kann die Fähigkeit von diff zum Vergleich von Verzeichnissen verwendet werden. Dazu muss die Option -R (gross geschrieben) an cvs diff und -r (klein geschrieben) an diff angehängt werden, damit der entsprechende Befehl das Verzeichnis (inkl. der Unterverzeichnisse) durchläuft. Um Dateien im Stammverzeichnis zu vergleichen, kann einfach in das Verzeichnis gewechselt werden und anstelle des Verzeichnisnamens ein Punkt (.) verwendet werden.

cvs diff -uRp verzeichnis > dateiname.patch
oder
diff -urp original_verzeichnis neues_verzeichnis > dateiname.patch

Dateien hinzufügen/entfernen

Für neue oder entfernte Dateien wird die Option -N verwendet.

Hinzufügen

Wenn die Option -N zur Markierung neuer Dateien verwendet wird, muss zusätzlich ein Eintrag in die Datei CVS/Entries des Verzeichnisses geschrieben werden. Zum Beispiel wenn eine Datei namens neueDatei.inc im Verzeichnis modules/system erstellt wurde, muss eine Zeile zur Datei modules/system/CVS/Entries hinzugefügt werden:

/admin.css/1.12/Tue Jan 16 23:15:28 2007//
/defaults.css/1.2/Fri Aug 25 09:01:12 2006//
/system.css/1.22/Wed Feb 7 03:46:21 2007//
/system.info/1.3/Tue Nov 21 20:55:35 2006//
/system.install/1.79/Fri Feb 16 16:39:46 2007//
/system.js/1.1/Thu Feb 22 16:33:29 2007//
/system.module/1.451/Thu Feb 22 16:33:29 2007//
/neueDatei.inc/0/Neue Datei//

Wenn mit mit einem Tag markierten Versionen gearbeitet wird, endet die Zeile mit dem Tag. Die anderen Einträge in der Datei können dabei als Vorlage verwendet werden:

/neueDatei.inc/0/Neue Datei//TDRUPAL-5

In diesem Beispiel ist der Text "Neue Datei" frei wählbar, jedoch die 0 muss als Dateiversion angegeben werden, um die Datei als neu zu markieren. Sobald die Zeile hinzugefügt wurde, berücksichtigt cvs diff -Nup sie für den Vergleich.

Dateien entfernen

Wird die Option -N zur Markierung entfernter Dateien verwendet, muss der entsprechende Eintrag in der Datei CVS/Entries des Verzeichnisses geändert werden. Wenn beispielsweise die Datei system.module ans dem Verzeichnis modules/system entfernt werden soll, muss die entsprechende Zeile in modules/system/CVS/Entries geändert werden:

/admin.css/1.12/Tue Jan 16 23:15:28 2007//
/defaults.css/1.2/Fri Aug 25 09:01:12 2006//
/system.css/1.22/Wed Feb 7 03:46:21 2007//
/system.info/1.3/Tue Nov 21 20:55:35 2006//
/system.install/1.79/Fri Feb 16 16:39:46 2007//
/system.js/1.1/Thu Feb 22 16:33:29 2007//
/system.module/-1.451/Thu Feb 22 16:33:29 2007//

Mehr ist nicht nötig. Einfach ein - zur Version hinzufügen, so dass aus 1.451 -1.451 wird. Dies funktioniert jedoch nur für Dateien, nicht für Verzeichnisse.
Der Befehl zum entfernen lautet dann:
cvs diff -upN verzeichnis > dateiname.patch
oder
diff -upN original_verzeichnis neues_verzeichnis > dateiname.patch

Ein Beispiel zur Verwendung von cvs diff

1. Sicherstellen, dass die letzte CVS Version der Datei/-en ausgechecked wurde, bevor Änderungen gemacht werden: in das Drupal Stammverzeichnis wechseln (cd) und den Befehl zur Aktualisierung ausführen: cvs update -dP.
2. Die Änderungen an den Dateien vornehmen.
3. Wenn der Patch erstellt werden kann, wieder in das Stammverzeichnis von Drupal wechseln.
4. Den Befehl cvs diff -up Pfad/zur/Datei/beispiel.module > patchname.patch ausführen. Dies erstellt einen neuen Patch im Stammverzeichnis von Drupal, der nun an einen Fehlerbericht oder Featurewunsch angehängt werden kann.

Ein Beispiel zur Verwendung von diff

1. Sicherstellen, dass die letzte Version der Datei/-en verfügbar ist (entweder durch Herunterladen der letzten gepackten Datei von drupal.org oder mittels Aktualisierung durch CVS).
2. Eine Arbeitskopie von jeder zu bearbeitenden Datei erstellen (z.B. system.module nach systemNeu.module kopieren).
3. Die Änderungen an den Dateien vornehmen.
4. Wenn der Patch erstellt werden kann, eine Kommandozeile öffnen und in das Stammverzeichnis von Drupal wechseln (cd).
5. Den Befehl diff -up Pfad/zur/Datei/system.module Pfad/zur/Datei/systemNeu.module > patchname.patch ausführen. Dies erstellt einen neuen Patch im Stammverzeichnis von Drupal, der nun an einen Fehlerbericht oder Featurewunsch angehängt werden kann.