Mercurial > hg
annotate mercurial/help/subrepos.txt @ 43148:843da18386d5
sidedatacopies: deal with upgrading and downgrading to that format
This is quite useful to test this on real life data.
Differential Revision: https://phab.mercurial-scm.org/D6955
author | Pierre-Yves David <pierre-yves.david@octobus.net> |
---|---|
date | Sun, 06 Oct 2019 23:36:52 -0400 |
parents | db26dbbee74d |
children |
rev | line source |
---|---|
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. |
24174
bd9f64ec891d
subrepos: support adding files in git subrepos
Mathias De Maré <mathias.demare@gmail.com>
parents:
23991
diff
changeset
|
81 Subversion subrepositories are currently silently |
12828 | 82 ignored. |
83 | |
23538
ccfb56450f21
addremove: add support for the -S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
23537
diff
changeset
|
84 :addremove: addremove does not recurse into subrepos unless |
23539
cb42050f2dad
addremove: support addremove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23538
diff
changeset
|
85 -S/--subrepos is specified. However, if you specify the full |
cb42050f2dad
addremove: support addremove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23538
diff
changeset
|
86 path of a directory in a subrepo, addremove will be performed on |
cb42050f2dad
addremove: support addremove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23538
diff
changeset
|
87 it even without -S/--subrepos being specified. Git and |
cb42050f2dad
addremove: support addremove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23538
diff
changeset
|
88 Subversion subrepositories will print a warning and continue. |
23538
ccfb56450f21
addremove: add support for the -S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
23537
diff
changeset
|
89 |
12828 | 90 :archive: archive does not recurse in subrepositories unless |
91 -S/--subrepos is specified. | |
92 | |
35165
27196b7fc1ac
cat: record the current behavior of wildcard matches in subrepos
Yuya Nishihara <yuya@tcha.org>
parents:
32005
diff
changeset
|
93 :cat: Git subrepositories only support exact file matches. |
23991
07c1a7d1ef69
subrepo: add 'cat' support for git subrepos
Mathias De Maré <mathias.demare@gmail.com>
parents:
23539
diff
changeset
|
94 Subversion subrepositories are currently ignored. |
21041
a2cc3c08c3ac
cat: support cat with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
20532
diff
changeset
|
95 |
12828 | 96 :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
|
97 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
|
98 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
|
99 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
|
100 -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
|
101 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
|
102 longer any modified subrepositories, it records their state and |
23537
f1b06a8aad42
commit: propagate --addremove to subrepos if -S is specified (issue3759)
Matt Harbison <matt_harbison@yahoo.com>
parents:
23523
diff
changeset
|
103 finally commits it in the parent repository. The --addremove |
f1b06a8aad42
commit: propagate --addremove to subrepos if -S is specified (issue3759)
Matt Harbison <matt_harbison@yahoo.com>
parents:
23523
diff
changeset
|
104 option also honors the -S/--subrepos option. However, Git and |
f1b06a8aad42
commit: propagate --addremove to subrepos if -S is specified (issue3759)
Matt Harbison <matt_harbison@yahoo.com>
parents:
23523
diff
changeset
|
105 Subversion subrepositories will print a warning and abort. |
12828 | 106 |
107 :diff: diff does not recurse in subrepos unless -S/--subrepos is | |
42010
db26dbbee74d
diff: support diffing explicit files in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
35165
diff
changeset
|
108 specified. However, if you specify the full path of a file or |
db26dbbee74d
diff: support diffing explicit files in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
35165
diff
changeset
|
109 directory in a subrepo, it will be diffed even without |
db26dbbee74d
diff: support diffing explicit files in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
35165
diff
changeset
|
110 -S/--subrepos being specified. Subversion subrepositories are |
db26dbbee74d
diff: support diffing explicit files in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
35165
diff
changeset
|
111 currently silently ignored. |
12828 | 112 |
24413
a8595176dd64
subrepo: add basic support to hgsubrepo for the files command
Matt Harbison <matt_harbison@yahoo.com>
parents:
24174
diff
changeset
|
113 :files: files does not recurse into subrepos unless -S/--subrepos is |
25228
63a57a2727b6
files: recurse into subrepos automatically with an explicit path
Matt Harbison <matt_harbison@yahoo.com>
parents:
24874
diff
changeset
|
114 specified. However, if you specify the full path of a file or |
63a57a2727b6
files: recurse into subrepos automatically with an explicit path
Matt Harbison <matt_harbison@yahoo.com>
parents:
24874
diff
changeset
|
115 directory in a subrepo, it will be displayed even without |
63a57a2727b6
files: recurse into subrepos automatically with an explicit path
Matt Harbison <matt_harbison@yahoo.com>
parents:
24874
diff
changeset
|
116 -S/--subrepos being specified. Git and Subversion subrepositories |
63a57a2727b6
files: recurse into subrepos automatically with an explicit path
Matt Harbison <matt_harbison@yahoo.com>
parents:
24874
diff
changeset
|
117 are currently silently ignored. |
24413
a8595176dd64
subrepo: add basic support to hgsubrepo for the files command
Matt Harbison <matt_harbison@yahoo.com>
parents:
24174
diff
changeset
|
118 |
15474
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
119 :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
|
120 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
|
121 |
12828 | 122 :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
|
123 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
|
124 silently ignored. |
12828 | 125 |
126 :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
|
127 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
|
128 silently ignored. |
12828 | 129 |
130 :pull: pull is not recursive since it is not clear what to pull prior | |
131 to running :hg:`update`. Listing and retrieving all | |
132 subrepositories changes referenced by the parent repository pulled | |
133 changesets is expensive at best, impossible in the Subversion | |
134 case. | |
135 | |
136 :push: Mercurial will automatically push all subrepositories first | |
137 when the parent repository is being pushed. This ensures new | |
138 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
|
139 repositories. Push is a no-op for Subversion subrepositories. |
12828 | 140 |
32005
2406dbba49bd
serve: add support for Mercurial subrepositories
Matt Harbison <matt_harbison@yahoo.com>
parents:
25228
diff
changeset
|
141 :serve: serve does not recurse into subrepositories unless |
2406dbba49bd
serve: add support for Mercurial subrepositories
Matt Harbison <matt_harbison@yahoo.com>
parents:
25228
diff
changeset
|
142 -S/--subrepos is specified. Git and Subversion subrepositories |
2406dbba49bd
serve: add support for Mercurial subrepositories
Matt Harbison <matt_harbison@yahoo.com>
parents:
25228
diff
changeset
|
143 are currently silently ignored. |
2406dbba49bd
serve: add support for Mercurial subrepositories
Matt Harbison <matt_harbison@yahoo.com>
parents:
25228
diff
changeset
|
144 |
12828 | 145 :status: status does not recurse into subrepositories unless |
146 -S/--subrepos is specified. Subrepository changes are displayed as | |
147 regular Mercurial changes on the subrepository | |
148 elements. Subversion subrepositories are currently silently | |
149 ignored. | |
150 | |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
151 :remove: remove does not recurse into subrepositories unless |
23326
f6b8d23492e5
remove: support remove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23325
diff
changeset
|
152 -S/--subrepos is specified. However, if you specify a file or |
f6b8d23492e5
remove: support remove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23325
diff
changeset
|
153 directory path in a subrepo, it will be removed even without |
f6b8d23492e5
remove: support remove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23325
diff
changeset
|
154 -S/--subrepos. Git and Subversion subrepositories are currently |
f6b8d23492e5
remove: support remove with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
23325
diff
changeset
|
155 silently ignored. |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
156 |
12828 | 157 :update: update restores the subrepos in the state they were |
158 originally committed in target changeset. If the recorded | |
159 changeset is not available in the current subrepository, Mercurial | |
160 will pull it in first before updating. This means that updating | |
161 can require network access when using subrepositories. | |
162 | |
163 Remapping Subrepositories Sources | |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
164 ================================= |
12828 | 165 |
166 A subrepository source location may change during a project life, | |
167 invalidating references stored in the parent repository history. To | |
168 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
169 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
170 hgrc(5) for more details. | |
171 |