Mercurial > hg
annotate mercurial/help/subrepos.txt @ 15410:9e99d2bbb1b1
add: support adding explicit files in subrepos
Change the behavior of the add command such that explicit paths in
subrepos are always added. This eliminates the previous behavior
where if you called "hg add" for an explicit path in a subrepo
without specifying the -S option, it would be silently ignored.
If you specify patterns, or no arguments at all, the -S option
will still be needed to activate recursion into subrepos.
author | David M. Carr <david@carrclan.us> |
---|---|
date | Wed, 02 Nov 2011 01:17:11 -0400 |
parents | 15f15f3b405d |
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 | |
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. |
9e99d2bbb1b1
add: support adding explicit files in subrepos
David M. Carr <david@carrclan.us>
parents:
15213
diff
changeset
|
78 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 | |
85 entire project and its subrepositories. It does this by first | |
86 attempting to commit all modified subrepositories, then recording | |
13411
d4de90a612f7
commit: abort if a subrepo is modified and ui.commitsubrepos=no
Patrick Mezard <pmezard@gmail.com>
parents:
12860
diff
changeset
|
87 their state and finally committing it in the parent |
d4de90a612f7
commit: abort if a subrepo is modified and ui.commitsubrepos=no
Patrick Mezard <pmezard@gmail.com>
parents:
12860
diff
changeset
|
88 repository. Mercurial can be made to abort if any subrepository |
d4de90a612f7
commit: abort if a subrepo is modified and ui.commitsubrepos=no
Patrick Mezard <pmezard@gmail.com>
parents:
12860
diff
changeset
|
89 content is modified by setting "ui.commitsubrepos=no" in a |
d4de90a612f7
commit: abort if a subrepo is modified and ui.commitsubrepos=no
Patrick Mezard <pmezard@gmail.com>
parents:
12860
diff
changeset
|
90 configuration file (see :hg:`help config`). |
12828 | 91 |
92 :diff: diff does not recurse in subrepos unless -S/--subrepos is | |
93 specified. Changes are displayed as usual, on the subrepositories | |
94 elements. Subversion subrepositories are currently silently | |
95 ignored. | |
96 | |
97 :incoming: incoming does not recurse in subrepos unless -S/--subrepos | |
98 is specified. Subversion subrepositories are currently silently | |
99 ignored. | |
100 | |
101 :outgoing: outgoing does not recurse in subrepos unless -S/--subrepos | |
102 is specified. Subversion subrepositories are currently silently | |
103 ignored. | |
104 | |
105 :pull: pull is not recursive since it is not clear what to pull prior | |
106 to running :hg:`update`. Listing and retrieving all | |
107 subrepositories changes referenced by the parent repository pulled | |
108 changesets is expensive at best, impossible in the Subversion | |
109 case. | |
110 | |
111 :push: Mercurial will automatically push all subrepositories first | |
112 when the parent repository is being pushed. This ensures new | |
113 subrepository changes are available when referenced by top-level | |
114 repositories. | |
115 | |
116 :status: status does not recurse into subrepositories unless | |
117 -S/--subrepos is specified. Subrepository changes are displayed as | |
118 regular Mercurial changes on the subrepository | |
119 elements. Subversion subrepositories are currently silently | |
120 ignored. | |
121 | |
122 :update: update restores the subrepos in the state they were | |
123 originally committed in target changeset. If the recorded | |
124 changeset is not available in the current subrepository, Mercurial | |
125 will pull it in first before updating. This means that updating | |
126 can require network access when using subrepositories. | |
127 | |
128 Remapping Subrepositories Sources | |
129 --------------------------------- | |
130 | |
131 A subrepository source location may change during a project life, | |
132 invalidating references stored in the parent repository history. To | |
133 fix this, rewriting rules can be defined in parent repository ``hgrc`` | |
134 file or in Mercurial configuration. See the ``[subpaths]`` section in | |
135 hgrc(5) for more details. | |
136 |