Mercurial > hg
annotate mercurial/help/subrepos.txt @ 15662:06671371e634 stable
progress: check for ui.quiet and ui.debugflag before we write
ui.quiet and ui.debugflag are not initialized during uisetup and
reposetup. progressui is always initialized, therefore we have to check
during write() if ui.quiet is set or not.
author | David Soria Parra <dsp@php.net> |
---|---|
date | Wed, 14 Dec 2011 15:41:08 +0100 |
parents | e48f0913f018 |
children | 2ddae301d0a2 |
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 | |
15428
da81da6caa6b
subrepo: improve help for git subrepo support
David M. Carr <david@carrclan.us>
parents:
15427
diff
changeset
|
76 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
|
77 silently ignored. |
12828 | 78 |
79 :archive: archive does not recurse in subrepositories unless | |
80 -S/--subrepos is specified. | |
81 | |
82 :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
|
83 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
|
84 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
|
85 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
|
86 -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
|
87 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
|
88 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
|
89 finally commits it in the parent repository. |
12828 | 90 |
91 :diff: diff does not recurse in subrepos unless -S/--subrepos is | |
92 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
|
93 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
|
94 silently ignored. |
12828 | 95 |
96 :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
|
97 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
|
98 silently ignored. |
12828 | 99 |
100 :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
|
101 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
|
102 silently ignored. |
12828 | 103 |
104 :pull: pull is not recursive since it is not clear what to pull prior | |
105 to running :hg:`update`. Listing and retrieving all | |
106 subrepositories changes referenced by the parent repository pulled | |
107 changesets is expensive at best, impossible in the Subversion | |
108 case. | |
109 | |
110 :push: Mercurial will automatically push all subrepositories first | |
111 when the parent repository is being pushed. This ensures new | |
112 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
|
113 repositories. Push is a no-op for Subversion subrepositories. |
12828 | 114 |
115 :status: status does not recurse into subrepositories unless | |
116 -S/--subrepos is specified. Subrepository changes are displayed as | |
117 regular Mercurial changes on the subrepository | |
118 elements. Subversion subrepositories are currently silently | |
119 ignored. | |
120 | |
121 :update: update restores the subrepos in the state they were | |
122 originally committed in target changeset. If the recorded | |
123 changeset is not available in the current subrepository, Mercurial | |
124 will pull it in first before updating. This means that updating | |
125 can require network access when using subrepositories. | |
126 | |
127 Remapping Subrepositories Sources | |
128 --------------------------------- | |
129 | |
130 A subrepository source location may change during a project life, | |
131 invalidating references stored in the parent repository history. To | |
132 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
133 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
134 hgrc(5) for more details. | |
135 |