Mercurial > hg
annotate mercurial/help/subrepos.txt @ 35935:00b9e26d727b
sshpeer: establish SSH connection before class instantiation
We want to move the handshake to before peers are created so
we can instantiate a different peer class depending on the
results of the handshake. This necessitates moving the SSH
process invocation to outside the peer class.
As part of the code move, some variables were renamed for
clarity. util.popen4() returns stdin, stdout, and stderr in
their typical file descriptor order. However, stdin and stdout
were being mapped to "pipeo" and "pipei" respectively. "o"
for "stdin" and "i" for "stdout" is a bit confusing. Although
it does make sense for "output" and "input" from the perspective
of the client. But in the context of the new function, it makes
sense to refer to these as their file descriptor names.
In addition, the last use of self._path disappeared, so we stop
setting that attribute and we can delete the redundant URL
parsing necessary to set it.
Differential Revision: https://phab.mercurial-scm.org/D2031
author | Gregory Szorc <gregory.szorc@gmail.com> |
---|---|
date | Mon, 05 Feb 2018 14:05:59 -0800 |
parents | 27196b7fc1ac |
children | db26dbbee74d |
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 | |
108 specified. Changes are displayed as usual, on the subrepositories | |
24874
89fe9921511f
subrepo: update the help text to account for diff -I/-X gitsubrepo support
Matt Harbison <matt_harbison@yahoo.com>
parents:
24413
diff
changeset
|
109 elements. Subversion subrepositories are currently silently ignored. |
12828 | 110 |
24413
a8595176dd64
subrepo: add basic support to hgsubrepo for the files command
Matt Harbison <matt_harbison@yahoo.com>
parents:
24174
diff
changeset
|
111 :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
|
112 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
|
113 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
|
114 -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
|
115 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
|
116 |
15474
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
117 :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
|
118 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
|
119 |
12828 | 120 :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
|
121 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
|
122 silently ignored. |
12828 | 123 |
124 :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
|
125 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
|
126 silently ignored. |
12828 | 127 |
128 :pull: pull is not recursive since it is not clear what to pull prior | |
129 to running :hg:`update`. Listing and retrieving all | |
130 subrepositories changes referenced by the parent repository pulled | |
131 changesets is expensive at best, impossible in the Subversion | |
132 case. | |
133 | |
134 :push: Mercurial will automatically push all subrepositories first | |
135 when the parent repository is being pushed. This ensures new | |
136 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
|
137 repositories. Push is a no-op for Subversion subrepositories. |
12828 | 138 |
32005
2406dbba49bd
serve: add support for Mercurial subrepositories
Matt Harbison <matt_harbison@yahoo.com>
parents:
25228
diff
changeset
|
139 :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
|
140 -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
|
141 are currently silently ignored. |
2406dbba49bd
serve: add support for Mercurial subrepositories
Matt Harbison <matt_harbison@yahoo.com>
parents:
25228
diff
changeset
|
142 |
12828 | 143 :status: status does not recurse into subrepositories unless |
144 -S/--subrepos is specified. Subrepository changes are displayed as | |
145 regular Mercurial changes on the subrepository | |
146 elements. Subversion subrepositories are currently silently | |
147 ignored. | |
148 | |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
149 :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
|
150 -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
|
151 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
|
152 -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
|
153 silently ignored. |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
154 |
12828 | 155 :update: update restores the subrepos in the state they were |
156 originally committed in target changeset. If the recorded | |
157 changeset is not available in the current subrepository, Mercurial | |
158 will pull it in first before updating. This means that updating | |
159 can require network access when using subrepositories. | |
160 | |
161 Remapping Subrepositories Sources | |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
162 ================================= |
12828 | 163 |
164 A subrepository source location may change during a project life, | |
165 invalidating references stored in the parent repository history. To | |
166 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
167 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
168 hgrc(5) for more details. | |
169 |