subrepos.txt
160 lines
| 6.7 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 | |||
|
r16503 | 2. Nested repository references. They are defined in ``.hgsub``, which | ||
should be placed in the root of working directory, and | ||||
|
r12828 | tell where the subrepository checkouts come from. Mercurial | ||
|
r17454 | subrepositories are referenced like:: | ||
|
r12828 | |||
path/to/nested = https://example.com/nested/repo/path | ||||
|
r17454 | Git and Subversion subrepos are also supported:: | ||
|
r15213 | |||
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. | ||||
|
r16503 | 3. Nested repository states. They are defined in ``.hgsubstate``, which | ||
is placed in the root of working directory, and | ||||
|
r12828 | 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:: | ||||
|
r20532 | |||
|
r12828 | The ``.hgsubstate`` file should not be edited manually. | ||
Adding a Subrepository | ||||
|
r17267 | ====================== | ||
|
r12828 | |||
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 | ||||
|
r17267 | ============================= | ||
|
r12828 | |||
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 | ||||
|
r17267 | ======================== | ||
|
r12828 | |||
|
r12860 | To remove a subrepository from the parent repository, delete its | ||
reference from ``.hgsub``, then remove its files. | ||||
|
r12828 | |||
Interaction with Mercurial Commands | ||||
|
r17267 | =================================== | ||
|
r12828 | |||
: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. | ||
|
r23538 | :addremove: addremove does not recurse into subrepos unless | ||
|
r23539 | -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. | ||||
|
r23538 | |||
|
r12828 | :archive: archive does not recurse in subrepositories unless | ||
-S/--subrepos is specified. | ||||
|
r21041 | :cat: cat currently only handles exact file matches in subrepos. | ||
|
r23991 | Subversion subrepositories are currently ignored. | ||
|
r21041 | |||
|
r12828 | :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 | ||||
|
r23537 | 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. | ||||
|
r12828 | |||
:diff: diff does not recurse in subrepos unless -S/--subrepos is | ||||
specified. Changes are displayed as usual, on the subrepositories | ||||
|
r23523 | elements. Git subrepositories do not support --include/--exclude. | ||
Subversion subrepositories are currently silently ignored. | ||||
|
r12828 | |||
|
r15474 | :forget: forget currently only handles exact file matches in subrepos. | ||
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. | ||||
|
r23325 | :remove: remove does not recurse into subrepositories unless | ||
|
r23326 | -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. | ||||
|
r23325 | |||
|
r12828 | :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 | ||||
|
r17267 | ================================= | ||
|
r12828 | |||
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. | ||||