Mercurial > hg
annotate mercurial/help/subrepos.txt @ 23325:4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Like 'forget', git and svn subrepos are currently not supported. Unfortunately
the name 'remove' is already used in the subrepo classes, so we break the
convention of naming the subrepo function after the command.
author | Matt Harbison <matt_harbison@yahoo.com> |
---|---|
date | Sat, 15 Nov 2014 21:36:19 -0500 |
parents | a2cc3c08c3ac |
children | f6b8d23492e5 |
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. |
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 | |
21041
a2cc3c08c3ac
cat: support cat with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
20532
diff
changeset
|
87 :cat: cat currently only handles exact file matches in subrepos. |
a2cc3c08c3ac
cat: support cat with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
20532
diff
changeset
|
88 Git and Subversion subrepositories are currently ignored. |
a2cc3c08c3ac
cat: support cat with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
20532
diff
changeset
|
89 |
12828 | 90 :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
|
91 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
|
92 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
|
93 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
|
94 -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
|
95 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
|
96 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
|
97 finally commits it in the parent repository. |
12828 | 98 |
99 :diff: diff does not recurse in subrepos unless -S/--subrepos is | |
100 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
|
101 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
|
102 silently ignored. |
12828 | 103 |
15474
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
104 :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
|
105 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
|
106 |
12828 | 107 :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
|
108 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
|
109 silently ignored. |
12828 | 110 |
111 :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
|
112 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
|
113 silently ignored. |
12828 | 114 |
115 :pull: pull is not recursive since it is not clear what to pull prior | |
116 to running :hg:`update`. Listing and retrieving all | |
117 subrepositories changes referenced by the parent repository pulled | |
118 changesets is expensive at best, impossible in the Subversion | |
119 case. | |
120 | |
121 :push: Mercurial will automatically push all subrepositories first | |
122 when the parent repository is being pushed. This ensures new | |
123 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
|
124 repositories. Push is a no-op for Subversion subrepositories. |
12828 | 125 |
126 :status: status does not recurse into subrepositories unless | |
127 -S/--subrepos is specified. Subrepository changes are displayed as | |
128 regular Mercurial changes on the subrepository | |
129 elements. Subversion subrepositories are currently silently | |
130 ignored. | |
131 | |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
132 :remove: remove does not recurse into subrepositories unless |
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
133 -S/--subrepos is specified. Git and Subversion subrepositories |
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
134 are currently silently ignored. |
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
135 |
12828 | 136 :update: update restores the subrepos in the state they were |
137 originally committed in target changeset. If the recorded | |
138 changeset is not available in the current subrepository, Mercurial | |
139 will pull it in first before updating. This means that updating | |
140 can require network access when using subrepositories. | |
141 | |
142 Remapping Subrepositories Sources | |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
143 ================================= |
12828 | 144 |
145 A subrepository source location may change during a project life, | |
146 invalidating references stored in the parent repository history. To | |
147 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
148 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
149 hgrc(5) for more details. | |
150 |