blob: 4484d8034b03352c53ef879e5cf0af6707b150df [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
Mike Frysinger04071c12016-12-28 16:07:16 -050034 <!ELEMENT remote EMPTY>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080035 <!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>
Steve Raed6480452016-08-10 15:00:00 -070038 <!ATTLIST remote pushurl CDATA #IMPLIED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080039 <!ATTLIST remote review CDATA #IMPLIED>
Anthony King36ea2fb2014-05-06 11:54:01 +010040 <!ATTLIST remote revision CDATA #IMPLIED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053041
Mike Frysinger04071c12016-12-28 16:07:16 -050042 <!ELEMENT default EMPTY>
Bryan Jacobsf609f912013-05-06 13:36:24 -040043 <!ATTLIST default remote IDREF #IMPLIED>
44 <!ATTLIST default revision CDATA #IMPLIED>
45 <!ATTLIST default dest-branch CDATA #IMPLIED>
46 <!ATTLIST default sync-j CDATA #IMPLIED>
47 <!ATTLIST default sync-c CDATA #IMPLIED>
48 <!ATTLIST default sync-s CDATA #IMPLIED>
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -070049
Mike Frysinger04071c12016-12-28 16:07:16 -050050 <!ELEMENT manifest-server EMPTY>
Kenny Ho827e5472015-10-22 20:59:42 +000051 <!ATTLIST manifest-server url CDATA #REQUIRED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053052
Warren Turkal53d6a7b2013-12-10 15:30:03 -080053 <!ELEMENT project (annotation*,
Ruslan Bilovol54527e72015-09-08 13:11:23 +030054 project*,
Kenny Ho827e5472015-10-22 20:59:42 +000055 copyfile*,
56 linkfile*)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040057 <!ATTLIST project name CDATA #REQUIRED>
58 <!ATTLIST project path CDATA #IMPLIED>
59 <!ATTLIST project remote IDREF #IMPLIED>
60 <!ATTLIST project revision CDATA #IMPLIED>
61 <!ATTLIST project dest-branch CDATA #IMPLIED>
62 <!ATTLIST project groups CDATA #IMPLIED>
63 <!ATTLIST project sync-c CDATA #IMPLIED>
64 <!ATTLIST project sync-s CDATA #IMPLIED>
David Pursehouse4e465202012-11-27 22:20:10 +090065 <!ATTLIST project upstream CDATA #IMPLIED>
David Pursehouseede7f122012-11-27 22:25:30 +090066 <!ATTLIST project clone-depth CDATA #IMPLIED>
Scott Fandb83b1b2013-02-28 09:34:14 +080067 <!ATTLIST project force-path CDATA #IMPLIED>
James W. Mills24c13082012-04-12 15:04:13 -050068
Mike Frysinger04071c12016-12-28 16:07:16 -050069 <!ELEMENT annotation EMPTY>
James W. Mills24c13082012-04-12 15:04:13 -050070 <!ATTLIST annotation name CDATA #REQUIRED>
71 <!ATTLIST annotation value CDATA #REQUIRED>
72 <!ATTLIST annotation keep CDATA "true">
Chirayu Desaid5a5b192013-11-21 19:15:30 +053073
Mike Frysinger04071c12016-12-28 16:07:16 -050074 <!ELEMENT copyfile EMPTY>
Kenny Ho827e5472015-10-22 20:59:42 +000075 <!ATTLIST copyfile src CDATA #REQUIRED>
76 <!ATTLIST copyfile dest CDATA #REQUIRED>
Ruslan Bilovol54527e72015-09-08 13:11:23 +030077
Mike Frysinger04071c12016-12-28 16:07:16 -050078 <!ELEMENT linkfile EMPTY>
Kenny Ho827e5472015-10-22 20:59:42 +000079 <!ATTLIST linkfile src CDATA #REQUIRED>
80 <!ATTLIST linkfile dest CDATA #REQUIRED>
Ruslan Bilovol54527e72015-09-08 13:11:23 +030081
Mike Frysinger04071c12016-12-28 16:07:16 -050082 <!ELEMENT extend-project EMPTY>
Josh Triplett884a3872014-06-12 14:57:29 -070083 <!ATTLIST extend-project name CDATA #REQUIRED>
84 <!ATTLIST extend-project path CDATA #IMPLIED>
85 <!ATTLIST extend-project groups CDATA #IMPLIED>
86
Mike Frysinger04071c12016-12-28 16:07:16 -050087 <!ELEMENT remove-project EMPTY>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080088 <!ATTLIST remove-project name CDATA #REQUIRED>
Doug Anderson37282b42011-03-04 11:54:18 -080089
Mike Frysinger04071c12016-12-28 16:07:16 -050090 <!ELEMENT repo-hooks EMPTY>
Doug Anderson37282b42011-03-04 11:54:18 -080091 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
92 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
Brian Harring26448742011-04-28 05:04:41 -070093
Mike Frysinger04071c12016-12-28 16:07:16 -050094 <!ELEMENT include EMPTY>
Brian Harring26448742011-04-28 05:04:41 -070095 <!ATTLIST include name CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080096 ]>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080097
98A description of the elements and their attributes follows.
99
100
101Element manifest
102----------------
103
104The root element of the file.
105
106
107Element remote
108--------------
109
110One or more remote elements may be specified. Each remote element
111specifies a Git URL shared by one or more projects and (optionally)
112the Gerrit review server those projects upload changes through.
113
114Attribute `name`: A short name unique to this manifest file. The
115name specified here is used as the remote name in each project's
116.git/config, and is therefore automatically available to commands
117like `git fetch`, `git remote`, `git pull` and `git push`.
118
Yestin Sunb292b982012-07-02 07:32:50 -0700119Attribute `alias`: The alias, if specified, is used to override
120`name` to be set as the remote name in each project's .git/config.
121Its value can be duplicated while attribute `name` has to be unique
122in the manifest file. This helps each project to be able to have
123same remote name which actually points to different remote url.
124
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800125Attribute `fetch`: The Git URL prefix for all projects which use
126this remote. Each project's name is appended to this prefix to
127form the actual URL used to clone the project.
128
Steve Raed6480452016-08-10 15:00:00 -0700129Attribute `pushurl`: The Git "push" URL prefix for all projects
130which use this remote. Each project's name is appended to this
131prefix to form the actual URL used to "git push" the project.
132This attribute is optional; if not specified then "git push"
133will use the same URL as the `fetch` attribute.
134
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800135Attribute `review`: Hostname of the Gerrit server where reviews
136are uploaded to by `repo upload`. This attribute is optional;
137if not specified then `repo upload` will not function.
138
Anthony King36ea2fb2014-05-06 11:54:01 +0100139Attribute `revision`: Name of a Git branch (e.g. `master` or
140`refs/heads/master`). Remotes with their own revision will override
141the default revision.
142
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800143Element default
144---------------
145
146At most one default element may be specified. Its remote and
147revision attributes are used when a project element does not
148specify its own remote or revision attribute.
149
150Attribute `remote`: Name of a previously defined remote element.
151Project elements lacking a remote attribute of their own will use
152this remote.
153
154Attribute `revision`: Name of a Git branch (e.g. `master` or
155`refs/heads/master`). Project elements lacking their own
156revision attribute will use this revision.
157
Bryan Jacobsf609f912013-05-06 13:36:24 -0400158Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
159Project elements not setting their own `dest-branch` will inherit
160this value. If this value is not set, projects will use `revision`
161by default instead.
162
Mani Chandel7a91d512014-07-24 16:27:08 +0530163Attribute `sync-j`: Number of parallel jobs to use when synching.
David Pursehouse4e465202012-11-27 22:20:10 +0900164
Mani Chandel7a91d512014-07-24 16:27:08 +0530165Attribute `sync-c`: Set to true to only sync the given Git
David Pursehouse4e465202012-11-27 22:20:10 +0900166branch (specified in the `revision` attribute) rather than the
Mani Chandel7a91d512014-07-24 16:27:08 +0530167whole ref space. Project elements lacking a sync-c element of
David Pursehouse4e465202012-11-27 22:20:10 +0900168their own will use this value.
169
Mani Chandel7a91d512014-07-24 16:27:08 +0530170Attribute `sync-s`: Set to true to also sync sub-projects.
David Pursehouse4e465202012-11-27 22:20:10 +0900171
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800172
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700173Element manifest-server
174-----------------------
175
176At most one manifest-server may be specified. The url attribute
177is used to specify the URL of a manifest server, which is an
David Pursehouse9a27d012012-08-21 14:23:49 +0900178XML RPC service.
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700179
David Pursehouse9a27d012012-08-21 14:23:49 +0900180The manifest server should implement the following RPC methods:
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700181
182 GetApprovedManifest(branch, target)
183
David Pursehouse9a27d012012-08-21 14:23:49 +0900184Return a manifest in which each project is pegged to a known good revision
David Pursehousee8688412016-04-13 17:55:34 +0900185for the current branch and target. This is used by repo sync when the
186--smart-sync option is given.
David Pursehouse9a27d012012-08-21 14:23:49 +0900187
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700188The target to use is defined by environment variables TARGET_PRODUCT
189and TARGET_BUILD_VARIANT. These variables are used to create a string
190of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug.
191If one of those variables or both are not present, the program will call
David Pursehousedaa851f2012-08-21 13:52:18 +0900192GetApprovedManifest without the target parameter and the manifest server
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700193should choose a reasonable default target.
194
David Pursehouse9a27d012012-08-21 14:23:49 +0900195 GetManifest(tag)
196
197Return a manifest in which each project is pegged to the revision at
David Pursehousee8688412016-04-13 17:55:34 +0900198the specified tag. This is used by repo sync when the --smart-tag option
199is given.
David Pursehouse9a27d012012-08-21 14:23:49 +0900200
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700201
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800202Element project
203---------------
204
205One or more project elements may be specified. Each element
206describes a single Git repository to be cloned into the repo
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800207client workspace. You may specify Git-submodules by creating a
208nested project. Git-submodules will be automatically
209recognized and inherit their parent's attributes, but those
210may be overridden by an explicitly specified project element.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800211
212Attribute `name`: A unique name for this project. The project's
213name is appended onto its remote's fetch URL to generate the actual
214URL to configure the Git remote with. The URL gets formed as:
215
216 ${remote_fetch}/${project_name}.git
217
218where ${remote_fetch} is the remote's fetch attribute and
219${project_name} is the project's name attribute. The suffix ".git"
David Pursehousedaa851f2012-08-21 13:52:18 +0900220is always appended as repo assumes the upstream is a forest of
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800221bare Git repositories. If the project has a parent element, its
222name will be prefixed by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800223
224The project name must match the name Gerrit knows, if Gerrit is
225being used for code reviews.
226
227Attribute `path`: An optional path relative to the top directory
228of the repo client where the Git working directory for this project
229should be placed. If not supplied the project name is used.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800230If the project has a parent element, its path will be prefixed
231by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800232
233Attribute `remote`: Name of a previously defined remote element.
234If not supplied the remote given by the default element is used.
235
236Attribute `revision`: Name of the Git branch the manifest wants
237to track for this project. Names can be relative to refs/heads
238(e.g. just "master") or absolute (e.g. "refs/heads/master").
239Tags and/or explicit SHA-1s should work in theory, but have not
240been extensively tested. If not supplied the revision given by
Anthony King36ea2fb2014-05-06 11:54:01 +0100241the remote element is used if applicable, else the default
242element is used.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800243
Bryan Jacobsf609f912013-05-06 13:36:24 -0400244Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
245When using `repo upload`, changes will be submitted for code
246review on this branch. If unspecified both here and in the
247default element, `revision` is used instead.
248
Colin Cross5acde752012-03-28 20:15:45 -0700249Attribute `groups`: List of groups to which this project belongs,
Conley Owens971de8e2012-04-16 10:36:08 -0700250whitespace or comma separated. All projects belong to the group
Conley Owensbb1b5f52012-08-13 13:11:18 -0700251"all", and each project automatically belongs to a group of
252its name:`name` and path:`path`. E.g. for
Brian Harring7da13142012-06-15 02:24:20 -0700253<project name="monkeys" path="barrel-of"/>, that project
254definition is implicitly in the following manifest groups:
Conley Owensbb1b5f52012-08-13 13:11:18 -0700255default, name:monkeys, and path:barrel-of. If you place a project in the
256group "notdefault", it will not be automatically downloaded by repo.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800257If the project has a parent element, the `name` and `path` here
258are the prefixed ones.
Colin Cross5acde752012-03-28 20:15:45 -0700259
Mani Chandel7a91d512014-07-24 16:27:08 +0530260Attribute `sync-c`: Set to true to only sync the given Git
David Pursehouse4e465202012-11-27 22:20:10 +0900261branch (specified in the `revision` attribute) rather than the
262whole ref space.
263
Mani Chandel7a91d512014-07-24 16:27:08 +0530264Attribute `sync-s`: Set to true to also sync sub-projects.
David Pursehouse4e465202012-11-27 22:20:10 +0900265
Nasser Grainawi909d58b2014-09-19 12:13:04 -0600266Attribute `upstream`: Name of the Git ref in which a sha1
David Pursehouse4e465202012-11-27 22:20:10 +0900267can be found. Used when syncing a revision locked manifest in
268-c mode to avoid having to sync the entire ref space.
269
David Pursehouseede7f122012-11-27 22:25:30 +0900270Attribute `clone-depth`: Set the depth to use when fetching this
271project. If specified, this value will override any value given
272to repo init with the --depth option on the command line.
273
Scott Fandb83b1b2013-02-28 09:34:14 +0800274Attribute `force-path`: Set to true to force this project to create the
275local mirror repository according to its `path` attribute (if supplied)
276rather than the `name` attribute. This attribute only applies to the
277local mirrors syncing, it will be ignored when syncing the projects in a
278client working directory.
279
Josh Triplett884a3872014-06-12 14:57:29 -0700280Element extend-project
281----------------------
282
283Modify the attributes of the named project.
284
285This element is mostly useful in a local manifest file, to modify the
286attributes of an existing project without completely replacing the
287existing project definition. This makes the local manifest more robust
288against changes to the original manifest.
289
290Attribute `path`: If specified, limit the change to projects checked out
291at the specified path, rather than all projects with the given name.
292
293Attribute `groups`: List of additional groups to which this project
294belongs. Same syntax as the corresponding element of `project`.
295
James W. Mills24c13082012-04-12 15:04:13 -0500296Element annotation
297------------------
298
299Zero or more annotation elements may be specified as children of a
300project element. Each element describes a name-value pair that will be
301exported into each project's environment during a 'forall' command,
302prefixed with REPO__. In addition, there is an optional attribute
303"keep" which accepts the case insensitive values "true" (default) or
304"false". This attribute determines whether or not the annotation will
305be kept when exported with the manifest subcommand.
306
Ruslan Bilovol54527e72015-09-08 13:11:23 +0300307Element copyfile
308----------------
309
310Zero or more copyfile elements may be specified as children of a
311project element. Each element describes a src-dest pair of files;
312the "src" file will be copied to the "dest" place during 'repo sync'
313command.
314"src" is project relative, "dest" is relative to the top of the tree.
315
316Element linkfile
317----------------
318
319It's just like copyfile and runs at the same time as copyfile but
320instead of copying it creates a symlink.
321
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800322Element remove-project
323----------------------
324
325Deletes the named project from the internal manifest table, possibly
326allowing a subsequent project element in the same manifest file to
327replace the project with a different source.
328
David Pursehouseb1525bf2012-11-14 08:51:38 +0900329This element is mostly useful in a local manifest file, where
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800330the user can remove a project, and possibly replace it with their
331own definition.
332
Brian Harring26448742011-04-28 05:04:41 -0700333Element include
334---------------
335
336This element provides the capability of including another manifest
337file into the originating manifest. Normal rules apply for the
David Pursehouse9f3406e2012-11-14 08:52:25 +0900338target manifest to include - it must be a usable manifest on its own.
Brian Harring26448742011-04-28 05:04:41 -0700339
David Pursehouse9f3406e2012-11-14 08:52:25 +0900340Attribute `name`: the manifest to include, specified relative to
341the manifest repository's root.
Brian Harring26448742011-04-28 05:04:41 -0700342
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800343
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900344Local Manifests
345===============
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800346
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900347Additional remotes and projects may be added through local manifest
348files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800349
350For example:
351
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900352 $ ls .repo/local_manifests
353 local_manifest.xml
354 another_local_manifest.xml
355
356 $ cat .repo/local_manifests/local_manifest.xml
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -0800357 <?xml version="1.0" encoding="UTF-8"?>
358 <manifest>
359 <project path="manifest"
360 name="tools/manifest" />
361 <project path="platform-manifest"
362 name="platform/manifest" />
363 </manifest>
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800364
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900365Users may add projects to the local manifest(s) prior to a `repo sync`
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800366invocation, instructing repo to automatically download and manage
367these extra projects.
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900368
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900369Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will
370be loaded in alphabetical order.
371
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900372Additional remotes and projects may also be added through a local
David Pursehouse5566ae52012-11-13 03:04:18 +0900373manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method
374is deprecated in favor of using multiple manifest files as mentioned
375above.
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900376
377If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before
378any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.