blob: f187bfaf017aa04548ff4071e125220d15b19d7d [file] [log] [blame]
Shawn O. Pearce3e548192008-11-04 11:19:36 -08001repo Manifest Format
2====================
3
4A repo manifest describes the structure of a repo client; that is
5the directories that are visible and where they should be obtained
6from with git.
7
8The basic structure of a manifest is a bare Git repository holding
9a single 'default.xml' XML file in the top level directory.
10
11Manifests are inherently version controlled, since they are kept
12within a Git repository. Updates to manifests are automatically
13obtained by clients during `repo sync`.
14
15
16XML File Format
17---------------
18
19A manifest XML file (e.g. 'default.xml') roughly conforms to the
20following DTD:
21
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080022 <!DOCTYPE manifest [
Doug Anderson2b8db3c2010-11-01 15:08:06 -070023 <!ELEMENT manifest (notice?,
24 remote*,
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080025 default?,
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -070026 manifest-server?,
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080027 remove-project*,
Doug Anderson37282b42011-03-04 11:54:18 -080028 project*,
29 repo-hooks?)>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053030
Doug Anderson2b8db3c2010-11-01 15:08:06 -070031 <!ELEMENT notice (#PCDATA)>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053032
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080033 <!ELEMENT remote (EMPTY)>
34 <!ATTLIST remote name ID #REQUIRED>
Yestin Sunb292b982012-07-02 07:32:50 -070035 <!ATTLIST remote alias CDATA #IMPLIED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080036 <!ATTLIST remote fetch CDATA #REQUIRED>
37 <!ATTLIST remote review CDATA #IMPLIED>
Anthony King36ea2fb2014-05-06 11:54:01 +010038 <!ATTLIST remote revision CDATA #IMPLIED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053039
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080040 <!ELEMENT default (EMPTY)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040041 <!ATTLIST default remote IDREF #IMPLIED>
42 <!ATTLIST default revision CDATA #IMPLIED>
43 <!ATTLIST default dest-branch CDATA #IMPLIED>
44 <!ATTLIST default sync-j CDATA #IMPLIED>
45 <!ATTLIST default sync-c CDATA #IMPLIED>
46 <!ATTLIST default sync-s CDATA #IMPLIED>
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -070047
48 <!ELEMENT manifest-server (EMPTY)>
49 <!ATTLIST url CDATA #REQUIRED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053050
Warren Turkal53d6a7b2013-12-10 15:30:03 -080051 <!ELEMENT project (annotation*,
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +080052 project*)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040053 <!ATTLIST project name CDATA #REQUIRED>
54 <!ATTLIST project path CDATA #IMPLIED>
55 <!ATTLIST project remote IDREF #IMPLIED>
56 <!ATTLIST project revision CDATA #IMPLIED>
57 <!ATTLIST project dest-branch CDATA #IMPLIED>
58 <!ATTLIST project groups CDATA #IMPLIED>
59 <!ATTLIST project sync-c CDATA #IMPLIED>
60 <!ATTLIST project sync-s CDATA #IMPLIED>
David Pursehouse4e465202012-11-27 22:20:10 +090061 <!ATTLIST project upstream CDATA #IMPLIED>
David Pursehouseede7f122012-11-27 22:25:30 +090062 <!ATTLIST project clone-depth CDATA #IMPLIED>
Scott Fandb83b1b2013-02-28 09:34:14 +080063 <!ATTLIST project force-path CDATA #IMPLIED>
James W. Mills24c13082012-04-12 15:04:13 -050064
65 <!ELEMENT annotation (EMPTY)>
66 <!ATTLIST annotation name CDATA #REQUIRED>
67 <!ATTLIST annotation value CDATA #REQUIRED>
68 <!ATTLIST annotation keep CDATA "true">
Chirayu Desaid5a5b192013-11-21 19:15:30 +053069
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080070 <!ELEMENT remove-project (EMPTY)>
71 <!ATTLIST remove-project name CDATA #REQUIRED>
Doug Anderson37282b42011-03-04 11:54:18 -080072
73 <!ELEMENT repo-hooks (EMPTY)>
74 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
75 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
Brian Harring26448742011-04-28 05:04:41 -070076
77 <!ELEMENT include (EMPTY)>
78 <!ATTLIST include name CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080079 ]>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080080
81A description of the elements and their attributes follows.
82
83
84Element manifest
85----------------
86
87The root element of the file.
88
89
90Element remote
91--------------
92
93One or more remote elements may be specified. Each remote element
94specifies a Git URL shared by one or more projects and (optionally)
95the Gerrit review server those projects upload changes through.
96
97Attribute `name`: A short name unique to this manifest file. The
98name specified here is used as the remote name in each project's
99.git/config, and is therefore automatically available to commands
100like `git fetch`, `git remote`, `git pull` and `git push`.
101
Yestin Sunb292b982012-07-02 07:32:50 -0700102Attribute `alias`: The alias, if specified, is used to override
103`name` to be set as the remote name in each project's .git/config.
104Its value can be duplicated while attribute `name` has to be unique
105in the manifest file. This helps each project to be able to have
106same remote name which actually points to different remote url.
107
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800108Attribute `fetch`: The Git URL prefix for all projects which use
109this remote. Each project's name is appended to this prefix to
110form the actual URL used to clone the project.
111
112Attribute `review`: Hostname of the Gerrit server where reviews
113are uploaded to by `repo upload`. This attribute is optional;
114if not specified then `repo upload` will not function.
115
Anthony King36ea2fb2014-05-06 11:54:01 +0100116Attribute `revision`: Name of a Git branch (e.g. `master` or
117`refs/heads/master`). Remotes with their own revision will override
118the default revision.
119
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800120Element default
121---------------
122
123At most one default element may be specified. Its remote and
124revision attributes are used when a project element does not
125specify its own remote or revision attribute.
126
127Attribute `remote`: Name of a previously defined remote element.
128Project elements lacking a remote attribute of their own will use
129this remote.
130
131Attribute `revision`: Name of a Git branch (e.g. `master` or
132`refs/heads/master`). Project elements lacking their own
133revision attribute will use this revision.
134
Bryan Jacobsf609f912013-05-06 13:36:24 -0400135Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
136Project elements not setting their own `dest-branch` will inherit
137this value. If this value is not set, projects will use `revision`
138by default instead.
139
David Pursehouse4e465202012-11-27 22:20:10 +0900140Attribute `sync_j`: Number of parallel jobs to use when synching.
141
142Attribute `sync_c`: Set to true to only sync the given Git
143branch (specified in the `revision` attribute) rather than the
144whole ref space. Project elements lacking a sync_c element of
145their own will use this value.
146
147Attribute `sync_s`: Set to true to also sync sub-projects.
148
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800149
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700150Element manifest-server
151-----------------------
152
153At most one manifest-server may be specified. The url attribute
154is used to specify the URL of a manifest server, which is an
David Pursehouse9a27d012012-08-21 14:23:49 +0900155XML RPC service.
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700156
David Pursehouse9a27d012012-08-21 14:23:49 +0900157The manifest server should implement the following RPC methods:
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700158
159 GetApprovedManifest(branch, target)
160
David Pursehouse9a27d012012-08-21 14:23:49 +0900161Return a manifest in which each project is pegged to a known good revision
162for the current branch and target.
163
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700164The target to use is defined by environment variables TARGET_PRODUCT
165and TARGET_BUILD_VARIANT. These variables are used to create a string
166of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug.
167If one of those variables or both are not present, the program will call
David Pursehousedaa851f2012-08-21 13:52:18 +0900168GetApprovedManifest without the target parameter and the manifest server
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700169should choose a reasonable default target.
170
David Pursehouse9a27d012012-08-21 14:23:49 +0900171 GetManifest(tag)
172
173Return a manifest in which each project is pegged to the revision at
174the specified tag.
175
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700176
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800177Element project
178---------------
179
180One or more project elements may be specified. Each element
181describes a single Git repository to be cloned into the repo
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800182client workspace. You may specify Git-submodules by creating a
183nested project. Git-submodules will be automatically
184recognized and inherit their parent's attributes, but those
185may be overridden by an explicitly specified project element.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800186
187Attribute `name`: A unique name for this project. The project's
188name is appended onto its remote's fetch URL to generate the actual
189URL to configure the Git remote with. The URL gets formed as:
190
191 ${remote_fetch}/${project_name}.git
192
193where ${remote_fetch} is the remote's fetch attribute and
194${project_name} is the project's name attribute. The suffix ".git"
David Pursehousedaa851f2012-08-21 13:52:18 +0900195is always appended as repo assumes the upstream is a forest of
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800196bare Git repositories. If the project has a parent element, its
197name will be prefixed by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800198
199The project name must match the name Gerrit knows, if Gerrit is
200being used for code reviews.
201
202Attribute `path`: An optional path relative to the top directory
203of the repo client where the Git working directory for this project
204should be placed. If not supplied the project name is used.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800205If the project has a parent element, its path will be prefixed
206by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800207
208Attribute `remote`: Name of a previously defined remote element.
209If not supplied the remote given by the default element is used.
210
211Attribute `revision`: Name of the Git branch the manifest wants
212to track for this project. Names can be relative to refs/heads
213(e.g. just "master") or absolute (e.g. "refs/heads/master").
214Tags and/or explicit SHA-1s should work in theory, but have not
215been extensively tested. If not supplied the revision given by
Anthony King36ea2fb2014-05-06 11:54:01 +0100216the remote element is used if applicable, else the default
217element is used.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800218
Bryan Jacobsf609f912013-05-06 13:36:24 -0400219Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
220When using `repo upload`, changes will be submitted for code
221review on this branch. If unspecified both here and in the
222default element, `revision` is used instead.
223
Colin Cross5acde752012-03-28 20:15:45 -0700224Attribute `groups`: List of groups to which this project belongs,
Conley Owens971de8e2012-04-16 10:36:08 -0700225whitespace or comma separated. All projects belong to the group
Conley Owensbb1b5f52012-08-13 13:11:18 -0700226"all", and each project automatically belongs to a group of
227its name:`name` and path:`path`. E.g. for
Brian Harring7da13142012-06-15 02:24:20 -0700228<project name="monkeys" path="barrel-of"/>, that project
229definition is implicitly in the following manifest groups:
Conley Owensbb1b5f52012-08-13 13:11:18 -0700230default, name:monkeys, and path:barrel-of. If you place a project in the
231group "notdefault", it will not be automatically downloaded by repo.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800232If the project has a parent element, the `name` and `path` here
233are the prefixed ones.
Colin Cross5acde752012-03-28 20:15:45 -0700234
David Pursehouse4e465202012-11-27 22:20:10 +0900235Attribute `sync_c`: Set to true to only sync the given Git
236branch (specified in the `revision` attribute) rather than the
237whole ref space.
238
239Attribute `sync_s`: Set to true to also sync sub-projects.
240
241Attribute `upstream`: Name of the Git branch in which a sha1
242can be found. Used when syncing a revision locked manifest in
243-c mode to avoid having to sync the entire ref space.
244
David Pursehouseede7f122012-11-27 22:25:30 +0900245Attribute `clone-depth`: Set the depth to use when fetching this
246project. If specified, this value will override any value given
247to repo init with the --depth option on the command line.
248
Scott Fandb83b1b2013-02-28 09:34:14 +0800249Attribute `force-path`: Set to true to force this project to create the
250local mirror repository according to its `path` attribute (if supplied)
251rather than the `name` attribute. This attribute only applies to the
252local mirrors syncing, it will be ignored when syncing the projects in a
253client working directory.
254
James W. Mills24c13082012-04-12 15:04:13 -0500255Element annotation
256------------------
257
258Zero or more annotation elements may be specified as children of a
259project element. Each element describes a name-value pair that will be
260exported into each project's environment during a 'forall' command,
261prefixed with REPO__. In addition, there is an optional attribute
262"keep" which accepts the case insensitive values "true" (default) or
263"false". This attribute determines whether or not the annotation will
264be kept when exported with the manifest subcommand.
265
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800266Element remove-project
267----------------------
268
269Deletes the named project from the internal manifest table, possibly
270allowing a subsequent project element in the same manifest file to
271replace the project with a different source.
272
David Pursehouseb1525bf2012-11-14 08:51:38 +0900273This element is mostly useful in a local manifest file, where
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800274the user can remove a project, and possibly replace it with their
275own definition.
276
Brian Harring26448742011-04-28 05:04:41 -0700277Element include
278---------------
279
280This element provides the capability of including another manifest
281file into the originating manifest. Normal rules apply for the
David Pursehouse9f3406e2012-11-14 08:52:25 +0900282target manifest to include - it must be a usable manifest on its own.
Brian Harring26448742011-04-28 05:04:41 -0700283
David Pursehouse9f3406e2012-11-14 08:52:25 +0900284Attribute `name`: the manifest to include, specified relative to
285the manifest repository's root.
Brian Harring26448742011-04-28 05:04:41 -0700286
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800287
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900288Local Manifests
289===============
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800290
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900291Additional remotes and projects may be added through local manifest
292files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800293
294For example:
295
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900296 $ ls .repo/local_manifests
297 local_manifest.xml
298 another_local_manifest.xml
299
300 $ cat .repo/local_manifests/local_manifest.xml
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -0800301 <?xml version="1.0" encoding="UTF-8"?>
302 <manifest>
303 <project path="manifest"
304 name="tools/manifest" />
305 <project path="platform-manifest"
306 name="platform/manifest" />
307 </manifest>
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800308
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900309Users may add projects to the local manifest(s) prior to a `repo sync`
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800310invocation, instructing repo to automatically download and manage
311these extra projects.
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900312
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900313Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will
314be loaded in alphabetical order.
315
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900316Additional remotes and projects may also be added through a local
David Pursehouse5566ae52012-11-13 03:04:18 +0900317manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method
318is deprecated in favor of using multiple manifest files as mentioned
319above.
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900320
321If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before
322any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.