Mercurial > hg
annotate mercurial/helptext/subrepos.txt @ 48598:a6f16ec07ed7
stream-clone: add a explicit test for format change during stream clone
They are different kind of requirements, the one which impact the data storage
and are relevant to the files being streamed and the one which does not. For
example some requirements are only relevant to the working copy, like sparse, or
dirstate-v2.
Since they are irrelevant to the content being streamed, they do not prevent the
receiving side to use streaming clone and mercurial skip adverting them over
the wire and, ideally, within the bundle.
In addition, this let the client decide to use whichever format it desire for
the part that does not affect the store itself. So the configuration related to
these format are used as normal when doing a streaming clone.
In practice, the feature was not really tested and is badly broken with bundle-2,
since the requirements are not filtered out from the stream bundle.
So we start with adding simple tests as a good base before the fix and adjust
the feature.
Differential Revision: https://phab.mercurial-scm.org/D12029
author | Pierre-Yves David <pierre-yves.david@octobus.net> |
---|---|
date | Mon, 17 Jan 2022 18:51:47 +0100 |
parents | 2e017696181f |
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 |