blob: 140a782f5d98dd4193baa4c2f241944820888371 [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
Jonathan Nieder93719792015-03-17 11:29:58 -070034 <!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>
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)>
Kenny Ho827e5472015-10-22 20:59:42 +000050 <!ATTLIST manifest-server url CDATA #REQUIRED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053051
Warren Turkal53d6a7b2013-12-10 15:30:03 -080052 <!ELEMENT project (annotation*,
Ruslan Bilovol54527e72015-09-08 13:11:23 +030053 project*,
Kenny Ho827e5472015-10-22 20:59:42 +000054 copyfile*,
55 linkfile*)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040056 <!ATTLIST project name CDATA #REQUIRED>
57 <!ATTLIST project path CDATA #IMPLIED>
58 <!ATTLIST project remote IDREF #IMPLIED>
59 <!ATTLIST project revision CDATA #IMPLIED>
60 <!ATTLIST project dest-branch CDATA #IMPLIED>
61 <!ATTLIST project groups CDATA #IMPLIED>
62 <!ATTLIST project sync-c CDATA #IMPLIED>
63 <!ATTLIST project sync-s CDATA #IMPLIED>
David Pursehouse4e465202012-11-27 22:20:10 +090064 <!ATTLIST project upstream CDATA #IMPLIED>
David Pursehouseede7f122012-11-27 22:25:30 +090065 <!ATTLIST project clone-depth CDATA #IMPLIED>
Scott Fandb83b1b2013-02-28 09:34:14 +080066 <!ATTLIST project force-path CDATA #IMPLIED>
James W. Mills24c13082012-04-12 15:04:13 -050067
68 <!ELEMENT annotation (EMPTY)>
69 <!ATTLIST annotation name CDATA #REQUIRED>
70 <!ATTLIST annotation value CDATA #REQUIRED>
71 <!ATTLIST annotation keep CDATA "true">
Chirayu Desaid5a5b192013-11-21 19:15:30 +053072
Ruslan Bilovol54527e72015-09-08 13:11:23 +030073 <!ELEMENT copyfile (EMPTY)>
Kenny Ho827e5472015-10-22 20:59:42 +000074 <!ATTLIST copyfile src CDATA #REQUIRED>
75 <!ATTLIST copyfile dest CDATA #REQUIRED>
Ruslan Bilovol54527e72015-09-08 13:11:23 +030076
77 <!ELEMENT linkfile (EMPTY)>
Kenny Ho827e5472015-10-22 20:59:42 +000078 <!ATTLIST linkfile src CDATA #REQUIRED>
79 <!ATTLIST linkfile dest CDATA #REQUIRED>
Ruslan Bilovol54527e72015-09-08 13:11:23 +030080
Kenny Ho827e5472015-10-22 20:59:42 +000081 <!ELEMENT extend-project (EMPTY)>
Josh Triplett884a3872014-06-12 14:57:29 -070082 <!ATTLIST extend-project name CDATA #REQUIRED>
83 <!ATTLIST extend-project path CDATA #IMPLIED>
84 <!ATTLIST extend-project groups CDATA #IMPLIED>
85
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080086 <!ELEMENT remove-project (EMPTY)>
87 <!ATTLIST remove-project name CDATA #REQUIRED>
Doug Anderson37282b42011-03-04 11:54:18 -080088
89 <!ELEMENT repo-hooks (EMPTY)>
90 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
91 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
Brian Harring26448742011-04-28 05:04:41 -070092
93 <!ELEMENT include (EMPTY)>
94 <!ATTLIST include name CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080095 ]>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080096
97A description of the elements and their attributes follows.
98
99
100Element manifest
101----------------
102
103The root element of the file.
104
105
106Element remote
107--------------
108
109One or more remote elements may be specified. Each remote element
110specifies a Git URL shared by one or more projects and (optionally)
111the Gerrit review server those projects upload changes through.
112
113Attribute `name`: A short name unique to this manifest file. The
114name specified here is used as the remote name in each project's
115.git/config, and is therefore automatically available to commands
116like `git fetch`, `git remote`, `git pull` and `git push`.
117
Yestin Sunb292b982012-07-02 07:32:50 -0700118Attribute `alias`: The alias, if specified, is used to override
119`name` to be set as the remote name in each project's .git/config.
120Its value can be duplicated while attribute `name` has to be unique
121in the manifest file. This helps each project to be able to have
122same remote name which actually points to different remote url.
123
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800124Attribute `fetch`: The Git URL prefix for all projects which use
125this remote. Each project's name is appended to this prefix to
126form the actual URL used to clone the project.
127
128Attribute `review`: Hostname of the Gerrit server where reviews
129are uploaded to by `repo upload`. This attribute is optional;
130if not specified then `repo upload` will not function.
131
Anthony King36ea2fb2014-05-06 11:54:01 +0100132Attribute `revision`: Name of a Git branch (e.g. `master` or
133`refs/heads/master`). Remotes with their own revision will override
134the default revision.
135
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800136Element default
137---------------
138
139At most one default element may be specified. Its remote and
140revision attributes are used when a project element does not
141specify its own remote or revision attribute.
142
143Attribute `remote`: Name of a previously defined remote element.
144Project elements lacking a remote attribute of their own will use
145this remote.
146
147Attribute `revision`: Name of a Git branch (e.g. `master` or
148`refs/heads/master`). Project elements lacking their own
149revision attribute will use this revision.
150
Bryan Jacobsf609f912013-05-06 13:36:24 -0400151Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
152Project elements not setting their own `dest-branch` will inherit
153this value. If this value is not set, projects will use `revision`
154by default instead.
155
Mani Chandel7a91d512014-07-24 16:27:08 +0530156Attribute `sync-j`: Number of parallel jobs to use when synching.
David Pursehouse4e465202012-11-27 22:20:10 +0900157
Mani Chandel7a91d512014-07-24 16:27:08 +0530158Attribute `sync-c`: Set to true to only sync the given Git
David Pursehouse4e465202012-11-27 22:20:10 +0900159branch (specified in the `revision` attribute) rather than the
Mani Chandel7a91d512014-07-24 16:27:08 +0530160whole ref space. Project elements lacking a sync-c element of
David Pursehouse4e465202012-11-27 22:20:10 +0900161their own will use this value.
162
Mani Chandel7a91d512014-07-24 16:27:08 +0530163Attribute `sync-s`: Set to true to also sync sub-projects.
David Pursehouse4e465202012-11-27 22:20:10 +0900164
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800165
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700166Element manifest-server
167-----------------------
168
169At most one manifest-server may be specified. The url attribute
170is used to specify the URL of a manifest server, which is an
David Pursehouse9a27d012012-08-21 14:23:49 +0900171XML RPC service.
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700172
David Pursehouse9a27d012012-08-21 14:23:49 +0900173The manifest server should implement the following RPC methods:
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700174
175 GetApprovedManifest(branch, target)
176
David Pursehouse9a27d012012-08-21 14:23:49 +0900177Return a manifest in which each project is pegged to a known good revision
178for the current branch and target.
179
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700180The target to use is defined by environment variables TARGET_PRODUCT
181and TARGET_BUILD_VARIANT. These variables are used to create a string
182of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug.
183If one of those variables or both are not present, the program will call
David Pursehousedaa851f2012-08-21 13:52:18 +0900184GetApprovedManifest without the target parameter and the manifest server
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700185should choose a reasonable default target.
186
David Pursehouse9a27d012012-08-21 14:23:49 +0900187 GetManifest(tag)
188
189Return a manifest in which each project is pegged to the revision at
190the specified tag.
191
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700192
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800193Element project
194---------------
195
196One or more project elements may be specified. Each element
197describes a single Git repository to be cloned into the repo
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800198client workspace. You may specify Git-submodules by creating a
199nested project. Git-submodules will be automatically
200recognized and inherit their parent's attributes, but those
201may be overridden by an explicitly specified project element.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800202
203Attribute `name`: A unique name for this project. The project's
204name is appended onto its remote's fetch URL to generate the actual
205URL to configure the Git remote with. The URL gets formed as:
206
207 ${remote_fetch}/${project_name}.git
208
209where ${remote_fetch} is the remote's fetch attribute and
210${project_name} is the project's name attribute. The suffix ".git"
David Pursehousedaa851f2012-08-21 13:52:18 +0900211is always appended as repo assumes the upstream is a forest of
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800212bare Git repositories. If the project has a parent element, its
213name will be prefixed by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800214
215The project name must match the name Gerrit knows, if Gerrit is
216being used for code reviews.
217
218Attribute `path`: An optional path relative to the top directory
219of the repo client where the Git working directory for this project
220should be placed. If not supplied the project name is used.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800221If the project has a parent element, its path will be prefixed
222by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800223
224Attribute `remote`: Name of a previously defined remote element.
225If not supplied the remote given by the default element is used.
226
227Attribute `revision`: Name of the Git branch the manifest wants
228to track for this project. Names can be relative to refs/heads
229(e.g. just "master") or absolute (e.g. "refs/heads/master").
230Tags and/or explicit SHA-1s should work in theory, but have not
231been extensively tested. If not supplied the revision given by
Anthony King36ea2fb2014-05-06 11:54:01 +0100232the remote element is used if applicable, else the default
233element is used.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800234
Bryan Jacobsf609f912013-05-06 13:36:24 -0400235Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
236When using `repo upload`, changes will be submitted for code
237review on this branch. If unspecified both here and in the
238default element, `revision` is used instead.
239
Colin Cross5acde752012-03-28 20:15:45 -0700240Attribute `groups`: List of groups to which this project belongs,
Conley Owens971de8e2012-04-16 10:36:08 -0700241whitespace or comma separated. All projects belong to the group
Conley Owensbb1b5f52012-08-13 13:11:18 -0700242"all", and each project automatically belongs to a group of
243its name:`name` and path:`path`. E.g. for
Brian Harring7da13142012-06-15 02:24:20 -0700244<project name="monkeys" path="barrel-of"/>, that project
245definition is implicitly in the following manifest groups:
Conley Owensbb1b5f52012-08-13 13:11:18 -0700246default, name:monkeys, and path:barrel-of. If you place a project in the
247group "notdefault", it will not be automatically downloaded by repo.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800248If the project has a parent element, the `name` and `path` here
249are the prefixed ones.
Colin Cross5acde752012-03-28 20:15:45 -0700250
Mani Chandel7a91d512014-07-24 16:27:08 +0530251Attribute `sync-c`: Set to true to only sync the given Git
David Pursehouse4e465202012-11-27 22:20:10 +0900252branch (specified in the `revision` attribute) rather than the
253whole ref space.
254
Mani Chandel7a91d512014-07-24 16:27:08 +0530255Attribute `sync-s`: Set to true to also sync sub-projects.
David Pursehouse4e465202012-11-27 22:20:10 +0900256
Nasser Grainawi909d58b2014-09-19 12:13:04 -0600257Attribute `upstream`: Name of the Git ref in which a sha1
David Pursehouse4e465202012-11-27 22:20:10 +0900258can be found. Used when syncing a revision locked manifest in
259-c mode to avoid having to sync the entire ref space.
260
David Pursehouseede7f122012-11-27 22:25:30 +0900261Attribute `clone-depth`: Set the depth to use when fetching this
262project. If specified, this value will override any value given
263to repo init with the --depth option on the command line.
264
Scott Fandb83b1b2013-02-28 09:34:14 +0800265Attribute `force-path`: Set to true to force this project to create the
266local mirror repository according to its `path` attribute (if supplied)
267rather than the `name` attribute. This attribute only applies to the
268local mirrors syncing, it will be ignored when syncing the projects in a
269client working directory.
270
Josh Triplett884a3872014-06-12 14:57:29 -0700271Element extend-project
272----------------------
273
274Modify the attributes of the named project.
275
276This element is mostly useful in a local manifest file, to modify the
277attributes of an existing project without completely replacing the
278existing project definition. This makes the local manifest more robust
279against changes to the original manifest.
280
281Attribute `path`: If specified, limit the change to projects checked out
282at the specified path, rather than all projects with the given name.
283
284Attribute `groups`: List of additional groups to which this project
285belongs. Same syntax as the corresponding element of `project`.
286
James W. Mills24c13082012-04-12 15:04:13 -0500287Element annotation
288------------------
289
290Zero or more annotation elements may be specified as children of a
291project element. Each element describes a name-value pair that will be
292exported into each project's environment during a 'forall' command,
293prefixed with REPO__. In addition, there is an optional attribute
294"keep" which accepts the case insensitive values "true" (default) or
295"false". This attribute determines whether or not the annotation will
296be kept when exported with the manifest subcommand.
297
Ruslan Bilovol54527e72015-09-08 13:11:23 +0300298Element copyfile
299----------------
300
301Zero or more copyfile elements may be specified as children of a
302project element. Each element describes a src-dest pair of files;
303the "src" file will be copied to the "dest" place during 'repo sync'
304command.
305"src" is project relative, "dest" is relative to the top of the tree.
306
307Element linkfile
308----------------
309
310It's just like copyfile and runs at the same time as copyfile but
311instead of copying it creates a symlink.
312
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800313Element remove-project
314----------------------
315
316Deletes the named project from the internal manifest table, possibly
317allowing a subsequent project element in the same manifest file to
318replace the project with a different source.
319
David Pursehouseb1525bf2012-11-14 08:51:38 +0900320This element is mostly useful in a local manifest file, where
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800321the user can remove a project, and possibly replace it with their
322own definition.
323
Brian Harring26448742011-04-28 05:04:41 -0700324Element include
325---------------
326
327This element provides the capability of including another manifest
328file into the originating manifest. Normal rules apply for the
David Pursehouse9f3406e2012-11-14 08:52:25 +0900329target manifest to include - it must be a usable manifest on its own.
Brian Harring26448742011-04-28 05:04:41 -0700330
David Pursehouse9f3406e2012-11-14 08:52:25 +0900331Attribute `name`: the manifest to include, specified relative to
332the manifest repository's root.
Brian Harring26448742011-04-28 05:04:41 -0700333
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800334
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900335Local Manifests
336===============
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800337
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900338Additional remotes and projects may be added through local manifest
339files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800340
341For example:
342
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900343 $ ls .repo/local_manifests
344 local_manifest.xml
345 another_local_manifest.xml
346
347 $ cat .repo/local_manifests/local_manifest.xml
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -0800348 <?xml version="1.0" encoding="UTF-8"?>
349 <manifest>
350 <project path="manifest"
351 name="tools/manifest" />
352 <project path="platform-manifest"
353 name="platform/manifest" />
354 </manifest>
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800355
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900356Users may add projects to the local manifest(s) prior to a `repo sync`
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800357invocation, instructing repo to automatically download and manage
358these extra projects.
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900359
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900360Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will
361be loaded in alphabetical order.
362
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900363Additional remotes and projects may also be added through a local
David Pursehouse5566ae52012-11-13 03:04:18 +0900364manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method
365is deprecated in favor of using multiple manifest files as mentioned
366above.
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900367
368If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before
369any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.