Mercurial (hg) ist ein verteiltes Versionskontrollsystem (DVCS, Distributed/Decentralized Version Control System).
Der folgende Text ist kein vollständigesTutorial zu Mercurial und beschreibt auch nicht die Möglichkeiten von Mercurial. Stattdessen werden nur erste Schritte und Installationshinweise beschrieben.
Bei zentralen Versionskontrollsystemen (wie z.B. CVS und Subversion) gibt es einen zentralen Server mit einem zentralen Repository, welches die Softwaremodule enthält. Die Teammitarbeiter können sich Revisions im Sinne von Snapshots holen ("auschecken"), daran arbeiten und geänderte Dateien entweder einzeln oder alle zurückspeichern ("einchecken").
Bei verteilten Versionskontrollsystemen (DVCS, Distributed/Decentralized Version Control System) (wie z.B. Mercurial und Git) kann es wahlweise ein zentrales Repository geben, muss es aber nicht. Jeder kann sehr einfach ein eigenes Repository starten und nach Belieben das gesamte Repository oder "Changesets" an andere weitergeben.
In Firmen wird meistens trotz verteilter Versionskontrollsysteme zusätzlich ein zentraler Server für Repositories verwendet, damit Mitarbeiter leichter Projektsourcen austauschen können und damit ausgelieferte Versionen leichter wiedergefunden werden können. Aber auch in diesem Fall gibt es gravierende Unterschiede zu zentralen Versionskontrollsystemen.
Während bei zentralen Versionskontrollsystemen Snapshots ausgecheckt werden, wird bei verteilten Versionskontrollsystemen das gesamte Repository auf den lokalen PC kopiert ("clone"). Somit befindet sich nicht nur der aktuelle Zustand auf dem lokalen PC, sondern auch die gesamte Vorgeschichte.
Sollen Sourcen bearbeitet werden, werden diese aus dem lokalen Repository in die Arbeitsverzeichnisse mit den Sourcen im lokalen Workspace kopiert. Nach der Bearbeitung werden sie mit dem commit-Kommando ins lokale Repository gespeichert. Damit sind sie aber noch nicht für andere Teammitglieder sichtbar. Erst ein push-Kommando transferiert die Änderungen (als "Changeset") zu einem anderen Repository, und erst dann sind sie für andere Mitarbeiter sichtbar.
Da bei verteilten Versionskontrollsystemen viele Kommandos das gesamte Repository betreffen, wird normalerweise nicht ein einziges großes Repository für alle Module verwendet, sondern mehrere Repositories, zum Beispiel pro Modul oder pro Multimodulprojekt eins. Weiteres hierzu wird weiter unten erläutert.
Für jemanden, der CVS oder Subversion gewöhnt ist, ist die Umstellung auf ein verteiltes Versionskontrollsystemen nicht so einfach. Alte Denkmuster müssen abgelegt und durch neue Vorgehensweisen ersetzt werden.
Einige wichtige Vorteile sind:
Einige mögliche Nachteile könnten sein:
Zu Mercurial finden Sie viel Doku und viele Tutorials im Internet. Zum Start eignen sich:
http://hginit.com
http://mercurial.selenic.com/learn
http://mercurial.selenic.com/wiki/QuickReferenceCardsAndCheatSheets
http://www.selenic.com/mercurial/hg.1.html
http://mercurial.selenic.com/wiki/FAQ
http://hgbook.red-bean.com
Bei CVS und Subversion wird oft ein einziges Repository für alle Module eines Projekts oder sogar für alle Module aller Projekte eingesetzt. Bei Mercurial wäre dies sehr ungünstig, da viele Kommandos defaultmäßig das gesamte Repository betreffen. Deshalb wird bei Mercurial zumindest pro Projekt und meistens sogar pro Projektmodul (oder Multimodulprojekt) ein eigenes Repository verwendet. Im Folgenden wird von Letzterem ausgegangen. Im Falle von Maven-Projekten bedeutet dies: Pro Maven-Modul (= pro "pom.xml") oder pro Maven-Multimodulprojekt wird ein eigenes Mercurial-Repository verwendet. Die zu einem Projekt gehörenden Module/Repositories liegen auf dem lokalen Arbeits-PC im selben Workspace-Verzeichnis, und falls es einen zentralen Mercurial-Webserver gibt, sind sie dort alle über eine gemeinsame URL erreichbar. Weiter unten finden Sie Hinweise, wie mehrere Projekte innerhalb eines zentralen Mercurial-Webservers strukturiert werden können.
Es gibt unterschiedliche Möglichkeiten zur Strukturierung der Repositories, zum Beispiel ohne oder mit "zentralem Repository", oder sogar mit mehreren "zentralen Repositories", etwa "Dev" für Entwicklung und "Stable" für die Auslieferungen. Eine mögliche Repo-Struktur zeigt folgende Grafik:
Bitte beachten Sie die unterschiedlichen Wirkungsbereiche der hg-Kommandos.
"hg update" und "hg commit":
Wie obige Grafik zeigt, wirken diese Kommandos nur auf der lokalen Festplatte. Andere Mitarbeiter sind nicht tangiert.
"hg clone", "hg pull" und "hg push":
Diese Kommandos tauschen "Changesets" aus, zwischen dem lokalen Repository und einem anderen Repository (meistens "remote", also ein anderer PC oder ein Server).
Bitte beachten Sie, dass die letzten Kommandos nur in das jeweilige Repository kopieren, aber nicht die Dateien in den Arbeitsverzeichnissen mit den Sourcen im Workspace ändern, weshalb nach einem "pull" ins lokale Repository ein "merge" oder "update" folgen muss.
Damit nicht unnötige Build-Artefakte (z.B. *.class-Dateien) ins Repository übernommen werden, sollten Sie in jedem Repository bevor Sie das erste Mal "hg commit" aufrufen eine .hgignore-Datei anlegen mit beispielsweise folgendem Inhalt:
syntax: glob .settings CVS logs target *.classpath *.cvsignore *.project Thumbs.db thumbs.db
Siehe: http://www.selenic.com/mercurial/hgignore.5.html.
Die gewünschte Mercurial-Version downloaden von http://mercurial.selenic.com/downloads (z.B. Mercurial-2.3.2-x64.exe).
Die Mercurial-Installationsdatei ausführen und Mercurial zum Beispiel nach C:\Programme\Mercurial installieren.
Editieren Sie nicht die Mercurial.ini (bzw. hgrc) im Mercurial-Installationsverzeichnis (z.B. C:\Programme\Mercurial). Stattdessen kopieren Sie diese Datei nach %USERPROFILE% (C:\Users\%USERNAME% bzw. C:\Dokumente und Einstellungen\%USERNAME%):
copy "C:\Programme\Mercurial\Mercurial.ini" "%USERPROFILE%"
Die kopierte Mercurial.ini (bzw. hgrc) editieren: In der Rubrik [ui] das Semikolon vor "username = ..." entfernen und Name und E-Mail-Adresse eintragen, sowie einen Texteditor eintragen, zum Beispiel so:
[ui] username = Vorname Nachname <Meine@Email.Adresse> editor = Notepad
Siehe auch: http://www.selenic.com/mercurial/hgrc.5.html#ui.
Falls Sie einen Webserver für Mercurial-Repositories ansprechen wollen, können Sie die Zugangsdaten in die kopierte Mercurial.ini (bzw. hgrc) eintragen, beispielsweise so (bitte Einträge anpassen):
[auth] meinhgwebserver.prefix = http://meinhgwebserver:4419/hgweb/cgi-bin/ meinhgwebserver.username = MeinName meinhgwebserver.password = geheim1
Bitte beachten Sie, dass so das Passwort unverschlüsselt hinterlegt ist. Es gibt auch andere Verfahren mit besserer Sicherheit.
Siehe auch: http://www.selenic.com/mercurial/hgrc.5.html#auth.
hg muss im Kommandozeilenfenster funktionieren:
cd \
hg version
hg
hg help
Auch wenn Sie später Mercurial nur über grafische Oberflächen
(z.B. MercurialEclipse-Plugin) bedienen wollen,
sollten Sie die ersten Schritte per Kommandozeile durchführen, um ein besseres Verständnis aufzubauen.
Die folgende Liste kann allerdings lediglich als Erinnerungsstütze verwendet werden.
Sie finden wesentlich bessere Einsteigertutorials im Internet, zum Beispiel
http://hginit.com.
Sehen Sie sich zu allen im Folgenden genannten "hg ..."-Kommandos die Kurzhilfe an, zum Beispiel so:
hg help glossary
hg help clone
hg help init
hg help add
hg help commit
Ähnliche Hilfstexte finden Sie auch unter: http://www.selenic.com/mercurial/hg.1.html.
Legen Sie auf diesem Server ein neues Modul-Repository an, zum Beispiel so (passen Sie Pfade, Modulnamen, Server-URL etc. an):
cd /D D:\Tools\hgweb-repos
hg init modulabcxyz
cd modulabcxyz
echo [web] > .hg\hgrc
echo description = Modul Abc Xyz >> .hg\hgrc
echo contact = Mein Name ^<Meine@Email.Adresse^> >> .hg\hgrc
type .hg\hgrc
start http://<hgweb-server>:4419/hgweb/cgi-bin/meinprojekt.cgi
Anschließend wechseln Sie auf Ihren lokalen Arbeits-PC und "clonen" das Remote-Modul-Repository:
md \MeinWorkspace
cd \MeinWorkspace
hg clone http://<hgweb-server>:4419/hgweb/cgi-bin/meinprojekt.cgi/modulabcxyz
cd modulabcxyz
hg paths
type .hg\hgrc
Dann legen Sie ein neues Mercurial-Repository für das neue Modul lokal an:
md \MeinWorkspace
cd \MeinWorkspace
hg init modulabcxyz
cd modulabcxyz
.hgignore anlegen:
Falls es im lokalen modulabcxyz-Verzeichnis noch keine .hgignore-Datei gibt, legen Sie diese an wie oben gezeigt.
Eine erste Datei erzeugen, dem lokalen Repository hinzufügen, committen und log ansehen:
echo Hallo Abc Xyz > HalloAbcXyz.txt
hg add
hg commit -m "HalloAbcXyz.txt hinzugefuegt"
hg log
tree /F
Ihr Modulverzeichnis sieht jetzt so aus:
[\MeinWorkspace] (Workspace für Softwaremodule, z.B. Eclipse-Projekte-Workspace)
'- [modulabcxyz] (Modulverzeichnis)
|- [.hg] (Modul-Repository-Daten)
| '- ...
|- .hgignore
|- HalloAbcXyz.txt (Sourcen im Modularbeitsverzeichnis)
'- ...
Erste Datei ändern, zwei Dateien hinzufügen, Status ansehen und committen:
echo Hallo-Ergaenzung >> HalloAbcXyz.txt
echo Zweites Hallo > Hallo2.txt
echo Drittes Hallo > Hallo3.txt
hg status
hg add
hg status
hg commit -m "HalloAbcXyz.txt geaendert sowie Hallo2.txt und Hallo3.txt hinzugefuegt"
hg status
hg log
Differenz anzeigen:
hg diff -r 0
hg diff -r 0:1 HalloAbcXyz.txt
hg diff -c 1
hg cat -r 0 HalloAbcXyz.txt
hg cat HalloAbcXyz.txt
Falls Datei gelöscht wird, dies per "hg remove" auch Mercurial mitteilen:
del Hallo3.txt
hg status
hg remove Hallo3.txt
hg status
hg commit -m "Hallo3.txt geloescht"
hg status
hg log
Alte Version wiederherstellen und wieder zurück zur neuesten Version:
hg update -r 0
type HalloAbcXyz.txt
hg update
type HalloAbcXyz.txt
Falls das Modul aus einem Remote-Repository kopiert wurde, können die Änderungen dorthin übertragen werden:
type .hg\hgrc
hg outgoing
hg push
start http://<hgweb-server>:4419/hgweb/cgi-bin/meinprojekt.cgi/modulabcxyz
Falls das Modul aus einem Remote-Repository kopiert wurde, und ein anderes Teammitglied Änderungen dorthin übertragen hat, müssen Sie diese zuerst abholen ("pull") und dann entweder "updaten" oder "mergen" (= zusammenführen), bevor Sie push ausführen:
hg incoming
hg pull
hg heads
hg merge
hg commit -m "merge"
hg outgoing
hg push
Jeder Changeset kann durch seine 12-stellige hexadezimale Changeset-ID eindeutig identifiziert werden, weshalb "Tags" nicht zwingend benötigt werden. Aber falls Sie "sprechendere Bezeichnungen" wünschen, können Sie auch Tags setzen:
hg tag Version-1.0
hg tags
hg log -l 3
Falls Sie die Mercurial-Changeset-ID in Skripten benötigen, sehen Sie sich die identify- und tip-Kommandos und den template-Parameter an und testen Sie folgende Kommandos:
hg id -i
hg tip --template "{node|short}\n{node}\n{date|isodate}\n"
Falls Sie die Mercurial-Changeset-ID in Maven-POMs verwenden wollen, beispielsweise um sie der META-INF/MANIFEST.MF hinzuzufügen, sehen Sie sich das buildnumber-maven-plugin mit dem hgchangeset-Goal und das Programmierbeispiel Maven-Webapp mit Properties im Manifest an.
Sie können nicht nur von einem Remote-Server "clonen", sondern auch auf Ihrer Festplatte, zum Beispiel für temporäre lokale Experimentier-Branches:
cd \MeinWorkspace
hg clone modulabcxyz modulabcxyzbranch
cd modulabcxyzbranch
Sollen Branches dauerhaft verwendet werden (z.B. für "stable" und "dev"), dann können "named Branches" angelegt werden:
| hg branch MeinNeuerBranch | [neuen Branch anlegen] | |
| hg commit -m "Neuer Branch" | [commit des neuen Branches] | |
| hg heads | ["Heads" anzeigen] | |
| hg branches -c | [alle Branches anzeigen] | |
| hg branch | [aktuell verwendeten Branch anzeigen] | |
| hg push -b . --new-branch | [push des neuen Branches] | |
| hg push -b . | [push zum aktuell verwendeten Branch] | |
| hg pull | [pull aller Branches] | |
| hg update MeinNeuerBranch | [umschalten auf den genannten Branch] | |
| hg commit --close-branch -m "Branch beenden" | [Branch beenden] |
Bevor Sie branchen, sollten Sie sich die verschiedenen Strategien hierzu ansehen, zum Beispiel "Branching with Clones", "Branching with Bookmarks", "Branching with Named Branches" und "Branching Anonymously", etwa wie beschrieben unter http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial.
Falls Sie Änderungen aus einem Branch in einen anderen Branch übertragen wollen, sehen Sie sich das graft-Kommando an ("Cherry-Picking").
Falls Sie mit Eclipse arbeiten, sollten Sie das MercurialEclipse-Plugin installieren, siehe: http://marketplace.eclipse.org/content/mercurialeclipse (oder http://www.javaforge.com/project/HGE).
Zur Installation tragen Sie in Eclipse unter "Help" | "Install new Software..." ein:
http://mercurialeclipse.eclipselabs.org.codespot.com/hg.wiki/update_site/stable
oder
http://cbes.javaforge.com/update
Je nach Installationsquelle haben Sie die Wahl, ob Sie nur das MercurialEclipse-Plugin oder zusätzlich auch die "Windows Binaries for Mercurial" installieren wollen. Die "Windows Binaries for Mercurial" benötigen Sie nur, wenn Sie nicht bereits Mercurial installiert haben und auch nicht installieren wollen (siehe oben Lokale Mercurial-Installation).
Falls Sie zusätzlich zu "MercurialEclipse" auch die "Windows Binaries for Mercurial" installiert haben,
können Sie das Ergebnis so überprüfen (bitte Pfad anpassen):
cd \Tools\Eclipse\plugins\com.intland.hgbinary.win32_2.3.2\os\win32
hg debuginstall
Bevor Sie Sourcen aus einem Mercurial-Repository kopieren, sollten Sie Ihre Encoding-Einstellung in Eclipse überprüfen:
Window | Preferences | General | Workspace: "Text file encoding".
Eventuell müssen Sie auf UTF-8 umstellen.
Folgendermaßen kopieren Sie ein Mercurial-Repository in Eclipse:
File | New | Project... | Mercurial | Clone Existing Mercurial Repository | Next.
URL: http://<hgweb-server-host>:4419/hgweb/cgi-bin/meinprojekt.cgi/modulabcxyz
Next | Next | Finish.
Falls Sie Probleme mit der Verbindung zum hgweb-Server haben
und in Eclipse einen Proxy konfiguriert haben
(z.B. Cntlm),
müssen Sie eventuell den Proxy für den hgweb-Server umgehen:
Window | Preferences | General | Network Connections | Proxy bypass: <hgweb-server-host>
Wenn Sie in Eclipse im Project Explorer (oder Package Explorer) mit der rechten Maustaste auf ein Modul aus einem Mercurial-Repository klicken, finden Sie unter "Team" die üblichen Mercurial-Kommandos (Commit, Push, Pull, Update, Merge etc.).
Kontrollieren Sie die Mercurial-Parameter:
a) In Eclipse unter: Window | Preferences | Team | Mercurial (insbesondere den Pfad zum "Mercurial Executable" hg.exe).
b) Im Eclipse Package Explorer das Projekt markieren | rechte Maustaste | Properties | Mercurial.
Sehen Sie sich die in Eclipse verwendeten Mercurial-Repositories an über:
Window | Show View | Mercurial Repositories.
Falls Sie bei der Installation auf Probleme stoßen (z.B. wegen Proxy- oder Webwasher-Problemen), sehen Sie sich an: Plug-in-Installation ohne Internet.
Falls Sie Maven-Multimodulprojekte in Eclipse bearbeiten wollen, sehen Sie sich unbedingt an: maven-multiproj.htm#Maven-Multimodulprojekt-in-Eclipse.
Damit ein Mitarbeiter Änderungen per Mercurial-Changeset zu einem anderen Mitarbeiter übertragen kann, ohne die Änderungen zu einem "zentralen Repository" übertragen zu müssen, enthält Mercurial einen kleinen Mini-Webserver. Sehen Sie sich den Hilfstext hierzu an:
hg -v help serve
Mitarbeiter A ruft auf seinem PC in seinem Mercurial-Arbeits-Repository-Verzeichnis auf (wählen Sie eine geeignete Portnummer und passen Sie Pfade, Modulnamen und URL an):
cd \MeinWorkspace\modulabcxyz
hg serve -p 4423
start http://<PCvonA>:4423
Dann kann Mitarbeiter B von seinem PC aus das komplette Repository von A kopieren:
cd \MeinWorkspace
hg clone http://<PCvonA>:4423 modulabcxyz
Oder Mitarbeiter B überträgt Changesets vom Mitarbeiter A in sein Mercurial-Arbeits-Repository:
cd \MeinWorkspace\modulabcxyz
hg pull http://<PCvonA>:4423
hg update
Normalerweise werden nur Leserechte benötigt, da nur per "hg pull" "abgeholt" wird.
Falls Sie auch "hg push" erlauben wollen, führen Sie aus:
hg serve --config web.allow_push=* --config web.push_ssl=False -p 4423
Aber beachten Sie dabei bitte:
a) Jeder kann so beliebig auf Ihren PC pushen!
b) Falls die gepushten Änderungen nicht nur im Repository, sondern auch in den Arbeitsverzeichnissen mit den Sourcen im Workspace landen sollen, müssen Sie nach dem Remote-push auf dem hg-serve-PC "hg update" aufrufen. Falls Sie dies automatisieren wollen, siehe: 'hg push' and automatic 'hg update'.
Ein hgweb-Webserver für Mercurial-Repositories sollte normalerweise unter Linux und mit dem Apache-Webserver eingerichtet werden. Hierzu finden Sie ausführliche Doku auf der Mercurial-Webseite.
Für kleine Teams kann es eventuell einfacher sein, einen möglicherweise bereits vorhandenen Teamserver unter Windows zu verwenden. Dies wird im Folgenden beschrieben, für Windows 7, 64 Bit, und Tomcat 7.
Die hier beschriebene Konfiguration berücksichtigt keine Sicherheitsaspekte und ist deshalb nur innerhalb geschützter Intranets verwendbar.
Weitere Hinweise finden Sie unter http://mercurial.selenic.com/wiki/PublishingRepositories.
Nachsehen, welche Python-Version für Ihre Mercurial/hgweb-Version benötigt wird (im Beispiel Python 2.6):
Entweder auf http://mercurial.selenic.com/downloads
z.B. unter
"Mercurial 2.0 Python 2.6 package - x64 Windows",
oder auf http://mercurial.selenic.com/wiki/Download#Windows
z.B. unter
"Mercurial-2.0 (32-bit py2.6) / Mercurial-2.0 (64-bit py2.6), installs Mercurial source as Python modules and
thus requires Python 2.6 installed.
This is recommended for hgweb setups and extensions with non-standard dependencies",
oder unter
http://mercurial.selenic.com/release/windows.
Die entsprechende Python-Installationsdatei downloaden (z.B. "Windows X86-64 MSI Installer (2.6.6)", python-2.6.6.amd64.msi, von http://www.python.org/download/releases/2.6.6).
Python installieren, z.B. nach C:\Programme\Python26.
Der Python-Pfad braucht nicht dem Windows-Such-PATH hinzugefügt werden.
Python testen:
cd /D C:\Programme\Python26
python -V
python -h
Von http://mercurial.selenic.com/downloads, von http://mercurial.selenic.com/wiki/Download#Windows oder von http://mercurial.selenic.com/release/windows das "Mercurial Python package (recommended for hgweb setups)" downloaden, zum Beispiel "Mercurial 2.0 Python 2.6 package - x64 Windows" (mercurial-2.0.win-amd64-py2.6.exe).
Führen Sie die Mercurial-Installationsdatei mit Administratorrechten aus (rechte Maustaste auf Installationsdatei und "Als Administrator ausführen"). Die Mercurial-Installation findet das installierte Python und fügt die Mercurial-Dateien im Python-Installationsverzeichnis hinzu, hauptsächlich in {Python26}\Lib\site-packages.
Falls Sie Mercurial nicht ausschließlich im hgweb-Webserver, sondern auch über die Kommandozeile verwenden wollen, fügen Sie das {Python26}\Scripts-Verzeichnis (z.B. C:\Programme\Python26\Scripts) dem Windows-Such-PATH hinzu (es enthält die Batchdatei hg.bat).
Erstellen Sie im %USERPROFILE%-Verzeichnis (C:\Users\%USERNAME% bzw. C:\Dokumente und Einstellungen\%USERNAME%) die Textdatei Mercurial.ini (bzw. hgrc):
[ui] username = hgweb-Server editor = Notepad [web] allow_archive = zip allow_push = * push_ssl = false
Genaueres erfahren Sie unter http://www.selenic.com/mercurial/hgrc.5.html.
Bitte beachten Sie, dass diese Konfiguration keine Sicherheit bietet und so nur in geschützten Intranets verwendet werden darf.
Falls Sie in Ihrem Webserver Authentication einrichten können, sollten Sie "allow_push = *" durch "allow_push = MeinName, AndererName" ersetzen.
Testen Sie hg im Kommandozeilenfenster:
cd /D C:\Programme\Python26\Scripts
hg version
hg
Um zwei erste simple Test-Repos mit Mercurial anzulegen, erzeugen Sie eine Batchdatei erstelle-test-hg-repos.bat mit folgendem Inhalt und führen sie aus:
@pushd . set HG=C:\Programme\Python26\Scripts\hg.bat @set REPOS_DIR=%1 @if "%REPOS_DIR%" == "" set REPOS_DIR=D:\Tools\hgweb-repos md "%REPOS_DIR%" cd /D "%REPOS_DIR%" call %HG% init modulabc @echo on call %HG% init modulxyz @echo on echo [web] > modulabc\.hg\hgrc echo description = Modul Abc >> modulabc\.hg\hgrc echo contact = Mein Name ^<Meine@Email.Adresse^> >> modulabc\.hg\hgrc echo [web] > modulxyz\.hg\hgrc echo description = Modul Xyz >> modulxyz\.hg\hgrc echo contact = Mein Name ^<Meine@Email.Adresse^> >> modulxyz\.hg\hgrc cd modulabc echo Hallo Abc > HalloAbc.txt call %HG% add @echo on call %HG% commit -m "HalloAbc.txt hinzugefuegt" @echo on cd .. tree /F @popd
(Die Batchdatei und die Test-Repositories werden später noch benötigt.)
Sie erhalten ein Verzeichnis mit zwei Mercurial-Repositories:
[D:\Tools\hgweb-repos]
|- [modulabc]
| |- [.hg]
| | '- hgrc
| | '- ...
| '- HalloAbc.txt
'- [modulxyz]
'- [.hg]
'- hgrc
'- ...
Tomcat 7 downloaden und installieren, z.B. "64-bit Windows zip", apache-tomcat-7.0.32-windows-x64.zip, downloaden und entzippen, z.B. nach: D:\Tools\Tomcat-hgweb.
Passen Sie in der server.xml im
{Tomcat}\conf-Verzeichnis
(z.B. D:\Tools\Tomcat-hgweb\conf\server.xml)
bei <Connector port="..." die Portnummer an (8080 besser nicht verwenden, z.B. 4419).
Falls auf dem PC noch ein weiterer Tomcat läuft: Ändern Sie alle Portnummern (z.B. überall 4 voranstellen).
Falls hgweb die einzige Anwendung dieser Tomcat-Instanz ist: Kopieren Sie das Mercurial-Icon von http://mercurial.selenic.com/favicon.ico nach D:\Tools\Tomcat-hgweb\webapps\ROOT.
Legen Sie im {Tomcat}\webapps-Verzeichnis das neue Verzeichnis hgweb und darunter die Verzeichnisse META-INF und WEB-INF und unter WEB-INF noch cgi an:
md D:\Tools\Tomcat-hgweb\webapps\hgweb\META-INF
md D:\Tools\Tomcat-hgweb\webapps\hgweb\WEB-INF\cgi
Im {Tomcat}\webapps\hgweb\META-INF-Verzeichnis die Datei context.xml anlegen mit dem Inhalt:
<?xml version="1.0" encoding="ISO-8859-1"?> <Context privileged="true" reloadable="true"> <WatchedResource>WEB-INF/web.xml</WatchedResource> </Context>
Im {Tomcat}\webapps\hgweb\WEB-INF-Verzeichnis die Datei web.xml anlegen mit dem Inhalt (bitte den Python-Pfad anpassen):
<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<servlet>
<servlet-name>hgweb-cgi</servlet-name>
<servlet-class>org.apache.catalina.servlets.CGIServlet</servlet-class>
<init-param>
<param-name>cgiPathPrefix</param-name>
<param-value>WEB-INF/cgi</param-value>
</init-param>
<init-param>
<param-name>executable</param-name>
<param-value>C:\Programme\Python26\python.exe</param-value>
</init-param>
<init-param>
<param-name>passShellEnvironment</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<load-on-startup>5</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>hgweb-cgi</servlet-name>
<url-pattern>/cgi-bin/*</url-pattern>
</servlet-mapping>
</web-app>
Im {Tomcat}\webapps\hgweb\WEB-INF\cgi-Verzeichnis die Datei python-tomcat-test.cgi anlegen mit dem Inhalt:
print 'Status: 200 OK' print 'Content-type: text/html' print print '<html>' print '<h1>Python funktioniert.</h1>' print '</html>'
In diesem Verzeichnis ein Kommandozeilenfenster öffnen und ausführen (bitte Pfade anpassen):
cd /D D:\Tools\Tomcat-hgweb\webapps\hgweb\WEB-INF\cgi
C:\Programme\Python26\python.exe python-tomcat-test.cgi
Wenn Python korrekt installiert ist, wird als Ergebnis ein HTTP-Header und der Quelltext einer simplen HTML-Datei ausgegeben.
Tomcat starten und das Python-Testskript als CGI-Skript ausführen (bitte Portnummer anpassen):
cd /D D:\Tools\Tomcat-hgweb\bin
startup.bat
start http://localhost:4419/hgweb/cgi-bin/python-tomcat-test.cgi
Als Ergebnis zeigt der Webbrowser eine HTML-Datei mit dem Text "Python funktioniert".
Im {Tomcat}\webapps\hgweb\WEB-INF\cgi-Verzeichnis die Datei meinprojekt.cgi anlegen mit dem Inhalt (bitte den mercurial-Pfad anpassen):
config = "meinprojekt.config" import sys; sys.path.insert(0, "C:/Programme/Python26/Lib/site-packages/mercurial") from mercurial import demandimport; demandimport.enable() from mercurial.hgweb import hgweb, wsgicgi application = hgweb(config) wsgicgi.launch(application)
(Falls es Probleme gibt oder falls Sie eine andere Mercurial-Version verwenden:
Alternativ die passende Original-hgweb.cgi-Datei downloaden und entsprechend anpassen,
siehe http://mercurial.selenic.com/wiki/PublishingRepositories#Getting_the_hgweb.cgi_script).
Im {Tomcat}\webapps\hgweb\WEB-INF\cgi-Verzeichnis die Datei meinprojekt.config anlegen mit dem Inhalt (bitte Pfad anpassen):
[paths] / = D:/Tools/hgweb-repos/*
(Vorausgesetzt Sie haben wie oben beschrieben entsprechende Test-Repositories im angegebenen Verzeichnis angelegt.)
Sie erhalten folgende Tomcat-Webapp-Struktur:
[\Tools\Tomcat-hgweb\webapps]
'- [hgweb]
|- [META-INF]
| '- context.xml
'- [WEB-INF]
|- [cgi]
| |- meinprojekt.cgi
| |- meinprojekt.config
| '- python-tomcat-test.cgi
'- web.xml
Starten Sie Tomcat und rufen Sie auf:
Sie erhalten:
Falls Sie lediglich eine leere Webseite erhalten: Testen Sie die Ausgabe von:
C:\Programme\Python26\python.exe meinprojekt.cgi
Falls Sie etwas anderes als "File "meinprojekt.cgi", line 6, in <module> wsgicgi.launch(application)" erhalten, könnte dies ein Hinweis auf einen Fehler im Python-CGI-Skript sein. Eventuell benötigen Sie für Ihre Mercurial/hgweb-Version ein anderes Skript, siehe http://mercurial.selenic.com/wiki/PublishingRepositories#Getting_the_hgweb.cgi_script.
Um die Repositories verschiedener Projekte zu strukturieren, haben Sie die Wahl zwischen verschiedenen Möglichkeiten. Drei einfache werden im Folgenden vorgestellt. Sehen Sie sich hierzu auch an: http://mercurial.selenic.com/wiki/PublishingRepositories#multiple, sowie:
hg help hgweb
Zusätzlich zu der hier gezeigten Strukturierung von Projekten können Sie darüberhinaus natürlich auch innerhalb der Module strukturieren, beispielsweise indem Sie Maven-Multimodulprojekte verwenden.
Erzeugen Sie mit der oben beschrieben Batchdatei neue Verzeichnisse für Test-Repositories:
erstelle-test-hg-repos.bat D:\Tools\hgweb-repos-a\proj-1
erstelle-test-hg-repos.bat D:\Tools\hgweb-repos-a\proj-2
Unter dem gemeinsamen Basisverzeichnis hgweb-repos-a entsteht folgende Repo-Verzeichnisstruktur:
[D:\Tools\hgweb-repos-a]
|- [proj-1]
| '- [modulabc]
| | '- ...
| '- [modulxyz]
| '- ...
'- [proj-2]
'- [modulabc]
| '- ...
'- [modulxyz]
'- ...
Erstellen Sie im {Tomcat}\webapps\hgweb\WEB-INF\cgi-Verzeichnis folgende zwei Dateien:
meinevielenprojekte-a.cgi
config = "meinevielenprojekte-a.config" import sys; sys.path.insert(0, "C:/Programme/Python26/Lib/site-packages/mercurial") from mercurial import demandimport; demandimport.enable() from mercurial.hgweb import hgweb, wsgicgi application = hgweb(config) wsgicgi.launch(application)
meinevielenprojekte-a.config
[paths] / = D:/Tools/hgweb-repos-a/*
Rufen Sie auf (bei laufendem Tomcat):
http://localhost:4419/hgweb/cgi-bin/meinevielenprojekte-a.cgi
Sie erhalten:
Erzeugen Sie mit der oben beschrieben Batchdatei neue Verzeichnisse für Test-Repositories:
erstelle-test-hg-repos.bat D:\Tools\hgweb-repos-b-1
erstelle-test-hg-repos.bat D:\Tools\hgweb-repos-b-2
Die getrennten Repo-Verzeichnisse sind so strukturiert:
[D:\Tools\]
|- [hgweb-repos-b-1]
| '- [modulabc]
| | '- ...
| '- [modulxyz]
| '- ...
'- [hgweb-repos-b-2]
'- [modulabc]
| '- ...
'- [modulxyz]
'- ...
Erstellen Sie im {Tomcat}\webapps\hgweb\WEB-INF\cgi-Verzeichnis folgende zwei Dateien:
meinevielenprojekte-b.cgi
config = "meinevielenprojekte-b.config" import sys; sys.path.insert(0, "C:/Programme/Python26/Lib/site-packages/mercurial") from mercurial import demandimport; demandimport.enable() from mercurial.hgweb import hgweb, wsgicgi application = hgweb(config) wsgicgi.launch(application)
meinevielenprojekte-b.config
[paths] proj-1 = D:/Tools/hgweb-repos-b-1/* proj-2 = D:/Tools/hgweb-repos-b-2/*
Rufen Sie auf (bei laufendem Tomcat):
http://localhost:4419/hgweb/cgi-bin/meinevielenprojekte-b.cgi
Sie erhalten:
Die für die Variante B erzeugten Repos werden auch für dieses Beispiel verwendet. Lediglich die Strukturierung und Darstellung ist anders.
Erstellen Sie im {Tomcat}\webapps\hgweb\WEB-INF\cgi-Verzeichnis folgende vier Dateien:
meinevielenprojekte-proj-1.cgi
config = "meinevielenprojekte-proj-1.config" import sys; sys.path.insert(0, "C:/Programme/Python26/Lib/site-packages/mercurial") from mercurial import demandimport; demandimport.enable() from mercurial.hgweb import hgweb, wsgicgi application = hgweb(config) wsgicgi.launch(application)
meinevielenprojekte-proj-1.config
[paths] / = D:/Tools/hgweb-repos-b-1/*
meinevielenprojekte-proj-2.cgi
config = "meinevielenprojekte-proj-2.config" import sys; sys.path.insert(0, "C:/Programme/Python26/Lib/site-packages/mercurial") from mercurial import demandimport; demandimport.enable() from mercurial.hgweb import hgweb, wsgicgi application = hgweb(config) wsgicgi.launch(application)
meinevielenprojekte-proj-2.config
[paths] proj-2 = D:/Tools/hgweb-repos-b-2/*
Nur um verschiedene Möglichkeiten zu zeigen, wird statt "/" diesmal "proj-2" verwendet.
Rufen Sie beide URLs auf (bei laufendem Tomcat):
http://localhost:4419/hgweb/cgi-bin/meinevielenprojekte-proj-1.cgi
http://localhost:4419/hgweb/cgi-bin/meinevielenprojekte-proj-2.cgi
Sie erhalten:
Fügen Sie zu obiger hgweb-Installation in der {Tomcat}\webapps\hgweb\WEB-INF\web.xml vor dem abschließenden </web-app>-Tag folgenden Block hinzu:
<security-constraint>
<web-resource-collection>
<web-resource-name>HgwebAuthentication</web-resource-name>
<url-pattern>/cgi-bin/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>hgweb</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>hgweb</realm-name>
</login-config>
<security-role>
<role-name>hgweb</role-name>
</security-role>
Ersetzen Sie Sie in obiger hgweb-Installation den Inhalt der {Tomcat}\conf\tomcat-users.xml durch:
<?xml version='1.0' encoding='utf-8'?> <tomcat-users> <role rolename="hgweb" /> <user username="MeinName" password="geheim1" roles="hgweb" /> <user username="AndererName" password="geheim2" roles="hgweb" /> <role rolename="admin" /> <role rolename="manager" /> <user username="MeinName" password="MeinPasswort" roles="admin,manager" /> </tomcat-users>
Ersetzen Sie Sie in obiger hgweb-Installation den Inhalt der C:\Users\%USERNAME%\Mercurial.ini (bzw. hgrc) durch:
[ui] username = hgweb-Server editor = Notepad [web] allow_archive = zip allow_push = MeinName, AndererName push_ssl = false