Show More
@@ -1,164 +1,163 b'' | |||
|
1 | 1 | Subrepositories let you nest external repositories or projects into a |
|
2 | 2 | parent Mercurial repository, and make commands operate on them as a |
|
3 | 3 | group. |
|
4 | 4 | |
|
5 | 5 | Mercurial currently supports Mercurial, Git, and Subversion |
|
6 | 6 | subrepositories. |
|
7 | 7 | |
|
8 | 8 | Subrepositories are made of three components: |
|
9 | 9 | |
|
10 | 10 | 1. Nested repository checkouts. They can appear anywhere in the |
|
11 | 11 | parent working directory. |
|
12 | 12 | |
|
13 | 13 | 2. Nested repository references. They are defined in ``.hgsub``, which |
|
14 | 14 | should be placed in the root of working directory, and |
|
15 | 15 | tell where the subrepository checkouts come from. Mercurial |
|
16 | 16 | subrepositories are referenced like:: |
|
17 | 17 | |
|
18 | 18 | path/to/nested = https://example.com/nested/repo/path |
|
19 | 19 | |
|
20 | 20 | Git and Subversion subrepos are also supported:: |
|
21 | 21 | |
|
22 | 22 | path/to/nested = [git]git://example.com/nested/repo/path |
|
23 | 23 | path/to/nested = [svn]https://example.com/nested/trunk/path |
|
24 | 24 | |
|
25 | 25 | where ``path/to/nested`` is the checkout location relatively to the |
|
26 | 26 | parent Mercurial root, and ``https://example.com/nested/repo/path`` |
|
27 | 27 | is the source repository path. The source can also reference a |
|
28 | 28 | filesystem path. |
|
29 | 29 | |
|
30 | 30 | Note that ``.hgsub`` does not exist by default in Mercurial |
|
31 | 31 | repositories, you have to create and add it to the parent |
|
32 | 32 | repository before using subrepositories. |
|
33 | 33 | |
|
34 | 34 | 3. Nested repository states. They are defined in ``.hgsubstate``, which |
|
35 | 35 | is placed in the root of working directory, and |
|
36 | 36 | capture whatever information is required to restore the |
|
37 | 37 | subrepositories to the state they were committed in a parent |
|
38 | 38 | repository changeset. Mercurial automatically record the nested |
|
39 | 39 | repositories states when committing in the parent repository. |
|
40 | 40 | |
|
41 | 41 | .. note:: |
|
42 | 42 | |
|
43 | 43 | The ``.hgsubstate`` file should not be edited manually. |
|
44 | 44 | |
|
45 | 45 | |
|
46 | 46 | Adding a Subrepository |
|
47 | 47 | ====================== |
|
48 | 48 | |
|
49 | 49 | If ``.hgsub`` does not exist, create it and add it to the parent |
|
50 | 50 | repository. Clone or checkout the external projects where you want it |
|
51 | 51 | to live in the parent repository. Edit ``.hgsub`` and add the |
|
52 | 52 | subrepository entry as described above. At this point, the |
|
53 | 53 | subrepository is tracked and the next commit will record its state in |
|
54 | 54 | ``.hgsubstate`` and bind it to the committed changeset. |
|
55 | 55 | |
|
56 | 56 | Synchronizing a Subrepository |
|
57 | 57 | ============================= |
|
58 | 58 | |
|
59 | 59 | Subrepos do not automatically track the latest changeset of their |
|
60 | 60 | sources. Instead, they are updated to the changeset that corresponds |
|
61 | 61 | with the changeset checked out in the top-level changeset. This is so |
|
62 | 62 | developers always get a consistent set of compatible code and |
|
63 | 63 | libraries when they update. |
|
64 | 64 | |
|
65 | 65 | Thus, updating subrepos is a manual process. Simply check out target |
|
66 | 66 | subrepo at the desired revision, test in the top-level repo, then |
|
67 | 67 | commit in the parent repository to record the new combination. |
|
68 | 68 | |
|
69 | 69 | Deleting a Subrepository |
|
70 | 70 | ======================== |
|
71 | 71 | |
|
72 | 72 | To remove a subrepository from the parent repository, delete its |
|
73 | 73 | reference from ``.hgsub``, then remove its files. |
|
74 | 74 | |
|
75 | 75 | Interaction with Mercurial Commands |
|
76 | 76 | =================================== |
|
77 | 77 | |
|
78 | 78 | :add: add does not recurse in subrepos unless -S/--subrepos is |
|
79 | 79 | specified. However, if you specify the full path of a file in a |
|
80 | 80 | subrepo, it will be added even without -S/--subrepos specified. |
|
81 | 81 | Subversion subrepositories are currently silently |
|
82 | 82 | ignored. |
|
83 | 83 | |
|
84 | 84 | :addremove: addremove does not recurse into subrepos unless |
|
85 | 85 | -S/--subrepos is specified. However, if you specify the full |
|
86 | 86 | path of a directory in a subrepo, addremove will be performed on |
|
87 | 87 | it even without -S/--subrepos being specified. Git and |
|
88 | 88 | Subversion subrepositories will print a warning and continue. |
|
89 | 89 | |
|
90 | 90 | :archive: archive does not recurse in subrepositories unless |
|
91 | 91 | -S/--subrepos is specified. |
|
92 | 92 | |
|
93 | 93 | :cat: cat currently only handles exact file matches in subrepos. |
|
94 | 94 | Subversion subrepositories are currently ignored. |
|
95 | 95 | |
|
96 | 96 | :commit: commit creates a consistent snapshot of the state of the |
|
97 | 97 | entire project and its subrepositories. If any subrepositories |
|
98 | 98 | have been modified, Mercurial will abort. Mercurial can be made |
|
99 | 99 | to instead commit all modified subrepositories by specifying |
|
100 | 100 | -S/--subrepos, or setting "ui.commitsubrepos=True" in a |
|
101 | 101 | configuration file (see :hg:`help config`). After there are no |
|
102 | 102 | longer any modified subrepositories, it records their state and |
|
103 | 103 | finally commits it in the parent repository. The --addremove |
|
104 | 104 | option also honors the -S/--subrepos option. However, Git and |
|
105 | 105 | Subversion subrepositories will print a warning and abort. |
|
106 | 106 | |
|
107 | 107 | :diff: diff does not recurse in subrepos unless -S/--subrepos is |
|
108 | 108 | specified. Changes are displayed as usual, on the subrepositories |
|
109 | elements. Git subrepositories do not support --include/--exclude. | |
|
110 | Subversion subrepositories are currently silently ignored. | |
|
109 | elements. Subversion subrepositories are currently silently ignored. | |
|
111 | 110 | |
|
112 | 111 | :files: files does not recurse into subrepos unless -S/--subrepos is |
|
113 | 112 | specified. Git and Subversion subrepositories are currently |
|
114 | 113 | silently ignored. |
|
115 | 114 | |
|
116 | 115 | :forget: forget currently only handles exact file matches in subrepos. |
|
117 | 116 | Git and Subversion subrepositories are currently silently ignored. |
|
118 | 117 | |
|
119 | 118 | :incoming: incoming does not recurse in subrepos unless -S/--subrepos |
|
120 | 119 | is specified. Git and Subversion subrepositories are currently |
|
121 | 120 | silently ignored. |
|
122 | 121 | |
|
123 | 122 | :outgoing: outgoing does not recurse in subrepos unless -S/--subrepos |
|
124 | 123 | is specified. Git and Subversion subrepositories are currently |
|
125 | 124 | silently ignored. |
|
126 | 125 | |
|
127 | 126 | :pull: pull is not recursive since it is not clear what to pull prior |
|
128 | 127 | to running :hg:`update`. Listing and retrieving all |
|
129 | 128 | subrepositories changes referenced by the parent repository pulled |
|
130 | 129 | changesets is expensive at best, impossible in the Subversion |
|
131 | 130 | case. |
|
132 | 131 | |
|
133 | 132 | :push: Mercurial will automatically push all subrepositories first |
|
134 | 133 | when the parent repository is being pushed. This ensures new |
|
135 | 134 | subrepository changes are available when referenced by top-level |
|
136 | 135 | repositories. Push is a no-op for Subversion subrepositories. |
|
137 | 136 | |
|
138 | 137 | :status: status does not recurse into subrepositories unless |
|
139 | 138 | -S/--subrepos is specified. Subrepository changes are displayed as |
|
140 | 139 | regular Mercurial changes on the subrepository |
|
141 | 140 | elements. Subversion subrepositories are currently silently |
|
142 | 141 | ignored. |
|
143 | 142 | |
|
144 | 143 | :remove: remove does not recurse into subrepositories unless |
|
145 | 144 | -S/--subrepos is specified. However, if you specify a file or |
|
146 | 145 | directory path in a subrepo, it will be removed even without |
|
147 | 146 | -S/--subrepos. Git and Subversion subrepositories are currently |
|
148 | 147 | silently ignored. |
|
149 | 148 | |
|
150 | 149 | :update: update restores the subrepos in the state they were |
|
151 | 150 | originally committed in target changeset. If the recorded |
|
152 | 151 | changeset is not available in the current subrepository, Mercurial |
|
153 | 152 | will pull it in first before updating. This means that updating |
|
154 | 153 | can require network access when using subrepositories. |
|
155 | 154 | |
|
156 | 155 | Remapping Subrepositories Sources |
|
157 | 156 | ================================= |
|
158 | 157 | |
|
159 | 158 | A subrepository source location may change during a project life, |
|
160 | 159 | invalidating references stored in the parent repository history. To |
|
161 | 160 | fix this, rewriting rules can be defined in parent repository ``hgrc`` |
|
162 | 161 | file or in Mercurial configuration. See the ``[subpaths]`` section in |
|
163 | 162 | hgrc(5) for more details. |
|
164 | 163 |
General Comments 0
You need to be logged in to leave comments.
Login now