Unterarchive

Subrepositories let you nest external repositories or projects into a parent Mercurial repository, and make commands operate on them as a group.

Mercurial unterstützt im Augenblick Mercurial-, Git- und Subversion- Unterarchive.

Unterarchive bestehen aus drei Komponenten:

  1. Verschachtelte Archivaktualisierungen. Sie können überall im übergeordneten Arbeitsverzeichnis auftauchen.
  2. Verschachtelte Archivreferenzen. Sie werden in ".hgsub" definiert, was in der Wurzel des Arbeitsverzeichnisses abgelegt werden sollte, und geben an, wo Aktualisierungen für Unterarchive herkommen. Mercurial-Unterarchive werden wie folgt angegeben:
    path/to/nested = https://example.com/nested/repo/path
    

    Git and Subversion subrepos are also supported:

    path/to/nested = [git]git://example.com/nested/repo/path
    path/to/nested = [svn]https://example.com/nested/trunk/path
    

    where "path/to/nested" is the checkout location relatively to the parent Mercurial root, and "https://example.com/nested/repo/path" is the source repository path. The source can also reference a filesystem path.

    Note that ".hgsub" does not exist by default in Mercurial repositories, you have to create and add it to the parent repository before using subrepositories.

  3. Nested repository states. They are defined in ".hgsubstate", which is placed in the root of working directory, and capture whatever information is required to restore the subrepositories to the state they were committed in a parent repository changeset. Mercurial automatically record the nested repositories states when committing in the parent repository.

    Hinweis:

    The ".hgsubstate" file should not be edited manually.

Adding a Subrepository

Wenn ".hgsub" nicht existiert, wird die Datei erstellt und dem übergeordneten Archiv hinzugefügt. Erstellen Sie eine Arbeitskopie (beispielsweise mit clone oder checkout) der externen Projekte dort, wo sie im übergeordneten Projektarchiv liegen soll. Bearbeiten Sie ".hgsub" und fügen Sie den Unterarchiv-Eintrag wie oben beschrieben hinzu. Anschließend wird das Unterarchiv überwacht und bei der nächsten Übernahme wird sein Stand in ".hgsubstate" erfasst und an die übernommene Änderung gebunden.

Synchronizing a Subrepository

Unterarchive übernehmen nicht automatisch den neuesten Änderungssatz ihrer Quellen. Stattdessen werden sie auf die Version aktualisiert, die der Version des übergeordneten Änderungssatzes entspricht. Dies geschieht, damit Entwickler immer eine konsistente Menge von Code und Bibliotheken erhalten, wenn sie aktualisieren.

Thus, updating subrepos is a manual process. Simply check out target subrepo at the desired revision, test in the top-level repo, then commit in the parent repository to record the new combination.

Deleting a Subrepository

Um ein Unterarchiv aus seinem Elternarchiv zu entfernen, löschen Sie seine Verweise aus ".hgsub" und seine Dateien.

Interaction with Mercurial Commands

add
add does not recurse in subrepos unless -S/--subrepos is specified. However, if you specify the full path of a file in a subrepo, it will be added even without -S/--subrepos specified. Subversion subrepositories are currently silently ignored.
addremove
addremove does not recurse into subrepos unless -S/--subrepos is specified. However, if you specify the full path of a directory in a subrepo, addremove will be performed on it even without -S/--subrepos being specified. Git and Subversion subrepositories will print a warning and continue.
archive
"archive" behandelt keine Unterarchive, es sei denn es ist -S/--subrepos angegeben.
cat
Git subrepositories only support exact file matches. Subversion subrepositories are currently ignored.
commit
commit creates a consistent snapshot of the state of the entire project and its subrepositories. If any subrepositories have been modified, Mercurial will abort. Mercurial can be made to instead commit all modified subrepositories by specifying -S/--subrepos, or setting "ui.commitsubrepos=True" in a configuration file (see 'hg help config'). After there are no longer any modified subrepositories, it records their state and finally commits it in the parent repository. The --addremove option also honors the -S/--subrepos option. However, Git and Subversion subrepositories will print a warning and abort.
diff
diff does not recurse in subrepos unless -S/--subrepos is specified. However, if you specify the full path of a file or directory in a subrepo, it will be diffed even without -S/--subrepos being specified. Subversion subrepositories are currently silently ignored.
files
files does not recurse into subrepos unless -S/--subrepos is specified. However, if you specify the full path of a file or directory in a subrepo, it will be displayed even without -S/--subrepos being specified. Git and Subversion subrepositories are currently silently ignored.
forget
"forget" behandelt zur Zeit nur exakte Passungen (matches) in Unterarchiven. Git- und Subversion-Unterarchive werden zur Zeit still ignoriert.
incoming
"incoming" behandelt keine Unterarchive, es sei denn es ist -S/--subrepos angegeben. Git- und Subversion-Unterarchive werden zur Zeit still ignoriert.
outgoing
"outgoing" behandelt keine Unterarchive, es sei denn es ist -S/--subrepos angegeben. Git- und Subversion-Unterarchive werden zur Zeit still ignoriert.
pull
"pull" behandelt keine Unterverzeichnisse, weil es nicht klar ist, was abgerufen werden soll, bevor 'hg update' ausgeführt wird. Alle Änderungen von Unterarchiven zu laden und aufzulisten, auf die von neu abgerufenen Änderungssätzen des übergeordneten Archivs verwiesen wird, ist bestenfalls teuer und unmöglich im Falle von Subversion.
push
Mercurial überträgt automatisch zuerst alle Unterverzeichnisse wenn das übergeordnete Archiv übertragen wird. Dies stellt sicher, dass neue Änderungen von Unterarchiven verfügbar sind, wenn sich übergeordnete Archive sich auf sie beziehen. "push" wird für Subversion-Unterarchive übersprungen.
serve
serve does not recurse into subrepositories unless -S/--subrepos is specified. Git and Subversion subrepositories are currently silently ignored.
status
"status" behandelt keine Unterarchive, es sei denn es ist -S/--subrepos angegeben. Änderungen von Unterarchiven werden als normale Mercurial-Änderungen am Unterverzeichnis angezeigt. Subversion-Unterarchive werden zur Zeit still ignoriert.
remove
remove does not recurse into subrepositories unless -S/--subrepos is specified. However, if you specify a file or directory path in a subrepo, it will be removed even without -S/--subrepos. Git and Subversion subrepositories are currently silently ignored.
update
"update" setzt Unterarchive zurück auf den Stand, in dem sie ursprünglich im Zieländerungssatz übernommen wurden. Falls der angegebene Änderungssatz nicht verfügbar ist, ruft Mercurial es zunächst vor der Aktualisierung ab. Das bedeutet, dass die Aktualisierung einen Netzwerk-Zugang benötigt, wenn Unterverzeichnisse verwendet werden.

Remapping Subrepositories Sources

Der Ablageort eines Unterverzeichnisses kann sich während der Lebenszeit eines Projektes ändern, sodass im übergeordneten Archiv gespeicherte Referenzen zerstört werden können. Um dies zu beheben, können in der "hgrc"-Datei des übergeordneten Archivs oder der Mercurial-Konfiguration Überschreibregeln (rewriting rules) angegeben werden. Siehe "[subpaths]"-Eintrag in hgrc(5) für mehr Details.