Mercurial (hg)

+ andere TechDocs
+ Mercurial
+ Maven
+ Multimodulprojekt
+


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.



Inhalt

  1. Unterschiede zwischen zentralen und verteilten Versionskontrollsystemen
  2. Vorbemerkungen zu Mercurial
    Doku und Tutorials, Repository-Struktur, update/commit versus pull/push, .hgignore
  3. Lokale Mercurial-Installation
  4. Erste Schritte mit Mercurial
  5. MercurialEclipse-Plugin
  6. Temporärer Repository-Webserver für spontanen Changeset-Austausch
  7. Installation eines zentralen hgweb-Webservers für Mercurial-Repositories unter Windows
    Python installieren, Mercurial-Installation für hgweb, Mit Mercurial zwei Test-Repositories anlegen, Tomcat installieren und für Python-CGI-Skripte vorbereiten, hgweb in Tomcat einbinden, hgweb starten
  8. Strukturierung mehrerer Repositories-Sammlungen innerhalb eines hgweb-Webservers
  9. Einfache Authentifizierung (mit Tomcat)


Unterschiede zwischen zentralen und verteilten Versionskontrollsystemen

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:



Vorbemerkungen zu Mercurial

Doku und Tutorials

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

Repository-Struktur

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:

Mercurial-Repos-Struktur

update/commit versus pull/push

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.

.hgignore

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.



Lokale Mercurial-Installation

  1. Die gewünschte Mercurial-Version downloaden von http://mercurial.selenic.com/downloads (z.B. Mercurial-2.3.2-x64.exe).

  2. Die Mercurial-Installationsdatei ausführen und Mercurial zum Beispiel nach C:\Programme\Mercurial installieren.

  3. 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%"

  4. 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.

  5. 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.

  6. hg muss im Kommandozeilenfenster funktionieren:

    cd \

    hg version

    hg

    hg help



Erste Schritte mit Mercurial

  1. 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.

  2. 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.

  3. Falls es bereits einen Remote-hgweb-Server für Mercurial-Repositories gibt:

    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

    Falls es keinen Remote-hgweb-Server für Mercurial-Repositories gibt:

    Dann legen Sie ein neues Mercurial-Repository für das neue Modul lokal an:

    md \MeinWorkspace

    cd \MeinWorkspace

    hg init modulabcxyz

    cd modulabcxyz

  4. .hgignore anlegen:

    Falls es im lokalen modulabcxyz-Verzeichnis noch keine .hgignore-Datei gibt, legen Sie diese an wie oben gezeigt.

  5. 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)
         '- ...
    
  6. 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

  7. 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

  8. 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

  9. Alte Version wiederherstellen und wieder zurück zur neuesten Version:

    hg update -r 0

    type HalloAbcXyz.txt

    hg update

    type HalloAbcXyz.txt

  10. 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

  11. 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

  12. 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

  13. 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.

  14. 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

  15. 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.

  16. Falls Sie Änderungen aus einem Branch in einen anderen Branch übertragen wollen, sehen Sie sich das graft-Kommando an ("Cherry-Picking").



MercurialEclipse-Plugin

  1. 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).

  2. 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

  3. 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).

  4. 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

  5. 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.

  6. 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.

  7. 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>

  8. 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.).

  9. 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.

  10. Sehen Sie sich die in Eclipse verwendeten Mercurial-Repositories an über:
    Window | Show View | Mercurial Repositories.

  11. 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.

  12. Falls Sie Maven-Multimodulprojekte in Eclipse bearbeiten wollen, sehen Sie sich unbedingt an: maven-multiproj.htm#Maven-Multimodulprojekt-in-Eclipse.



Temporärer Repository-Webserver für spontanen Changeset-Austausch

  1. 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

  2. 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

    mercurial-hgweb

  3. 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'.



Installation eines zentralen hgweb-Webservers für Mercurial-Repositories unter Windows

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.

Python installieren

  1. 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.

  2. 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).

  3. Python installieren, z.B. nach C:\Programme\Python26.

  4. Der Python-Pfad braucht nicht dem Windows-Such-PATH hinzugefügt werden.

  5. Python testen:

    cd /D C:\Programme\Python26

    python -V

    python -h

Mercurial-Installation für hgweb

  1. 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).

  2. 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.

  3. 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).

  4. 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.

  5. Testen Sie hg im Kommandozeilenfenster:

    cd /D C:\Programme\Python26\Scripts

    hg version

    hg

Mit Mercurial zwei Test-Repositories anlegen

  1. 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.)

  2. Sie erhalten ein Verzeichnis mit zwei Mercurial-Repositories:

    [D:\Tools\hgweb-repos]
     |- [modulabc]
     |   |- [.hg]
     |   |   '- hgrc
     |   |   '- ...
     |   '- HalloAbc.txt
     '- [modulxyz]
         '- [.hg]
             '- hgrc
             '- ...
    

Tomcat installieren und für Python-CGI-Skripte vorbereiten

  1. 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.

  2. 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).

  3. 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.

  4. 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

  5. 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>
    
  6. 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>
    
  7. 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>'
    
  8. 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.

  9. 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".

hgweb in Tomcat einbinden

  1. 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).

  2. 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.)

  3. 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
    

hgweb starten

  1. Starten Sie Tomcat und rufen Sie auf:

    http://localhost:4419/hgweb/cgi-bin/meinprojekt.cgi

  2. Sie erhalten:

    mercurial-hgweb

  3. 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.



Strukturierung mehrerer Repositories-Sammlungen innerhalb eines hgweb-Webservers

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.

Variante A: Gemeinsames Basisverzeichnis und gemeinsame Liste unter einer URL

  1. 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

  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]
             '- ...
    
  3. 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/*
    
  4. Rufen Sie auf (bei laufendem Tomcat):

    http://localhost:4419/hgweb/cgi-bin/meinevielenprojekte-a.cgi

    Sie erhalten:

    mercurial-hgweb

Variante B: Getrennte Verzeichnisse, aber gemeinsame Liste unter einer URL

  1. 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

  2. Die getrennten Repo-Verzeichnisse sind so strukturiert:

    [D:\Tools\]
     |- [hgweb-repos-b-1]
     |   '- [modulabc]
     |   |   '- ...
     |   '- [modulxyz]
     |       '- ...
     '- [hgweb-repos-b-2]
         '- [modulabc]
         |   '- ...
         '- [modulxyz]
             '- ...
    
  3. 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/*
    
  4. Rufen Sie auf (bei laufendem Tomcat):

    http://localhost:4419/hgweb/cgi-bin/meinevielenprojekte-b.cgi

    Sie erhalten:

    mercurial-hgweb

Variante C: Getrennte Verzeichnisse und getrennte Listen mit verschiedenen URLs

  1. Die für die Variante B erzeugten Repos werden auch für dieses Beispiel verwendet. Lediglich die Strukturierung und Darstellung ist anders.

  2. 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.

  3. 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:

    mercurial-hgweb

    mercurial-hgweb



Einfache Authentifizierung (mit Tomcat)

  1. 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>
    
  2. 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>
    
  3. 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
    




Weitere Themen: andere TechDocs | Mercurial | Maven
© 2011 Torsten Horn, Aachen