Mercurial > hg
annotate mercurial/help/subrepos.txt @ 15432:2ddae301d0a2
merge with stable
author | Martin Geisler <mg@aragost.com> |
---|---|
date | Fri, 04 Nov 2011 10:39:04 +0100 |
parents | 9e99d2bbb1b1 e48f0913f018 |
children | 95174c381525 |
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 |
13 2. Nested repository references. They are defined in ``.hgsub`` and | |
14 tell where the subrepository checkouts come from. Mercurial | |
15 subrepositories are referenced like: | |
16 | |
17 path/to/nested = https://example.com/nested/repo/path | |
18 | |
15213
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
19 Git and Subversion subrepos are also supported: |
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
20 |
15f15f3b405d
subrepo: add git to the help topic
Matt Mackall <mpm@selenic.com>
parents:
13411
diff
changeset
|
21 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
|
22 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
|
23 |
12828 | 24 where ``path/to/nested`` is the checkout location relatively to the |
25 parent Mercurial root, and ``https://example.com/nested/repo/path`` | |
26 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
|
27 filesystem path. |
12828 | 28 |
29 Note that ``.hgsub`` does not exist by default in Mercurial | |
30 repositories, you have to create and add it to the parent | |
31 repository before using subrepositories. | |
32 | |
33 3. Nested repository states. They are defined in ``.hgsubstate`` and | |
34 capture whatever information is required to restore the | |
35 subrepositories to the state they were committed in a parent | |
36 repository changeset. Mercurial automatically record the nested | |
37 repositories states when committing in the parent repository. | |
38 | |
39 .. note:: | |
40 The ``.hgsubstate`` file should not be edited manually. | |
41 | |
42 | |
43 Adding a Subrepository | |
44 ---------------------- | |
45 | |
46 If ``.hgsub`` does not exist, create it and add it to the parent | |
47 repository. Clone or checkout the external projects where you want it | |
48 to live in the parent repository. Edit ``.hgsub`` and add the | |
49 subrepository entry as described above. At this point, the | |
50 subrepository is tracked and the next commit will record its state in | |
51 ``.hgsubstate`` and bind it to the committed changeset. | |
52 | |
53 Synchronizing a Subrepository | |
54 ----------------------------- | |
55 | |
56 Subrepos do not automatically track the latest changeset of their | |
57 sources. Instead, they are updated to the changeset that corresponds | |
58 with the changeset checked out in the top-level changeset. This is so | |
59 developers always get a consistent set of compatible code and | |
60 libraries when they update. | |
61 | |
62 Thus, updating subrepos is a manual process. Simply check out target | |
63 subrepo at the desired revision, test in the top-level repo, then | |
64 commit in the parent repository to record the new combination. | |
65 | |
66 Deleting a Subrepository | |
67 ------------------------ | |
68 | |
12860
db2ff771204d
help: correct tip about deleting a subrepository
Wagner Bruna <wbruna@softwareexpress.com.br>
parents:
12828
diff
changeset
|
69 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
|
70 reference from ``.hgsub``, then remove its files. |
12828 | 71 |
72 Interaction with Mercurial Commands | |
73 ----------------------------------- | |
74 | |
75 :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
|
76 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
|
77 subrepo, it will be added even without -S/--subrepos specified. |
15432 | 78 Git and Subversion subrepositories are currently silently |
12828 | 79 ignored. |
80 | |
81 :archive: archive does not recurse in subrepositories unless | |
82 -S/--subrepos is specified. | |
83 | |
84 :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
|
85 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
|
86 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
|
87 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
|
88 -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
|
89 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
|
90 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
|
91 finally commits it in the parent repository. |
12828 | 92 |
93 :diff: diff does not recurse in subrepos unless -S/--subrepos is | |
94 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
|
95 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
|
96 silently ignored. |
12828 | 97 |
98 :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
|
99 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
|
100 silently ignored. |
12828 | 101 |
102 :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
|
103 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
|
104 silently ignored. |
12828 | 105 |
106 :pull: pull is not recursive since it is not clear what to pull prior | |
107 to running :hg:`update`. Listing and retrieving all | |
108 subrepositories changes referenced by the parent repository pulled | |
109 changesets is expensive at best, impossible in the Subversion | |
110 case. | |
111 | |
112 :push: Mercurial will automatically push all subrepositories first | |
113 when the parent repository is being pushed. This ensures new | |
114 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
|
115 repositories. Push is a no-op for Subversion subrepositories. |
12828 | 116 |
117 :status: status does not recurse into subrepositories unless | |
118 -S/--subrepos is specified. Subrepository changes are displayed as | |
119 regular Mercurial changes on the subrepository | |
120 elements. Subversion subrepositories are currently silently | |
121 ignored. | |
122 | |
123 :update: update restores the subrepos in the state they were | |
124 originally committed in target changeset. If the recorded | |
125 changeset is not available in the current subrepository, Mercurial | |
126 will pull it in first before updating. This means that updating | |
127 can require network access when using subrepositories. | |
128 | |
129 Remapping Subrepositories Sources | |
130 --------------------------------- | |
131 | |
132 A subrepository source location may change during a project life, | |
133 invalidating references stored in the parent repository history. To | |
134 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
135 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
136 hgrc(5) for more details. | |
137 |