subrepos.txt
137 lines
| 5.6 KiB
| text/plain
|
TextLexer
|
r12828 | Subrepositories let you nest external repositories or projects into a | ||
parent Mercurial repository, and make commands operate on them as a | ||||
|
r15213 | group. | ||
Mercurial currently supports Mercurial, Git, and Subversion | ||||
subrepositories. | ||||
|
r12828 | |||
Subrepositories are made of three components: | ||||
1. Nested repository checkouts. They can appear anywhere in the | ||||
|
r15213 | parent working directory. | ||
|
r12828 | |||
2. Nested repository references. They are defined in ``.hgsub`` and | ||||
tell where the subrepository checkouts come from. Mercurial | ||||
subrepositories are referenced like: | ||||
path/to/nested = https://example.com/nested/repo/path | ||||
|
r15213 | 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 | ||||
|
r12828 | 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 | ||||
|
r15213 | filesystem path. | ||
|
r12828 | |||
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`` 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. | ||||
.. note:: | ||||
The ``.hgsubstate`` file should not be edited manually. | ||||
Adding a Subrepository | ||||
---------------------- | ||||
If ``.hgsub`` does not exist, create it and add it to the parent | ||||
repository. Clone or checkout the external projects where you want it | ||||
to live in the parent repository. Edit ``.hgsub`` and add the | ||||
subrepository entry as described above. At this point, the | ||||
subrepository is tracked and the next commit will record its state in | ||||
``.hgsubstate`` and bind it to the committed changeset. | ||||
Synchronizing a Subrepository | ||||
----------------------------- | ||||
Subrepos do not automatically track the latest changeset of their | ||||
sources. Instead, they are updated to the changeset that corresponds | ||||
with the changeset checked out in the top-level changeset. This is so | ||||
developers always get a consistent set of compatible code and | ||||
libraries when they update. | ||||
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 | ||||
------------------------ | ||||
|
r12860 | To remove a subrepository from the parent repository, delete its | ||
reference from ``.hgsub``, then remove its files. | ||||
|
r12828 | |||
Interaction with Mercurial Commands | ||||
----------------------------------- | ||||
:add: add does not recurse in subrepos unless -S/--subrepos is | ||||
|
r15410 | specified. However, if you specify the full path of a file in a | ||
subrepo, it will be added even without -S/--subrepos specified. | ||||
|
r15432 | Git and Subversion subrepositories are currently silently | ||
|
r12828 | ignored. | ||
:archive: archive does not recurse in subrepositories unless | ||||
-S/--subrepos is specified. | ||||
:commit: commit creates a consistent snapshot of the state of the | ||||
|
r15427 | 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. | ||||
|
r12828 | |||
:diff: diff does not recurse in subrepos unless -S/--subrepos is | ||||
specified. Changes are displayed as usual, on the subrepositories | ||||
|
r15428 | elements. Git and Subversion subrepositories are currently | ||
silently ignored. | ||||
|
r12828 | |||
:incoming: incoming does not recurse in subrepos unless -S/--subrepos | ||||
|
r15428 | is specified. Git and Subversion subrepositories are currently | ||
silently ignored. | ||||
|
r12828 | |||
:outgoing: outgoing does not recurse in subrepos unless -S/--subrepos | ||||
|
r15428 | is specified. Git and Subversion subrepositories are currently | ||
silently ignored. | ||||
|
r12828 | |||
:pull: pull is not recursive since it is not clear what to pull prior | ||||
to running :hg:`update`. Listing and retrieving all | ||||
subrepositories changes referenced by the parent repository pulled | ||||
changesets is expensive at best, impossible in the Subversion | ||||
case. | ||||
:push: Mercurial will automatically push all subrepositories first | ||||
when the parent repository is being pushed. This ensures new | ||||
subrepository changes are available when referenced by top-level | ||||
|
r15429 | repositories. Push is a no-op for Subversion subrepositories. | ||
|
r12828 | |||
:status: status does not recurse into subrepositories unless | ||||
-S/--subrepos is specified. Subrepository changes are displayed as | ||||
regular Mercurial changes on the subrepository | ||||
elements. Subversion subrepositories are currently silently | ||||
ignored. | ||||
:update: update restores the subrepos in the state they were | ||||
originally committed in target changeset. If the recorded | ||||
changeset is not available in the current subrepository, Mercurial | ||||
will pull it in first before updating. This means that updating | ||||
can require network access when using subrepositories. | ||||
Remapping Subrepositories Sources | ||||
--------------------------------- | ||||
A subrepository source location may change during a project life, | ||||
invalidating references stored in the parent repository history. To | ||||
fix this, rewriting rules can be defined in parent repository ``hgrc`` | ||||
file or in Mercurial configuration. See the ``[subpaths]`` section in | ||||
hgrc(5) for more details. | ||||