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