Mercurial > hg
annotate mercurial/help/subrepos.txt @ 24283:ef22cfff7052
transaction: add a validation stage
The 'transaction' object can now be fed a 'validator' function. This function
will be run right before the transaction is closed to validate its content. The
target usage is hooks. The validation function is expected to raise an exception
when it wants to abort the transaction.
This only introduce the idea with a default no-op validator. Actual usage is in
the next changeset.
author | Pierre-Yves David <pierre-yves.david@fb.com> |
---|---|
date | Mon, 09 Mar 2015 22:43:36 -0700 |
parents | bd9f64ec891d |
children | a8595176dd64 |
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 | |
23523
01a8dfc79cdc
subrepo: add partial diff support for git subrepos
Mathias De Maré <mathias.demare@gmail.com>
parents:
23326
diff
changeset
|
109 elements. Git subrepositories do not support --include/--exclude. |
01a8dfc79cdc
subrepo: add partial diff support for git subrepos
Mathias De Maré <mathias.demare@gmail.com>
parents:
23326
diff
changeset
|
110 Subversion subrepositories are currently silently ignored. |
12828 | 111 |
15474
95174c381525
forget: support forgetting explicit paths in subrepos
David M. Carr <david@carrclan.us>
parents:
15432
diff
changeset
|
112 :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
|
113 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
|
114 |
12828 | 115 :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
|
116 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
|
117 silently ignored. |
12828 | 118 |
119 :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
|
120 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
|
121 silently ignored. |
12828 | 122 |
123 :pull: pull is not recursive since it is not clear what to pull prior | |
124 to running :hg:`update`. Listing and retrieving all | |
125 subrepositories changes referenced by the parent repository pulled | |
126 changesets is expensive at best, impossible in the Subversion | |
127 case. | |
128 | |
129 :push: Mercurial will automatically push all subrepositories first | |
130 when the parent repository is being pushed. This ensures new | |
131 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
|
132 repositories. Push is a no-op for Subversion subrepositories. |
12828 | 133 |
134 :status: status does not recurse into subrepositories unless | |
135 -S/--subrepos is specified. Subrepository changes are displayed as | |
136 regular Mercurial changes on the subrepository | |
137 elements. Subversion subrepositories are currently silently | |
138 ignored. | |
139 | |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
140 :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
|
141 -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
|
142 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
|
143 -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
|
144 silently ignored. |
23325
4165cfd67519
remove: recurse into subrepositories with --subrepos/-S flag
Matt Harbison <matt_harbison@yahoo.com>
parents:
21041
diff
changeset
|
145 |
12828 | 146 :update: update restores the subrepos in the state they were |
147 originally committed in target changeset. If the recorded | |
148 changeset is not available in the current subrepository, Mercurial | |
149 will pull it in first before updating. This means that updating | |
150 can require network access when using subrepositories. | |
151 | |
152 Remapping Subrepositories Sources | |
17267
979b107eaea2
doc: unify section level between help topics
FUJIWARA Katsunori <foozy@lares.dti.ne.jp>
parents:
16503
diff
changeset
|
153 ================================= |
12828 | 154 |
155 A subrepository source location may change during a project life, | |
156 invalidating references stored in the parent repository history. To | |
157 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
158 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
159 hgrc(5) for more details. | |
160 |