Mercurial > hg
annotate mercurial/help/subrepos.txt @ 15427:2a3ab9e81a3e stable
subrepo: update help for commit to reflect new default behavior
Update the subrepo help to be consistent with the new default behavior,
which is to abort if any subrepo is dirty.
author | David M. Carr <david@carrclan.us> |
---|---|
date | Thu, 03 Nov 2011 23:11:40 -0400 |
parents | 15f15f3b405d |
children | da81da6caa6b |
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 | |
76 specified. Subversion subrepositories are currently silently | |
77 ignored. | |
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 | |
93 elements. Subversion subrepositories are currently silently | |
94 ignored. | |
95 | |
96 :incoming: incoming does not recurse in subrepos unless -S/--subrepos | |
97 is specified. Subversion subrepositories are currently silently | |
98 ignored. | |
99 | |
100 :outgoing: outgoing does not recurse in subrepos unless -S/--subrepos | |
101 is specified. Subversion subrepositories are currently silently | |
102 ignored. | |
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 | |
113 repositories. | |
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 |