|
12828
|
1 Subrepositories let you nest external repositories or projects into a
|
|
|
2 parent Mercurial repository, and make commands operate on them as a
|
|
|
3 group. External Mercurial and Subversion projects are currently
|
|
|
4 supported.
|
|
|
5
|
|
|
6 Subrepositories are made of three components:
|
|
|
7
|
|
|
8 1. Nested repository checkouts. They can appear anywhere in the
|
|
|
9 parent working directory, and are Mercurial clones or Subversion
|
|
|
10 checkouts.
|
|
|
11
|
|
|
12 2. Nested repository references. They are defined in ``.hgsub`` and
|
|
|
13 tell where the subrepository checkouts come from. Mercurial
|
|
|
14 subrepositories are referenced like:
|
|
|
15
|
|
|
16 path/to/nested = https://example.com/nested/repo/path
|
|
|
17
|
|
|
18 where ``path/to/nested`` is the checkout location relatively to the
|
|
|
19 parent Mercurial root, and ``https://example.com/nested/repo/path``
|
|
|
20 is the source repository path. The source can also reference a
|
|
|
21 filesystem path. Subversion repositories are defined with:
|
|
|
22
|
|
|
23 path/to/nested = [svn]https://example.com/nested/trunk/path
|
|
|
24
|
|
|
25 Note that ``.hgsub`` does not exist by default in Mercurial
|
|
|
26 repositories, you have to create and add it to the parent
|
|
|
27 repository before using subrepositories.
|
|
|
28
|
|
|
29 3. Nested repository states. They are defined in ``.hgsubstate`` and
|
|
|
30 capture whatever information is required to restore the
|
|
|
31 subrepositories to the state they were committed in a parent
|
|
|
32 repository changeset. Mercurial automatically record the nested
|
|
|
33 repositories states when committing in the parent repository.
|
|
|
34
|
|
|
35 .. note::
|
|
|
36 The ``.hgsubstate`` file should not be edited manually.
|
|
|
37
|
|
|
38
|
|
|
39 Adding a Subrepository
|
|
|
40 ----------------------
|
|
|
41
|
|
|
42 If ``.hgsub`` does not exist, create it and add it to the parent
|
|
|
43 repository. Clone or checkout the external projects where you want it
|
|
|
44 to live in the parent repository. Edit ``.hgsub`` and add the
|
|
|
45 subrepository entry as described above. At this point, the
|
|
|
46 subrepository is tracked and the next commit will record its state in
|
|
|
47 ``.hgsubstate`` and bind it to the committed changeset.
|
|
|
48
|
|
|
49 Synchronizing a Subrepository
|
|
|
50 -----------------------------
|
|
|
51
|
|
|
52 Subrepos do not automatically track the latest changeset of their
|
|
|
53 sources. Instead, they are updated to the changeset that corresponds
|
|
|
54 with the changeset checked out in the top-level changeset. This is so
|
|
|
55 developers always get a consistent set of compatible code and
|
|
|
56 libraries when they update.
|
|
|
57
|
|
|
58 Thus, updating subrepos is a manual process. Simply check out target
|
|
|
59 subrepo at the desired revision, test in the top-level repo, then
|
|
|
60 commit in the parent repository to record the new combination.
|
|
|
61
|
|
|
62 Deleting a Subrepository
|
|
|
63 ------------------------
|
|
|
64
|
|
|
65 To remove a subrepo from the parent repository, delete its reference
|
|
|
66 from ``.hgsub``. Then, the subrepo tree will show up as a set of
|
|
|
67 unknown files in :hg:`status`, and you can delete the files.
|
|
|
68
|
|
|
69 Interaction with Mercurial Commands
|
|
|
70 -----------------------------------
|
|
|
71
|
|
|
72 :add: add does not recurse in subrepos unless -S/--subrepos is
|
|
|
73 specified. Subversion subrepositories are currently silently
|
|
|
74 ignored.
|
|
|
75
|
|
|
76 :archive: archive does not recurse in subrepositories unless
|
|
|
77 -S/--subrepos is specified.
|
|
|
78
|
|
|
79 :commit: commit creates a consistent snapshot of the state of the
|
|
|
80 entire project and its subrepositories. It does this by first
|
|
|
81 attempting to commit all modified subrepositories, then recording
|
|
|
82 their state and finally committing it in the parent repository.
|
|
|
83
|
|
|
84 :diff: diff does not recurse in subrepos unless -S/--subrepos is
|
|
|
85 specified. Changes are displayed as usual, on the subrepositories
|
|
|
86 elements. Subversion subrepositories are currently silently
|
|
|
87 ignored.
|
|
|
88
|
|
|
89 :incoming: incoming does not recurse in subrepos unless -S/--subrepos
|
|
|
90 is specified. Subversion subrepositories are currently silently
|
|
|
91 ignored.
|
|
|
92
|
|
|
93 :outgoing: outgoing does not recurse in subrepos unless -S/--subrepos
|
|
|
94 is specified. Subversion subrepositories are currently silently
|
|
|
95 ignored.
|
|
|
96
|
|
|
97 :pull: pull is not recursive since it is not clear what to pull prior
|
|
|
98 to running :hg:`update`. Listing and retrieving all
|
|
|
99 subrepositories changes referenced by the parent repository pulled
|
|
|
100 changesets is expensive at best, impossible in the Subversion
|
|
|
101 case.
|
|
|
102
|
|
|
103 :push: Mercurial will automatically push all subrepositories first
|
|
|
104 when the parent repository is being pushed. This ensures new
|
|
|
105 subrepository changes are available when referenced by top-level
|
|
|
106 repositories.
|
|
|
107
|
|
|
108 :status: status does not recurse into subrepositories unless
|
|
|
109 -S/--subrepos is specified. Subrepository changes are displayed as
|
|
|
110 regular Mercurial changes on the subrepository
|
|
|
111 elements. Subversion subrepositories are currently silently
|
|
|
112 ignored.
|
|
|
113
|
|
|
114 :update: update restores the subrepos in the state they were
|
|
|
115 originally committed in target changeset. If the recorded
|
|
|
116 changeset is not available in the current subrepository, Mercurial
|
|
|
117 will pull it in first before updating. This means that updating
|
|
|
118 can require network access when using subrepositories.
|
|
|
119
|
|
|
120 Remapping Subrepositories Sources
|
|
|
121 ---------------------------------
|
|
|
122
|
|
|
123 A subrepository source location may change during a project life,
|
|
|
124 invalidating references stored in the parent repository history. To
|
|
|
125 fix this, rewriting rules can be defined in parent repository ``hgrc``
|
|
|
126 file or in Mercurial configuration. See the ``[subpaths]`` section in
|
|
|
127 hgrc(5) for more details.
|
|
|
128
|
