blob: a54282c89365a86c0d8de49d4e006c2c8d64eb20 [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?)>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080030
Doug Anderson2b8db3c2010-11-01 15:08:06 -070031 <!ELEMENT notice (#PCDATA)>
32
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>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080038
39 <!ELEMENT default (EMPTY)>
40 <!ATTLIST default remote IDREF #IMPLIED>
41 <!ATTLIST default revision CDATA #IMPLIED>
Shawn O. Pearce6392c872011-09-22 17:44:31 -070042 <!ATTLIST default sync-j CDATA #IMPLIED>
Anatol Pomazau79770d22012-04-20 14:41:59 -070043 <!ATTLIST default sync-c CDATA #IMPLIED>
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -070044
45 <!ELEMENT manifest-server (EMPTY)>
46 <!ATTLIST url CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080047
Shawn O. Pearcecd81dd62012-10-26 12:18:00 -070048 <!ELEMENT project (annotation?)>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080049 <!ATTLIST project name CDATA #REQUIRED>
50 <!ATTLIST project path CDATA #IMPLIED>
51 <!ATTLIST project remote IDREF #IMPLIED>
52 <!ATTLIST project revision CDATA #IMPLIED>
Colin Cross5acde752012-03-28 20:15:45 -070053 <!ATTLIST project groups CDATA #IMPLIED>
Anatol Pomazau79770d22012-04-20 14:41:59 -070054 <!ATTLIST project sync-c CDATA #IMPLIED>
James W. Mills24c13082012-04-12 15:04:13 -050055
56 <!ELEMENT annotation (EMPTY)>
57 <!ATTLIST annotation name CDATA #REQUIRED>
58 <!ATTLIST annotation value CDATA #REQUIRED>
59 <!ATTLIST annotation keep CDATA "true">
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080060
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080061 <!ELEMENT remove-project (EMPTY)>
62 <!ATTLIST remove-project name CDATA #REQUIRED>
Doug Anderson37282b42011-03-04 11:54:18 -080063
64 <!ELEMENT repo-hooks (EMPTY)>
65 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
66 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
Brian Harring26448742011-04-28 05:04:41 -070067
68 <!ELEMENT include (EMPTY)>
69 <!ATTLIST include name CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080070 ]>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080071
72A description of the elements and their attributes follows.
73
74
75Element manifest
76----------------
77
78The root element of the file.
79
80
81Element remote
82--------------
83
84One or more remote elements may be specified. Each remote element
85specifies a Git URL shared by one or more projects and (optionally)
86the Gerrit review server those projects upload changes through.
87
88Attribute `name`: A short name unique to this manifest file. The
89name specified here is used as the remote name in each project's
90.git/config, and is therefore automatically available to commands
91like `git fetch`, `git remote`, `git pull` and `git push`.
92
Yestin Sunb292b982012-07-02 07:32:50 -070093Attribute `alias`: The alias, if specified, is used to override
94`name` to be set as the remote name in each project's .git/config.
95Its value can be duplicated while attribute `name` has to be unique
96in the manifest file. This helps each project to be able to have
97same remote name which actually points to different remote url.
98
Shawn O. Pearce3e548192008-11-04 11:19:36 -080099Attribute `fetch`: The Git URL prefix for all projects which use
100this remote. Each project's name is appended to this prefix to
101form the actual URL used to clone the project.
102
103Attribute `review`: Hostname of the Gerrit server where reviews
104are uploaded to by `repo upload`. This attribute is optional;
105if not specified then `repo upload` will not function.
106
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800107Element default
108---------------
109
110At most one default element may be specified. Its remote and
111revision attributes are used when a project element does not
112specify its own remote or revision attribute.
113
114Attribute `remote`: Name of a previously defined remote element.
115Project elements lacking a remote attribute of their own will use
116this remote.
117
118Attribute `revision`: Name of a Git branch (e.g. `master` or
119`refs/heads/master`). Project elements lacking their own
120revision attribute will use this revision.
121
122
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700123Element manifest-server
124-----------------------
125
126At most one manifest-server may be specified. The url attribute
127is used to specify the URL of a manifest server, which is an
David Pursehouse9a27d012012-08-21 14:23:49 +0900128XML RPC service.
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700129
David Pursehouse9a27d012012-08-21 14:23:49 +0900130The manifest server should implement the following RPC methods:
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700131
132 GetApprovedManifest(branch, target)
133
David Pursehouse9a27d012012-08-21 14:23:49 +0900134Return a manifest in which each project is pegged to a known good revision
135for the current branch and target.
136
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700137The target to use is defined by environment variables TARGET_PRODUCT
138and TARGET_BUILD_VARIANT. These variables are used to create a string
139of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug.
140If one of those variables or both are not present, the program will call
David Pursehousedaa851f2012-08-21 13:52:18 +0900141GetApprovedManifest without the target parameter and the manifest server
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700142should choose a reasonable default target.
143
David Pursehouse9a27d012012-08-21 14:23:49 +0900144 GetManifest(tag)
145
146Return a manifest in which each project is pegged to the revision at
147the specified tag.
148
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700149
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800150Element project
151---------------
152
153One or more project elements may be specified. Each element
154describes a single Git repository to be cloned into the repo
Shawn O. Pearcecd81dd62012-10-26 12:18:00 -0700155client workspace.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800156
157Attribute `name`: A unique name for this project. The project's
158name is appended onto its remote's fetch URL to generate the actual
159URL to configure the Git remote with. The URL gets formed as:
160
161 ${remote_fetch}/${project_name}.git
162
163where ${remote_fetch} is the remote's fetch attribute and
164${project_name} is the project's name attribute. The suffix ".git"
David Pursehousedaa851f2012-08-21 13:52:18 +0900165is always appended as repo assumes the upstream is a forest of
Shawn O. Pearcecd81dd62012-10-26 12:18:00 -0700166bare Git repositories.
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800167
168The project name must match the name Gerrit knows, if Gerrit is
169being used for code reviews.
170
171Attribute `path`: An optional path relative to the top directory
172of the repo client where the Git working directory for this project
173should be placed. If not supplied the project name is used.
174
175Attribute `remote`: Name of a previously defined remote element.
176If not supplied the remote given by the default element is used.
177
178Attribute `revision`: Name of the Git branch the manifest wants
179to track for this project. Names can be relative to refs/heads
180(e.g. just "master") or absolute (e.g. "refs/heads/master").
181Tags and/or explicit SHA-1s should work in theory, but have not
182been extensively tested. If not supplied the revision given by
183the default element is used.
184
Colin Cross5acde752012-03-28 20:15:45 -0700185Attribute `groups`: List of groups to which this project belongs,
Conley Owens971de8e2012-04-16 10:36:08 -0700186whitespace or comma separated. All projects belong to the group
Conley Owensbb1b5f52012-08-13 13:11:18 -0700187"all", and each project automatically belongs to a group of
188its name:`name` and path:`path`. E.g. for
Brian Harring7da13142012-06-15 02:24:20 -0700189<project name="monkeys" path="barrel-of"/>, that project
190definition is implicitly in the following manifest groups:
Conley Owensbb1b5f52012-08-13 13:11:18 -0700191default, name:monkeys, and path:barrel-of. If you place a project in the
192group "notdefault", it will not be automatically downloaded by repo.
Colin Cross5acde752012-03-28 20:15:45 -0700193
James W. Mills24c13082012-04-12 15:04:13 -0500194Element annotation
195------------------
196
197Zero or more annotation elements may be specified as children of a
198project element. Each element describes a name-value pair that will be
199exported into each project's environment during a 'forall' command,
200prefixed with REPO__. In addition, there is an optional attribute
201"keep" which accepts the case insensitive values "true" (default) or
202"false". This attribute determines whether or not the annotation will
203be kept when exported with the manifest subcommand.
204
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800205Element remove-project
206----------------------
207
208Deletes the named project from the internal manifest table, possibly
209allowing a subsequent project element in the same manifest file to
210replace the project with a different source.
211
David Pursehouseb1525bf2012-11-14 08:51:38 +0900212This element is mostly useful in a local manifest file, where
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800213the user can remove a project, and possibly replace it with their
214own definition.
215
Brian Harring26448742011-04-28 05:04:41 -0700216Element include
217---------------
218
219This element provides the capability of including another manifest
220file into the originating manifest. Normal rules apply for the
David Pursehouse9f3406e2012-11-14 08:52:25 +0900221target manifest to include - it must be a usable manifest on its own.
Brian Harring26448742011-04-28 05:04:41 -0700222
David Pursehouse9f3406e2012-11-14 08:52:25 +0900223Attribute `name`: the manifest to include, specified relative to
224the manifest repository's root.
Brian Harring26448742011-04-28 05:04:41 -0700225
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800226
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900227Local Manifests
228===============
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800229
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900230Additional remotes and projects may be added through local manifest
231files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800232
233For example:
234
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900235 $ ls .repo/local_manifests
236 local_manifest.xml
237 another_local_manifest.xml
238
239 $ cat .repo/local_manifests/local_manifest.xml
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -0800240 <?xml version="1.0" encoding="UTF-8"?>
241 <manifest>
242 <project path="manifest"
243 name="tools/manifest" />
244 <project path="platform-manifest"
245 name="platform/manifest" />
246 </manifest>
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800247
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900248Users may add projects to the local manifest(s) prior to a `repo sync`
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800249invocation, instructing repo to automatically download and manage
250these extra projects.
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900251
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900252Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will
253be loaded in alphabetical order.
254
David Pursehouse2d5a0df2012-11-13 02:50:36 +0900255Additional remotes and projects may also be added through a local
David Pursehouse5566ae52012-11-13 03:04:18 +0900256manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method
257is deprecated in favor of using multiple manifest files as mentioned
258above.
David Pursehouse52f1e5d2012-11-14 04:53:24 +0900259
260If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before
261any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.