blob: f63c9d0ea6fd9d008a3aefb9017e74e765565934 [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>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053038
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080039 <!ELEMENT default (EMPTY)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040040 <!ATTLIST default remote IDREF #IMPLIED>
41 <!ATTLIST default revision CDATA #IMPLIED>
42 <!ATTLIST default dest-branch CDATA #IMPLIED>
43 <!ATTLIST default sync-j CDATA #IMPLIED>
44 <!ATTLIST default sync-c CDATA #IMPLIED>
45 <!ATTLIST default sync-s CDATA #IMPLIED>
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -070046
47 <!ELEMENT manifest-server (EMPTY)>
48 <!ATTLIST url CDATA #REQUIRED>
Chirayu Desaid5a5b192013-11-21 19:15:30 +053049
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +080050 <!ELEMENT project (annotation?,
51 project*)>
Bryan Jacobsf609f912013-05-06 13:36:24 -040052 <!ATTLIST project name CDATA #REQUIRED>
53 <!ATTLIST project path CDATA #IMPLIED>
54 <!ATTLIST project remote IDREF #IMPLIED>
55 <!ATTLIST project revision CDATA #IMPLIED>
56 <!ATTLIST project dest-branch CDATA #IMPLIED>
57 <!ATTLIST project groups CDATA #IMPLIED>
58 <!ATTLIST project sync-c CDATA #IMPLIED>
59 <!ATTLIST project sync-s CDATA #IMPLIED>
David Pursehouse4e465202012-11-27 22:20:10 +090060 <!ATTLIST project upstream CDATA #IMPLIED>
David Pursehouseede7f122012-11-27 22:25:30 +090061 <!ATTLIST project clone-depth CDATA #IMPLIED>
Scott Fandb83b1b2013-02-28 09:34:14 +080062 <!ATTLIST project force-path CDATA #IMPLIED>
James W. Mills24c13082012-04-12 15:04:13 -050063
64 <!ELEMENT annotation (EMPTY)>
65 <!ATTLIST annotation name CDATA #REQUIRED>
66 <!ATTLIST annotation value CDATA #REQUIRED>
67 <!ATTLIST annotation keep CDATA "true">
Chirayu Desaid5a5b192013-11-21 19:15:30 +053068
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080069 <!ELEMENT remove-project (EMPTY)>
70 <!ATTLIST remove-project name CDATA #REQUIRED>
Doug Anderson37282b42011-03-04 11:54:18 -080071
72 <!ELEMENT repo-hooks (EMPTY)>
73 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
74 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
Brian Harring26448742011-04-28 05:04:41 -070075
76 <!ELEMENT include (EMPTY)>
77 <!ATTLIST include name CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080078 ]>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080079
80A description of the elements and their attributes follows.
81
82
83Element manifest
84----------------
85
86The root element of the file.
87
88
89Element remote
90--------------
91
92One or more remote elements may be specified. Each remote element
93specifies a Git URL shared by one or more projects and (optionally)
94the Gerrit review server those projects upload changes through.
95
96Attribute `name`: A short name unique to this manifest file. The
97name specified here is used as the remote name in each project's
98.git/config, and is therefore automatically available to commands
99like `git fetch`, `git remote`, `git pull` and `git push`.
100
Yestin Sunb292b982012-07-02 07:32:50 -0700101Attribute `alias`: The alias, if specified, is used to override
102`name` to be set as the remote name in each project's .git/config.
103Its value can be duplicated while attribute `name` has to be unique
104in the manifest file. This helps each project to be able to have
105same remote name which actually points to different remote url.
106
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800107Attribute `fetch`: The Git URL prefix for all projects which use
108this remote. Each project's name is appended to this prefix to
109form the actual URL used to clone the project.
110
111Attribute `review`: Hostname of the Gerrit server where reviews
112are uploaded to by `repo upload`. This attribute is optional;
113if not specified then `repo upload` will not function.
114
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800115Element default
116---------------
117
118At most one default element may be specified. Its remote and
119revision attributes are used when a project element does not
120specify its own remote or revision attribute.
121
122Attribute `remote`: Name of a previously defined remote element.
123Project elements lacking a remote attribute of their own will use
124this remote.
125
126Attribute `revision`: Name of a Git branch (e.g. `master` or
127`refs/heads/master`). Project elements lacking their own
128revision attribute will use this revision.
129
Bryan Jacobsf609f912013-05-06 13:36:24 -0400130Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
131Project elements not setting their own `dest-branch` will inherit
132this value. If this value is not set, projects will use `revision`
133by default instead.
134
David Pursehouse4e465202012-11-27 22:20:10 +0900135Attribute `sync_j`: Number of parallel jobs to use when synching.
136
137Attribute `sync_c`: Set to true to only sync the given Git
138branch (specified in the `revision` attribute) rather than the
139whole ref space. Project elements lacking a sync_c element of
140their own will use this value.
141
142Attribute `sync_s`: Set to true to also sync sub-projects.
143
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800144
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700145Element manifest-server
146-----------------------
147
148At most one manifest-server may be specified. The url attribute
149is used to specify the URL of a manifest server, which is an
David Pursehouse9a27d012012-08-21 14:23:49 +0900150XML RPC service.
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700151
David Pursehouse9a27d012012-08-21 14:23:49 +0900152The manifest server should implement the following RPC methods:
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700153
154 GetApprovedManifest(branch, target)
155
David Pursehouse9a27d012012-08-21 14:23:49 +0900156Return a manifest in which each project is pegged to a known good revision
157for the current branch and target.
158
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700159The target to use is defined by environment variables TARGET_PRODUCT
160and TARGET_BUILD_VARIANT. These variables are used to create a string
161of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug.
162If one of those variables or both are not present, the program will call
David Pursehousedaa851f2012-08-21 13:52:18 +0900163GetApprovedManifest without the target parameter and the manifest server
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700164should choose a reasonable default target.
165
David Pursehouse9a27d012012-08-21 14:23:49 +0900166 GetManifest(tag)
167
168Return a manifest in which each project is pegged to the revision at
169the specified tag.
170
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700171
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800172Element project
173---------------
174
175One or more project elements may be specified. Each element
176describes a single Git repository to be cloned into the repo
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800177client workspace. You may specify Git-submodules by creating a
178nested project. Git-submodules will be automatically
179recognized and inherit their parent's attributes, but those
180may be overridden by an explicitly specified project element.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800181
182Attribute `name`: A unique name for this project. The project's
183name is appended onto its remote's fetch URL to generate the actual
184URL to configure the Git remote with. The URL gets formed as:
185
186 ${remote_fetch}/${project_name}.git
187
188where ${remote_fetch} is the remote's fetch attribute and
189${project_name} is the project's name attribute. The suffix ".git"
David Pursehousedaa851f2012-08-21 13:52:18 +0900190is always appended as repo assumes the upstream is a forest of
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800191bare Git repositories. If the project has a parent element, its
192name will be prefixed by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800193
194The project name must match the name Gerrit knows, if Gerrit is
195being used for code reviews.
196
197Attribute `path`: An optional path relative to the top directory
198of the repo client where the Git working directory for this project
199should be placed. If not supplied the project name is used.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800200If the project has a parent element, its path will be prefixed
201by the parent's.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800202
203Attribute `remote`: Name of a previously defined remote element.
204If not supplied the remote given by the default element is used.
205
206Attribute `revision`: Name of the Git branch the manifest wants
207to track for this project. Names can be relative to refs/heads
208(e.g. just "master") or absolute (e.g. "refs/heads/master").
209Tags and/or explicit SHA-1s should work in theory, but have not
210been extensively tested. If not supplied the revision given by
211the default element is used.
212
Bryan Jacobsf609f912013-05-06 13:36:24 -0400213Attribute `dest-branch`: Name of a Git branch (e.g. `master`).
214When using `repo upload`, changes will be submitted for code
215review on this branch. If unspecified both here and in the
216default element, `revision` is used instead.
217
Colin Cross5acde752012-03-28 20:15:45 -0700218Attribute `groups`: List of groups to which this project belongs,
Conley Owens971de8e2012-04-16 10:36:08 -0700219whitespace or comma separated. All projects belong to the group
Conley Owensbb1b5f52012-08-13 13:11:18 -0700220"all", and each project automatically belongs to a group of
221its name:`name` and path:`path`. E.g. for
Brian Harring7da13142012-06-15 02:24:20 -0700222<project name="monkeys" path="barrel-of"/>, that project
223definition is implicitly in the following manifest groups:
Conley Owensbb1b5f52012-08-13 13:11:18 -0700224default, name:monkeys, and path:barrel-of. If you place a project in the
225group "notdefault", it will not be automatically downloaded by repo.
Che-Liang Chioub2bd91c2012-01-11 11:28:42 +0800226If the project has a parent element, the `name` and `path` here
227are the prefixed ones.
Colin Cross5acde752012-03-28 20:15:45 -0700228
David Pursehouse4e465202012-11-27 22:20:10 +0900229Attribute `sync_c`: Set to true to only sync the given Git
230branch (specified in the `revision` attribute) rather than the
231whole ref space.
232
233Attribute `sync_s`: Set to true to also sync sub-projects.
234
235Attribute `upstream`: Name of the Git branch in which a sha1
236can be found. Used when syncing a revision locked manifest in
237-c mode to avoid having to sync the entire ref space.
238
David Pursehouseede7f122012-11-27 22:25:30 +0900239Attribute `clone-depth`: Set the depth to use when fetching this
240project. If specified, this value will override any value given
241to repo init with the --depth option on the command line.
242
Scott Fandb83b1b2013-02-28 09:34:14 +0800243Attribute `force-path`: Set to true to force this project to create the
244local mirror repository according to its `path` attribute (if supplied)
245rather than the `name` attribute. This attribute only applies to the
246local mirrors syncing, it will be ignored when syncing the projects in a
247client working directory.
248
James W. Mills24c13082012-04-12 15:04:13 -0500249Element annotation
250------------------
251
252Zero or more annotation elements may be specified as children of a
253project element. Each element describes a name-value pair that will be
254exported into each project's environment during a 'forall' command,
255prefixed with REPO__. In addition, there is an optional attribute
256"keep" which accepts the case insensitive values "true" (default) or
257"false". This attribute determines whether or not the annotation will
258be kept when exported with the manifest subcommand.
259
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800260Element remove-project
261----------------------
262
263Deletes the named project from the internal manifest table, possibly
264allowing a subsequent project element in the same manifest file to
265replace the project with a different source.
266
David Pursehouseb1525bf2012-11-14 08:51:38 +0900267This element is mostly useful in a local manifest file, where
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800268the user can remove a project, and possibly replace it with their
269own definition.
270
Brian Harring26448742011-04-28 05:04:41 -0700271Element include
272---------------
273
274This element provides the capability of including another manifest
275file into the originating manifest. Normal rules apply for the
David Pursehouse9f3406e2012-11-14 08:52:25 +0900276target manifest to include - it must be a usable manifest on its own.
Brian Harring26448742011-04-28 05:04:41 -0700277
David Pursehouse9f3406e2012-11-14 08:52:25 +0900278Attribute `name`: the manifest to include, specified relative to
279the manifest repository's root.
Brian Harring26448742011-04-28 05:04:41 -0700280
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800281
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900282Local Manifests
283===============
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800284
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900285Additional remotes and projects may be added through local manifest
286files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800287
288For example:
289
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900290 $ ls .repo/local_manifests
291 local_manifest.xml
292 another_local_manifest.xml
293
294 $ cat .repo/local_manifests/local_manifest.xml
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -0800295 <?xml version="1.0" encoding="UTF-8"?>
296 <manifest>
297 <project path="manifest"
298 name="tools/manifest" />
299 <project path="platform-manifest"
300 name="platform/manifest" />
301 </manifest>
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800302
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900303Users may add projects to the local manifest(s) prior to a `repo sync`
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800304invocation, instructing repo to automatically download and manage
305these extra projects.
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900306
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900307Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will
308be loaded in alphabetical order.
309
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900310Additional remotes and projects may also be added through a local
David Pursehouse5566ae52012-11-13 03:04:18 +0900311manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method
312is deprecated in favor of using multiple manifest files as mentioned
313above.
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900314
315If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before
316any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.