blob: e5f5ee189ac583f9892964f11e219132bac200e5 [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>
35 <!ATTLIST remote fetch CDATA #REQUIRED>
36 <!ATTLIST remote review CDATA #IMPLIED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080037
38 <!ELEMENT default (EMPTY)>
39 <!ATTLIST default remote IDREF #IMPLIED>
40 <!ATTLIST default revision CDATA #IMPLIED>
Shawn O. Pearce6392c872011-09-22 17:44:31 -070041 <!ATTLIST default sync-j CDATA #IMPLIED>
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -070042
43 <!ELEMENT manifest-server (EMPTY)>
44 <!ATTLIST url CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080045
James W. Mills24c13082012-04-12 15:04:13 -050046 <!ELEMENT project (annotation?)>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080047 <!ATTLIST project name CDATA #REQUIRED>
48 <!ATTLIST project path CDATA #IMPLIED>
49 <!ATTLIST project remote IDREF #IMPLIED>
50 <!ATTLIST project revision CDATA #IMPLIED>
Colin Cross5acde752012-03-28 20:15:45 -070051 <!ATTLIST project groups CDATA #IMPLIED>
James W. Mills24c13082012-04-12 15:04:13 -050052
53 <!ELEMENT annotation (EMPTY)>
54 <!ATTLIST annotation name CDATA #REQUIRED>
55 <!ATTLIST annotation value CDATA #REQUIRED>
56 <!ATTLIST annotation keep CDATA "true">
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080057
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080058 <!ELEMENT remove-project (EMPTY)>
59 <!ATTLIST remove-project name CDATA #REQUIRED>
Doug Anderson37282b42011-03-04 11:54:18 -080060
61 <!ELEMENT repo-hooks (EMPTY)>
62 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
63 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -080064 ]>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080065
66A description of the elements and their attributes follows.
67
68
69Element manifest
70----------------
71
72The root element of the file.
73
74
75Element remote
76--------------
77
78One or more remote elements may be specified. Each remote element
79specifies a Git URL shared by one or more projects and (optionally)
80the Gerrit review server those projects upload changes through.
81
82Attribute `name`: A short name unique to this manifest file. The
83name specified here is used as the remote name in each project's
84.git/config, and is therefore automatically available to commands
85like `git fetch`, `git remote`, `git pull` and `git push`.
86
87Attribute `fetch`: The Git URL prefix for all projects which use
88this remote. Each project's name is appended to this prefix to
89form the actual URL used to clone the project.
90
91Attribute `review`: Hostname of the Gerrit server where reviews
92are uploaded to by `repo upload`. This attribute is optional;
93if not specified then `repo upload` will not function.
94
Shawn O. Pearce3e548192008-11-04 11:19:36 -080095Element default
96---------------
97
98At most one default element may be specified. Its remote and
99revision attributes are used when a project element does not
100specify its own remote or revision attribute.
101
102Attribute `remote`: Name of a previously defined remote element.
103Project elements lacking a remote attribute of their own will use
104this remote.
105
106Attribute `revision`: Name of a Git branch (e.g. `master` or
107`refs/heads/master`). Project elements lacking their own
108revision attribute will use this revision.
109
110
Nico Sallembiena1bfd2c2010-04-06 10:40:01 -0700111Element manifest-server
112-----------------------
113
114At most one manifest-server may be specified. The url attribute
115is used to specify the URL of a manifest server, which is an
116XML RPC service that will return a manifest in which each project
117is pegged to a known good revision for the current branch and
118target.
119
120The manifest server should implement:
121
122 GetApprovedManifest(branch, target)
123
124The target to use is defined by environment variables TARGET_PRODUCT
125and TARGET_BUILD_VARIANT. These variables are used to create a string
126of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug.
127If one of those variables or both are not present, the program will call
128GetApprovedManifest without the target paramater and the manifest server
129should choose a reasonable default target.
130
131
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800132Element project
133---------------
134
135One or more project elements may be specified. Each element
136describes a single Git repository to be cloned into the repo
137client workspace.
138
139Attribute `name`: A unique name for this project. The project's
140name is appended onto its remote's fetch URL to generate the actual
141URL to configure the Git remote with. The URL gets formed as:
142
143 ${remote_fetch}/${project_name}.git
144
145where ${remote_fetch} is the remote's fetch attribute and
146${project_name} is the project's name attribute. The suffix ".git"
147is always appended as repo assumes the upstream is a forrest of
148bare Git repositories.
149
150The project name must match the name Gerrit knows, if Gerrit is
151being used for code reviews.
152
153Attribute `path`: An optional path relative to the top directory
154of the repo client where the Git working directory for this project
155should be placed. If not supplied the project name is used.
156
157Attribute `remote`: Name of a previously defined remote element.
158If not supplied the remote given by the default element is used.
159
160Attribute `revision`: Name of the Git branch the manifest wants
161to track for this project. Names can be relative to refs/heads
162(e.g. just "master") or absolute (e.g. "refs/heads/master").
163Tags and/or explicit SHA-1s should work in theory, but have not
164been extensively tested. If not supplied the revision given by
165the default element is used.
166
Colin Cross5acde752012-03-28 20:15:45 -0700167Attribute `groups`: List of groups to which this project belongs,
168whitespace or comma separated. All projects are part of the group
169"default" unless "-default" is specified in the list of groups.
170
James W. Mills24c13082012-04-12 15:04:13 -0500171Element annotation
172------------------
173
174Zero or more annotation elements may be specified as children of a
175project element. Each element describes a name-value pair that will be
176exported into each project's environment during a 'forall' command,
177prefixed with REPO__. In addition, there is an optional attribute
178"keep" which accepts the case insensitive values "true" (default) or
179"false". This attribute determines whether or not the annotation will
180be kept when exported with the manifest subcommand.
181
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800182Element remove-project
183----------------------
184
185Deletes the named project from the internal manifest table, possibly
186allowing a subsequent project element in the same manifest file to
187replace the project with a different source.
188
189This element is mostly useful in the local_manifest.xml, where
190the user can remove a project, and possibly replace it with their
191own definition.
192
193
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800194Local Manifest
195==============
196
197Additional remotes and projects may be added through a local
198manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`.
199
200For example:
201
Shawn O. Pearce43c3d9e2009-03-04 14:26:50 -0800202 $ cat .repo/local_manifest.xml
203 <?xml version="1.0" encoding="UTF-8"?>
204 <manifest>
205 <project path="manifest"
206 name="tools/manifest" />
207 <project path="platform-manifest"
208 name="platform/manifest" />
209 </manifest>
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800210
211Users may add projects to the local manifest prior to a `repo sync`
212invocation, instructing repo to automatically download and manage
213these extra projects.