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