##// END OF EJS Templates
subrepo: update the help text to account for diff -I/-X gitsubrepo support...
Matt Harbison -
r24874:89fe9921 stable
parent child Browse files
Show More
@@ -1,164 +1,163 b''
1 1 Subrepositories let you nest external repositories or projects into a
2 2 parent Mercurial repository, and make commands operate on them as a
3 3 group.
4 4
5 5 Mercurial currently supports Mercurial, Git, and Subversion
6 6 subrepositories.
7 7
8 8 Subrepositories are made of three components:
9 9
10 10 1. Nested repository checkouts. They can appear anywhere in the
11 11 parent working directory.
12 12
13 13 2. Nested repository references. They are defined in ``.hgsub``, which
14 14 should be placed in the root of working directory, and
15 15 tell where the subrepository checkouts come from. Mercurial
16 16 subrepositories are referenced like::
17 17
18 18 path/to/nested = https://example.com/nested/repo/path
19 19
20 20 Git and Subversion subrepos are also supported::
21 21
22 22 path/to/nested = [git]git://example.com/nested/repo/path
23 23 path/to/nested = [svn]https://example.com/nested/trunk/path
24 24
25 25 where ``path/to/nested`` is the checkout location relatively to the
26 26 parent Mercurial root, and ``https://example.com/nested/repo/path``
27 27 is the source repository path. The source can also reference a
28 28 filesystem path.
29 29
30 30 Note that ``.hgsub`` does not exist by default in Mercurial
31 31 repositories, you have to create and add it to the parent
32 32 repository before using subrepositories.
33 33
34 34 3. Nested repository states. They are defined in ``.hgsubstate``, which
35 35 is placed in the root of working directory, and
36 36 capture whatever information is required to restore the
37 37 subrepositories to the state they were committed in a parent
38 38 repository changeset. Mercurial automatically record the nested
39 39 repositories states when committing in the parent repository.
40 40
41 41 .. note::
42 42
43 43 The ``.hgsubstate`` file should not be edited manually.
44 44
45 45
46 46 Adding a Subrepository
47 47 ======================
48 48
49 49 If ``.hgsub`` does not exist, create it and add it to the parent
50 50 repository. Clone or checkout the external projects where you want it
51 51 to live in the parent repository. Edit ``.hgsub`` and add the
52 52 subrepository entry as described above. At this point, the
53 53 subrepository is tracked and the next commit will record its state in
54 54 ``.hgsubstate`` and bind it to the committed changeset.
55 55
56 56 Synchronizing a Subrepository
57 57 =============================
58 58
59 59 Subrepos do not automatically track the latest changeset of their
60 60 sources. Instead, they are updated to the changeset that corresponds
61 61 with the changeset checked out in the top-level changeset. This is so
62 62 developers always get a consistent set of compatible code and
63 63 libraries when they update.
64 64
65 65 Thus, updating subrepos is a manual process. Simply check out target
66 66 subrepo at the desired revision, test in the top-level repo, then
67 67 commit in the parent repository to record the new combination.
68 68
69 69 Deleting a Subrepository
70 70 ========================
71 71
72 72 To remove a subrepository from the parent repository, delete its
73 73 reference from ``.hgsub``, then remove its files.
74 74
75 75 Interaction with Mercurial Commands
76 76 ===================================
77 77
78 78 :add: add does not recurse in subrepos unless -S/--subrepos is
79 79 specified. However, if you specify the full path of a file in a
80 80 subrepo, it will be added even without -S/--subrepos specified.
81 81 Subversion subrepositories are currently silently
82 82 ignored.
83 83
84 84 :addremove: addremove does not recurse into subrepos unless
85 85 -S/--subrepos is specified. However, if you specify the full
86 86 path of a directory in a subrepo, addremove will be performed on
87 87 it even without -S/--subrepos being specified. Git and
88 88 Subversion subrepositories will print a warning and continue.
89 89
90 90 :archive: archive does not recurse in subrepositories unless
91 91 -S/--subrepos is specified.
92 92
93 93 :cat: cat currently only handles exact file matches in subrepos.
94 94 Subversion subrepositories are currently ignored.
95 95
96 96 :commit: commit creates a consistent snapshot of the state of the
97 97 entire project and its subrepositories. If any subrepositories
98 98 have been modified, Mercurial will abort. Mercurial can be made
99 99 to instead commit all modified subrepositories by specifying
100 100 -S/--subrepos, or setting "ui.commitsubrepos=True" in a
101 101 configuration file (see :hg:`help config`). After there are no
102 102 longer any modified subrepositories, it records their state and
103 103 finally commits it in the parent repository. The --addremove
104 104 option also honors the -S/--subrepos option. However, Git and
105 105 Subversion subrepositories will print a warning and abort.
106 106
107 107 :diff: diff does not recurse in subrepos unless -S/--subrepos is
108 108 specified. Changes are displayed as usual, on the subrepositories
109 elements. Git subrepositories do not support --include/--exclude.
110 Subversion subrepositories are currently silently ignored.
109 elements. Subversion subrepositories are currently silently ignored.
111 110
112 111 :files: files does not recurse into subrepos unless -S/--subrepos is
113 112 specified. Git and Subversion subrepositories are currently
114 113 silently ignored.
115 114
116 115 :forget: forget currently only handles exact file matches in subrepos.
117 116 Git and Subversion subrepositories are currently silently ignored.
118 117
119 118 :incoming: incoming does not recurse in subrepos unless -S/--subrepos
120 119 is specified. Git and Subversion subrepositories are currently
121 120 silently ignored.
122 121
123 122 :outgoing: outgoing does not recurse in subrepos unless -S/--subrepos
124 123 is specified. Git and Subversion subrepositories are currently
125 124 silently ignored.
126 125
127 126 :pull: pull is not recursive since it is not clear what to pull prior
128 127 to running :hg:`update`. Listing and retrieving all
129 128 subrepositories changes referenced by the parent repository pulled
130 129 changesets is expensive at best, impossible in the Subversion
131 130 case.
132 131
133 132 :push: Mercurial will automatically push all subrepositories first
134 133 when the parent repository is being pushed. This ensures new
135 134 subrepository changes are available when referenced by top-level
136 135 repositories. Push is a no-op for Subversion subrepositories.
137 136
138 137 :status: status does not recurse into subrepositories unless
139 138 -S/--subrepos is specified. Subrepository changes are displayed as
140 139 regular Mercurial changes on the subrepository
141 140 elements. Subversion subrepositories are currently silently
142 141 ignored.
143 142
144 143 :remove: remove does not recurse into subrepositories unless
145 144 -S/--subrepos is specified. However, if you specify a file or
146 145 directory path in a subrepo, it will be removed even without
147 146 -S/--subrepos. Git and Subversion subrepositories are currently
148 147 silently ignored.
149 148
150 149 :update: update restores the subrepos in the state they were
151 150 originally committed in target changeset. If the recorded
152 151 changeset is not available in the current subrepository, Mercurial
153 152 will pull it in first before updating. This means that updating
154 153 can require network access when using subrepositories.
155 154
156 155 Remapping Subrepositories Sources
157 156 =================================
158 157
159 158 A subrepository source location may change during a project life,
160 159 invalidating references stored in the parent repository history. To
161 160 fix this, rewriting rules can be defined in parent repository ``hgrc``
162 161 file or in Mercurial configuration. See the ``[subpaths]`` section in
163 162 hgrc(5) for more details.
164 163
General Comments 0
You need to be logged in to leave comments. Login now