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