blob: 1aa93965b9d51c668952604218877baaae387ad9 [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*,
Josh Triplett884a3872014-06-12 14:57:29 -070029 extend-project*,
Doug Anderson37282b42011-03-04 11:54:18 -080030 repo-hooks?)>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053031
Doug Anderson2b8db3c2010-11-01 15:08:06 -070032 <!ELEMENT notice (#PCDATA)>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053033
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080034 <!ELEMENT remote (EMPTY)>
35 <!ATTLIST remote name ID #REQUIRED>
Yestin Sunb292b982012-07-02 07:32:50 -070036 <!ATTLIST remote alias CDATA #IMPLIED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080037 <!ATTLIST remote fetch CDATA #REQUIRED>
38 <!ATTLIST remote review CDATA #IMPLIED>
Anthony King36ea2fb2014-05-06 11:54:01 +010039 <!ATTLIST remote revision CDATA #IMPLIED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053040
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080041 <!ELEMENT default (EMPTY)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040042 <!ATTLIST default remote IDREF #IMPLIED>
43 <!ATTLIST default revision CDATA #IMPLIED>
44 <!ATTLIST default dest-branch CDATA #IMPLIED>
45 <!ATTLIST default sync-j CDATA #IMPLIED>
46 <!ATTLIST default sync-c CDATA #IMPLIED>
47 <!ATTLIST default sync-s CDATA #IMPLIED>
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -070048
49 <!ELEMENT manifest-server (EMPTY)>
50 <!ATTLIST url CDATA #REQUIRED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053051
Warren Turkal53d6a7b2013-12-10 15:30:03 -080052 <!ELEMENT project (annotation*,
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +080053 project*)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040054 <!ATTLIST project name CDATA #REQUIRED>
55 <!ATTLIST project path CDATA #IMPLIED>
56 <!ATTLIST project remote IDREF #IMPLIED>
57 <!ATTLIST project revision CDATA #IMPLIED>
58 <!ATTLIST project dest-branch CDATA #IMPLIED>
59 <!ATTLIST project groups CDATA #IMPLIED>
60 <!ATTLIST project sync-c CDATA #IMPLIED>
61 <!ATTLIST project sync-s CDATA #IMPLIED>
David Pursehouse4e465202012-11-27 22:20:10 +090062 <!ATTLIST project upstream CDATA #IMPLIED>
David Pursehouseede7f122012-11-27 22:25:30 +090063 <!ATTLIST project clone-depth CDATA #IMPLIED>
Scott Fandb83b1b2013-02-28 09:34:14 +080064 <!ATTLIST project force-path CDATA #IMPLIED>
James W. Mills24c13082012-04-12 15:04:13 -050065
66 <!ELEMENT annotation (EMPTY)>
67 <!ATTLIST annotation name CDATA #REQUIRED>
68 <!ATTLIST annotation value CDATA #REQUIRED>
69 <!ATTLIST annotation keep CDATA "true">
Chirayu Desaid5a5b192013-11-21 19:15:30 +053070
Josh Triplett884a3872014-06-12 14:57:29 -070071 <!ELEMENT extend-project>
72 <!ATTLIST extend-project name CDATA #REQUIRED>
73 <!ATTLIST extend-project path CDATA #IMPLIED>
74 <!ATTLIST extend-project groups CDATA #IMPLIED>
75
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080076 <!ELEMENT remove-project (EMPTY)>
77 <!ATTLIST remove-project name CDATA #REQUIRED>
Doug Anderson37282b42011-03-04 11:54:18 -080078
79 <!ELEMENT repo-hooks (EMPTY)>
80 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
81 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
Brian Harring26448742011-04-28 05:04:41 -070082
83 <!ELEMENT include (EMPTY)>
84 <!ATTLIST include name CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080085 ]>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080086
87A description of the elements and their attributes follows.
88
89
90Element manifest
91----------------
92
93The root element of the file.
94
95
96Element remote
97--------------
98
99One or more remote elements may be specified. Each remote element
100specifies a Git URL shared by one or more projects and (optionally)
101the Gerrit review server those projects upload changes through.
102
103Attribute `name`: A short name unique to this manifest file. The
104name specified here is used as the remote name in each project's
105.git/config, and is therefore automatically available to commands
106like `git fetch`, `git remote`, `git pull` and `git push`.
107
Yestin Sunb292b982012-07-02 07:32:50 -0700108Attribute `alias`: The alias, if specified, is used to override
109`name` to be set as the remote name in each project's .git/config.
110Its value can be duplicated while attribute `name` has to be unique
111in the manifest file. This helps each project to be able to have
112same remote name which actually points to different remote url.
113
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800114Attribute `fetch`: The Git URL prefix for all projects which use
115this remote. Each project's name is appended to this prefix to
116form the actual URL used to clone the project.
117
118Attribute `review`: Hostname of the Gerrit server where reviews
119are uploaded to by `repo upload`. This attribute is optional;
120if not specified then `repo upload` will not function.
121
Anthony King36ea2fb2014-05-06 11:54:01 +0100122Attribute `revision`: Name of a Git branch (e.g. `master` or
123`refs/heads/master`). Remotes with their own revision will override
124the default revision.
125
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800126Element default
127---------------
128
129At most one default element may be specified. Its remote and
130revision attributes are used when a project element does not
131specify its own remote or revision attribute.
132
133Attribute `remote`: Name of a previously defined remote element.
134Project elements lacking a remote attribute of their own will use
135this remote.
136
137Attribute `revision`: Name of a Git branch (e.g. `master` or
138`refs/heads/master`). Project elements lacking their own
139revision attribute will use this revision.
140
Bryan Jacobsf609f912013-05-06 13:36:24 -0400141Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
142Project elements not setting their own `dest-branch` will inherit
143this value. If this value is not set, projects will use `revision`
144by default instead.
145
Mani Chandel7a91d512014-07-24 16:27:08 +0530146Attribute `sync-j`: Number of parallel jobs to use when synching.
David Pursehouse4e465202012-11-27 22:20:10 +0900147
Mani Chandel7a91d512014-07-24 16:27:08 +0530148Attribute `sync-c`: Set to true to only sync the given Git
David Pursehouse4e465202012-11-27 22:20:10 +0900149branch (specified in the `revision` attribute) rather than the
Mani Chandel7a91d512014-07-24 16:27:08 +0530150whole ref space. Project elements lacking a sync-c element of
David Pursehouse4e465202012-11-27 22:20:10 +0900151their own will use this value.
152
Mani Chandel7a91d512014-07-24 16:27:08 +0530153Attribute `sync-s`: Set to true to also sync sub-projects.
David Pursehouse4e465202012-11-27 22:20:10 +0900154
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800155
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700156Element manifest-server
157-----------------------
158
159At most one manifest-server may be specified. The url attribute
160is used to specify the URL of a manifest server, which is an
David Pursehouse9a27d012012-08-21 14:23:49 +0900161XML RPC service.
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700162
David Pursehouse9a27d012012-08-21 14:23:49 +0900163The manifest server should implement the following RPC methods:
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700164
165 GetApprovedManifest(branch, target)
166
David Pursehouse9a27d012012-08-21 14:23:49 +0900167Return a manifest in which each project is pegged to a known good revision
168for the current branch and target.
169
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700170The target to use is defined by environment variables TARGET_PRODUCT
171and TARGET_BUILD_VARIANT. These variables are used to create a string
172of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug.
173If one of those variables or both are not present, the program will call
David Pursehousedaa851f2012-08-21 13:52:18 +0900174GetApprovedManifest without the target parameter and the manifest server
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700175should choose a reasonable default target.
176
David Pursehouse9a27d012012-08-21 14:23:49 +0900177 GetManifest(tag)
178
179Return a manifest in which each project is pegged to the revision at
180the specified tag.
181
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700182
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800183Element project
184---------------
185
186One or more project elements may be specified. Each element
187describes a single Git repository to be cloned into the repo
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800188client workspace. You may specify Git-submodules by creating a
189nested project. Git-submodules will be automatically
190recognized and inherit their parent's attributes, but those
191may be overridden by an explicitly specified project element.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800192
193Attribute `name`: A unique name for this project. The project's
194name is appended onto its remote's fetch URL to generate the actual
195URL to configure the Git remote with. The URL gets formed as:
196
197 ${remote_fetch}/${project_name}.git
198
199where ${remote_fetch} is the remote's fetch attribute and
200${project_name} is the project's name attribute. The suffix ".git"
David Pursehousedaa851f2012-08-21 13:52:18 +0900201is always appended as repo assumes the upstream is a forest of
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800202bare Git repositories. If the project has a parent element, its
203name will be prefixed by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800204
205The project name must match the name Gerrit knows, if Gerrit is
206being used for code reviews.
207
208Attribute `path`: An optional path relative to the top directory
209of the repo client where the Git working directory for this project
210should be placed. If not supplied the project name is used.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800211If the project has a parent element, its path will be prefixed
212by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800213
214Attribute `remote`: Name of a previously defined remote element.
215If not supplied the remote given by the default element is used.
216
217Attribute `revision`: Name of the Git branch the manifest wants
218to track for this project. Names can be relative to refs/heads
219(e.g. just "master") or absolute (e.g. "refs/heads/master").
220Tags and/or explicit SHA-1s should work in theory, but have not
221been extensively tested. If not supplied the revision given by
Anthony King36ea2fb2014-05-06 11:54:01 +0100222the remote element is used if applicable, else the default
223element is used.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800224
Bryan Jacobsf609f912013-05-06 13:36:24 -0400225Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
226When using `repo upload`, changes will be submitted for code
227review on this branch. If unspecified both here and in the
228default element, `revision` is used instead.
229
Colin Cross5acde752012-03-28 20:15:45 -0700230Attribute `groups`: List of groups to which this project belongs,
Conley Owens971de8e2012-04-16 10:36:08 -0700231whitespace or comma separated. All projects belong to the group
Conley Owensbb1b5f52012-08-13 13:11:18 -0700232"all", and each project automatically belongs to a group of
233its name:`name` and path:`path`. E.g. for
Brian Harring7da13142012-06-15 02:24:20 -0700234<project name="monkeys" path="barrel-of"/>, that project
235definition is implicitly in the following manifest groups:
Conley Owensbb1b5f52012-08-13 13:11:18 -0700236default, name:monkeys, and path:barrel-of. If you place a project in the
237group "notdefault", it will not be automatically downloaded by repo.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800238If the project has a parent element, the `name` and `path` here
239are the prefixed ones.
Colin Cross5acde752012-03-28 20:15:45 -0700240
Mani Chandel7a91d512014-07-24 16:27:08 +0530241Attribute `sync-c`: Set to true to only sync the given Git
David Pursehouse4e465202012-11-27 22:20:10 +0900242branch (specified in the `revision` attribute) rather than the
243whole ref space.
244
Mani Chandel7a91d512014-07-24 16:27:08 +0530245Attribute `sync-s`: Set to true to also sync sub-projects.
David Pursehouse4e465202012-11-27 22:20:10 +0900246
Nasser Grainawi909d58b2014-09-19 12:13:04 -0600247Attribute `upstream`: Name of the Git ref in which a sha1
David Pursehouse4e465202012-11-27 22:20:10 +0900248can be found. Used when syncing a revision locked manifest in
249-c mode to avoid having to sync the entire ref space.
250
David Pursehouseede7f122012-11-27 22:25:30 +0900251Attribute `clone-depth`: Set the depth to use when fetching this
252project. If specified, this value will override any value given
253to repo init with the --depth option on the command line.
254
Scott Fandb83b1b2013-02-28 09:34:14 +0800255Attribute `force-path`: Set to true to force this project to create the
256local mirror repository according to its `path` attribute (if supplied)
257rather than the `name` attribute. This attribute only applies to the
258local mirrors syncing, it will be ignored when syncing the projects in a
259client working directory.
260
Josh Triplett884a3872014-06-12 14:57:29 -0700261Element extend-project
262----------------------
263
264Modify the attributes of the named project.
265
266This element is mostly useful in a local manifest file, to modify the
267attributes of an existing project without completely replacing the
268existing project definition. This makes the local manifest more robust
269against changes to the original manifest.
270
271Attribute `path`: If specified, limit the change to projects checked out
272at the specified path, rather than all projects with the given name.
273
274Attribute `groups`: List of additional groups to which this project
275belongs. Same syntax as the corresponding element of `project`.
276
James W. Mills24c13082012-04-12 15:04:13 -0500277Element annotation
278------------------
279
280Zero or more annotation elements may be specified as children of a
281project element. Each element describes a name-value pair that will be
282exported into each project's environment during a 'forall' command,
283prefixed with REPO__. In addition, there is an optional attribute
284"keep" which accepts the case insensitive values "true" (default) or
285"false". This attribute determines whether or not the annotation will
286be kept when exported with the manifest subcommand.
287
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800288Element remove-project
289----------------------
290
291Deletes the named project from the internal manifest table, possibly
292allowing a subsequent project element in the same manifest file to
293replace the project with a different source.
294
David Pursehouseb1525bf2012-11-14 08:51:38 +0900295This element is mostly useful in a local manifest file, where
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800296the user can remove a project, and possibly replace it with their
297own definition.
298
Brian Harring26448742011-04-28 05:04:41 -0700299Element include
300---------------
301
302This element provides the capability of including another manifest
303file into the originating manifest. Normal rules apply for the
David Pursehouse9f3406e2012-11-14 08:52:25 +0900304target manifest to include - it must be a usable manifest on its own.
Brian Harring26448742011-04-28 05:04:41 -0700305
David Pursehouse9f3406e2012-11-14 08:52:25 +0900306Attribute `name`: the manifest to include, specified relative to
307the manifest repository's root.
Brian Harring26448742011-04-28 05:04:41 -0700308
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800309
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900310Local Manifests
311===============
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800312
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900313Additional remotes and projects may be added through local manifest
314files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800315
316For example:
317
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900318 $ ls .repo/local_manifests
319 local_manifest.xml
320 another_local_manifest.xml
321
322 $ cat .repo/local_manifests/local_manifest.xml
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -0800323 <?xml version="1.0" encoding="UTF-8"?>
324 <manifest>
325 <project path="manifest"
326 name="tools/manifest" />
327 <project path="platform-manifest"
328 name="platform/manifest" />
329 </manifest>
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800330
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900331Users may add projects to the local manifest(s) prior to a `repo sync`
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800332invocation, instructing repo to automatically download and manage
333these extra projects.
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900334
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900335Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will
336be loaded in alphabetical order.
337
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900338Additional remotes and projects may also be added through a local
David Pursehouse5566ae52012-11-13 03:04:18 +0900339manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method
340is deprecated in favor of using multiple manifest files as mentioned
341above.
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900342
343If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before
344any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.