author | Simon Heimberg <simohe@besonet.ch> |
Wed, 19 Feb 2014 13:25:28 +0100 | |
changeset 20532 | f1a3ae7c15df |
parent 17454 | f5e86b416e05 |
child 21041 | a2cc3c08c3ac |
permissions | -rw-r--r-- |
12828 | 1 |
Subrepositories let you nest external repositories or projects into a |
2 |
parent Mercurial repository, and make commands operate on them as a |
|
15213
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
3 |
group. |
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
4 |
|
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
5 |
Mercurial currently supports Mercurial, Git, and Subversion |
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
6 |
subrepositories. |
12828 | 7 |
|
8 |
Subrepositories are made of three components: |
|
9 |
||
10 |
1. Nested repository checkouts. They can appear anywhere in the |
|
15213
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
11 |
parent working directory. |
12828 | 12 |
|
16503
c27a769d9703
doc: add description about location of management files for subrepo
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
15474
diff
changeset
|
13 |
2. Nested repository references. They are defined in ``.hgsub``, which |
c27a769d9703
doc: add description about location of management files for subrepo
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
15474
diff
changeset
|
14 |
should be placed in the root of working directory, and |
12828 | 15 |
tell where the subrepository checkouts come from. Mercurial |
17454
f5e86b416e05
help: fix literal block syntax
Takumi IINO <trot.thunder@gmail.com>
parents:
17267
diff
changeset
|
16 |
subrepositories are referenced like:: |
12828 | 17 |
|
18 |
path/to/nested = https://example.com/nested/repo/path |
|
19 |
||
17454
f5e86b416e05
help: fix literal block syntax
Takumi IINO <trot.thunder@gmail.com>
parents:
17267
diff
changeset
|
20 |
Git and Subversion subrepos are also supported:: |
15213
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
21 |
|
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
22 |
path/to/nested = [git]git://example.com/nested/repo/path |
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
23 |
path/to/nested = [svn]https://example.com/nested/trunk/path |
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
24 |
|
12828 | 25 |
where ``path/to/nested`` is the checkout location relatively to the |
26 |
parent Mercurial root, and ``https://example.com/nested/repo/path`` |
|
27 |
is the source repository path. The source can also reference a |
|
15213
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
28 |
filesystem path. |
12828 | 29 |
|
30 |
Note that ``.hgsub`` does not exist by default in Mercurial |
|
31 |
repositories, you have to create and add it to the parent |
|
32 |
repository before using subrepositories. |
|
33 |
||
16503
c27a769d9703
doc: add description about location of management files for subrepo
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
15474
diff
changeset
|
34 |
3. Nested repository states. They are defined in ``.hgsubstate``, which |
c27a769d9703
doc: add description about location of management files for subrepo
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
15474
diff
changeset
|
35 |
is placed in the root of working directory, and |
12828 | 36 |
capture whatever information is required to restore the |
37 |
subrepositories to the state they were committed in a parent |
|
38 |
repository changeset. Mercurial automatically record the nested |
|
39 |
repositories states when committing in the parent repository. |
|
40 |
||
41 |
.. note:: |
|
20532
f1a3ae7c15df
help: remove last occurrences of ".. note::" without two newlines
Simon Heimberg <simohe@besonet.ch>
parents:
17454
diff
changeset
|
42 |
|
12828 | 43 |
The ``.hgsubstate`` file should not be edited manually. |
44 |
||
45 |
||
46 |
Adding a Subrepository |
|
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
47 |
====================== |
12828 | 48 |
|
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 |
|
51 |
to live in the parent repository. Edit ``.hgsub`` and add the |
|
52 |
subrepository entry as described above. At this point, the |
|
53 |
subrepository is tracked and the next commit will record its state in |
|
54 |
``.hgsubstate`` and bind it to the committed changeset. |
|
55 |
||
56 |
Synchronizing a Subrepository |
|
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
57 |
============================= |
12828 | 58 |
|
59 |
Subrepos do not automatically track the latest changeset of their |
|
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 |
|
62 |
developers always get a consistent set of compatible code and |
|
63 |
libraries when they update. |
|
64 |
||
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 |
|
67 |
commit in the parent repository to record the new combination. |
|
68 |
||
69 |
Deleting a Subrepository |
|
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
70 |
======================== |
12828 | 71 |
|
12860
db2ff771204d
help: correct tip about deleting a subrepository
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
12828
diff
changeset
|
72 |
To remove a subrepository from the parent repository, delete its |
db2ff771204d
help: correct tip about deleting a subrepository
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
12828
diff
changeset
|
73 |
reference from ``.hgsub``, then remove its files. |
12828 | 74 |
|
75 |
Interaction with Mercurial Commands |
|
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
76 |
=================================== |
12828 | 77 |
|
78 |
:add: add does not recurse in subrepos unless -S/--subrepos is |
|
15410
9e99d2bbb1b1
add: support adding explicit files in subrepos
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
79 |
specified. However, if you specify the full path of a file in a |
9e99d2bbb1b1
add: support adding explicit files in subrepos
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
80 |
subrepo, it will be added even without -S/--subrepos specified. |
15432 | 81 |
Git and Subversion subrepositories are currently silently |
12828 | 82 |
ignored. |
83 |
||
84 |
:archive: archive does not recurse in subrepositories unless |
|
85 |
-S/--subrepos is specified. |
|
86 |
||
87 |
:commit: commit creates a consistent snapshot of the state of the |
|
15427
2a3ab9e81a3e
subrepo: update help for commit to reflect new default behavior
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
88 |
entire project and its subrepositories. If any subrepositories |
2a3ab9e81a3e
subrepo: update help for commit to reflect new default behavior
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
89 |
have been modified, Mercurial will abort. Mercurial can be made |
2a3ab9e81a3e
subrepo: update help for commit to reflect new default behavior
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
90 |
to instead commit all modified subrepositories by specifying |
2a3ab9e81a3e
subrepo: update help for commit to reflect new default behavior
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
91 |
-S/--subrepos, or setting "ui.commitsubrepos=True" in a |
2a3ab9e81a3e
subrepo: update help for commit to reflect new default behavior
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
92 |
configuration file (see :hg:`help config`). After there are no |
2a3ab9e81a3e
subrepo: update help for commit to reflect new default behavior
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
93 |
longer any modified subrepositories, it records their state and |
2a3ab9e81a3e
subrepo: update help for commit to reflect new default behavior
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
94 |
finally commits it in the parent repository. |
12828 | 95 |
|
96 |
:diff: diff does not recurse in subrepos unless -S/--subrepos is |
|
97 |
specified. Changes are displayed as usual, on the subrepositories |
|
15428
da81da6caa6b
subrepo: improve help for git subrepo support
David M. Carr <david@carrclan.us>
parents:
15427
diff
changeset
|
98 |
elements. Git and Subversion subrepositories are currently |
da81da6caa6b
subrepo: improve help for git subrepo support
David M. Carr <david@carrclan.us>
parents:
15427
diff
changeset
|
99 |
silently ignored. |
12828 | 100 |
|
15474
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
101 |
:forget: forget currently only handles exact file matches in subrepos. |
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
102 |
Git and Subversion subrepositories are currently silently ignored. |
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
103 |
|
12828 | 104 |
:incoming: incoming does not recurse in subrepos unless -S/--subrepos |
15428
da81da6caa6b
subrepo: improve help for git subrepo support
David M. Carr <david@carrclan.us>
parents:
15427
diff
changeset
|
105 |
is specified. Git and Subversion subrepositories are currently |
da81da6caa6b
subrepo: improve help for git subrepo support
David M. Carr <david@carrclan.us>
parents:
15427
diff
changeset
|
106 |
silently ignored. |
12828 | 107 |
|
108 |
:outgoing: outgoing does not recurse in subrepos unless -S/--subrepos |
|
15428
da81da6caa6b
subrepo: improve help for git subrepo support
David M. Carr <david@carrclan.us>
parents:
15427
diff
changeset
|
109 |
is specified. Git and Subversion subrepositories are currently |
da81da6caa6b
subrepo: improve help for git subrepo support
David M. Carr <david@carrclan.us>
parents:
15427
diff
changeset
|
110 |
silently ignored. |
12828 | 111 |
|
112 |
:pull: pull is not recursive since it is not clear what to pull prior |
|
113 |
to running :hg:`update`. Listing and retrieving all |
|
114 |
subrepositories changes referenced by the parent repository pulled |
|
115 |
changesets is expensive at best, impossible in the Subversion |
|
116 |
case. |
|
117 |
||
118 |
:push: Mercurial will automatically push all subrepositories first |
|
119 |
when the parent repository is being pushed. This ensures new |
|
120 |
subrepository changes are available when referenced by top-level |
|
15429
e48f0913f018
subrepo: improve help for svn subrepo support
David M. Carr <david@carrclan.us>
parents:
15428
diff
changeset
|
121 |
repositories. Push is a no-op for Subversion subrepositories. |
12828 | 122 |
|
123 |
:status: status does not recurse into subrepositories unless |
|
124 |
-S/--subrepos is specified. Subrepository changes are displayed as |
|
125 |
regular Mercurial changes on the subrepository |
|
126 |
elements. Subversion subrepositories are currently silently |
|
127 |
ignored. |
|
128 |
||
129 |
:update: update restores the subrepos in the state they were |
|
130 |
originally committed in target changeset. If the recorded |
|
131 |
changeset is not available in the current subrepository, Mercurial |
|
132 |
will pull it in first before updating. This means that updating |
|
133 |
can require network access when using subrepositories. |
|
134 |
||
135 |
Remapping Subrepositories Sources |
|
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
136 |
================================= |
12828 | 137 |
|
138 |
A subrepository source location may change during a project life, |
|
139 |
invalidating references stored in the parent repository history. To |
|
140 |
fix this, rewriting rules can be defined in parent repository ``hgrc`` |
|
141 |
file or in Mercurial configuration. See the ``[subpaths]`` section in |
|
142 |
hgrc(5) for more details. |
|
143 |