Mercurial > hg
annotate mercurial/help/subrepos.txt @ 24946:c44534209a0a
bookmarks: rename readcurrent to readactive (API)
Today, the terms 'active' and 'current' are interchangeably used throughout the
codebase in reference to the active bookmark (the bookmark that will be updated
with the next commit). This leads to confusion among developers and users.
This patch is part of a series to standardize the usage to 'active' throughout
the mercurial codebase and user interface.
author | Ryan McElroy <rmcelroy@fb.com> |
---|---|
date | Mon, 13 Apr 2015 23:03:13 -0700 |
parents | 89fe9921511f |
children | 63a57a2727b6 |
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 | |
21041
a2cc3c08c3ac
cat: support cat with explicit paths in subrepos
Matt Harbison <matt_harbison@yahoo.com>
parents:
20532
diff
changeset
|
93 :cat: cat currently only handles exact file matches in subrepos. |
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 |
a8595176dd64
subrepo: add basic support to hgsubrepo for the files command
Matt Harbison <matt_harbison@yahoo.com>
parents:
24174
diff
changeset
|
112 specified. Git and Subversion subrepositories are currently |
a8595176dd64
subrepo: add basic support to hgsubrepo for the files command
Matt Harbison <matt_harbison@yahoo.com>
parents:
24174
diff
changeset
|
113 silently ignored. |
a8595176dd64
subrepo: add basic support to hgsubrepo for the files command
Matt Harbison <matt_harbison@yahoo.com>
parents:
24174
diff
changeset
|
114 |
15474
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
115 :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
|
116 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
|
117 |
12828 | 118 :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
|
119 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
|
120 silently ignored. |
12828 | 121 |
122 :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
|
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 :pull: pull is not recursive since it is not clear what to pull prior | |
127 to running :hg:`update`. Listing and retrieving all | |
128 subrepositories changes referenced by the parent repository pulled | |
129 changesets is expensive at best, impossible in the Subversion | |
130 case. | |
131 | |
132 :push: Mercurial will automatically push all subrepositories first | |
133 when the parent repository is being pushed. This ensures new | |
134 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
|
135 repositories. Push is a no-op for Subversion subrepositories. |
12828 | 136 |
137 :status: status does not recurse into subrepositories unless | |
138 -S/--subrepos is specified. Subrepository changes are displayed as | |
139 regular Mercurial changes on the subrepository | |
140 elements. Subversion subrepositories are currently silently | |
141 ignored. | |
142 | |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
143 :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
|
144 -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
|
145 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
|
146 -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
|
147 silently ignored. |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
148 |
12828 | 149 :update: update restores the subrepos in the state they were |
150 originally committed in target changeset. If the recorded | |
151 changeset is not available in the current subrepository, Mercurial | |
152 will pull it in first before updating. This means that updating | |
153 can require network access when using subrepositories. | |
154 | |
155 Remapping Subrepositories Sources | |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
156 ================================= |
12828 | 157 |
158 A subrepository source location may change during a project life, | |
159 invalidating references stored in the parent repository history. To | |
160 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
161 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
162 hgrc(5) for more details. | |
163 |