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