· 7 years ago · Feb 04, 2019, 12:06 PM
1repo Manifest Format
2A repo manifest describes the structure of a repo client; that is the directories that are visible and where they should be obtained from with git.
3
4The basic structure of a manifest is a bare Git repository holding a single default.xml XML file in the top level directory.
5
6Manifests are inherently version controlled, since they are kept within a Git repository. Updates to manifests are automatically obtained by clients during repo sync.
7
8Contents
9XML File Format
10Element manifest
11Element remote
12Element default
13Element manifest-server
14Element project
15Element extend-project
16Element annotation
17Element copyfile
18Element linkfile
19Element remove-project
20Element include
21Local Manifests
22XML File Format
23A manifest XML file (e.g. default.xml) roughly conforms to the following DTD:
24
25<!DOCTYPE manifest [
26 <!ELEMENT manifest (notice?,
27 remote*,
28 default?,
29 manifest-server?,
30 remove-project*,
31 project*,
32 extend-project*,
33 repo-hooks?,
34 include*)>
35
36 <!ELEMENT notice (#PCDATA)>
37
38 <!ELEMENT remote EMPTY>
39 <!ATTLIST remote name ID #REQUIRED>
40 <!ATTLIST remote alias CDATA #IMPLIED>
41 <!ATTLIST remote fetch CDATA #REQUIRED>
42 <!ATTLIST remote pushurl CDATA #IMPLIED>
43 <!ATTLIST remote review CDATA #IMPLIED>
44 <!ATTLIST remote revision CDATA #IMPLIED>
45
46 <!ELEMENT default EMPTY>
47 <!ATTLIST default remote IDREF #IMPLIED>
48 <!ATTLIST default revision CDATA #IMPLIED>
49 <!ATTLIST default dest-branch CDATA #IMPLIED>
50 <!ATTLIST default upstream CDATA #IMPLIED>
51 <!ATTLIST default sync-j CDATA #IMPLIED>
52 <!ATTLIST default sync-c CDATA #IMPLIED>
53 <!ATTLIST default sync-s CDATA #IMPLIED>
54 <!ATTLIST default sync-tags CDATA #IMPLIED>
55
56 <!ELEMENT manifest-server EMPTY>
57 <!ATTLIST manifest-server url CDATA #REQUIRED>
58
59 <!ELEMENT project (annotation*,
60 project*,
61 copyfile*,
62 linkfile*)>
63 <!ATTLIST project name CDATA #REQUIRED>
64 <!ATTLIST project path CDATA #IMPLIED>
65 <!ATTLIST project remote IDREF #IMPLIED>
66 <!ATTLIST project revision CDATA #IMPLIED>
67 <!ATTLIST project dest-branch CDATA #IMPLIED>
68 <!ATTLIST project groups CDATA #IMPLIED>
69 <!ATTLIST project sync-c CDATA #IMPLIED>
70 <!ATTLIST project sync-s CDATA #IMPLIED>
71 <!ATTLIST default sync-tags CDATA #IMPLIED>
72 <!ATTLIST project upstream CDATA #IMPLIED>
73 <!ATTLIST project clone-depth CDATA #IMPLIED>
74 <!ATTLIST project force-path CDATA #IMPLIED>
75
76 <!ELEMENT annotation EMPTY>
77 <!ATTLIST annotation name CDATA #REQUIRED>
78 <!ATTLIST annotation value CDATA #REQUIRED>
79 <!ATTLIST annotation keep CDATA "true">
80
81 <!ELEMENT copyfile EMPTY>
82 <!ATTLIST copyfile src CDATA #REQUIRED>
83 <!ATTLIST copyfile dest CDATA #REQUIRED>
84
85 <!ELEMENT linkfile EMPTY>
86 <!ATTLIST linkfile src CDATA #REQUIRED>
87 <!ATTLIST linkfile dest CDATA #REQUIRED>
88
89 <!ELEMENT extend-project EMPTY>
90 <!ATTLIST extend-project name CDATA #REQUIRED>
91 <!ATTLIST extend-project path CDATA #IMPLIED>
92 <!ATTLIST extend-project groups CDATA #IMPLIED>
93 <!ATTLIST extend-project revision CDATA #IMPLIED>
94
95 <!ELEMENT remove-project EMPTY>
96 <!ATTLIST remove-project name CDATA #REQUIRED>
97
98 <!ELEMENT repo-hooks EMPTY>
99 <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
100 <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>
101
102 <!ELEMENT include EMPTY>
103 <!ATTLIST include name CDATA #REQUIRED>
104]>
105A description of the elements and their attributes follows.
106
107Element manifest
108The root element of the file.
109
110Element remote
111One or more remote elements may be specified. Each remote element specifies a Git URL shared by one or more projects and (optionally) the Gerrit review server those projects upload changes through.
112
113Attribute name: A short name unique to this manifest file. The name specified here is used as the remote name in each project's .git/config, and is therefore automatically available to commands like git fetch, git remote, git pull and git push.
114
115Attribute alias: The alias, if specified, is used to override name to be set as the remote name in each project's .git/config. Its value can be duplicated while attribute name has to be unique in the manifest file. This helps each project to be able to have same remote name which actually points to different remote url.
116
117Attribute fetch: The Git URL prefix for all projects which use this remote. Each project's name is appended to this prefix to form the actual URL used to clone the project.
118
119Attribute pushurl: The Git “push†URL prefix for all projects which use this remote. Each project's name is appended to this prefix to form the actual URL used to “git push†the project. This attribute is optional; if not specified then “git push†will use the same URL as the fetch attribute.
120
121Attribute review: Hostname of the Gerrit server where reviews are uploaded to by repo upload. This attribute is optional; if not specified then repo upload will not function.
122
123Attribute revision: Name of a Git branch (e.g. master or refs/heads/master). Remotes with their own revision will override the default revision.
124
125Element default
126At most one default element may be specified. Its remote and revision attributes are used when a project element does not specify its own remote or revision attribute.
127
128Attribute remote: Name of a previously defined remote element. Project elements lacking a remote attribute of their own will use this remote.
129
130Attribute revision: Name of a Git branch (e.g. master or refs/heads/master). Project elements lacking their own revision attribute will use this revision.
131
132Attribute dest-branch: Name of a Git branch (e.g. master). Project elements not setting their own dest-branch will inherit this value. If this value is not set, projects will use revision by default instead.
133
134Attribute upstream: Name of the Git ref in which a sha1 can be found. Used when syncing a revision locked manifest in -c mode to avoid having to sync the entire ref space. Project elements not setting their own upstream will inherit this value.
135
136Attribute sync-j: Number of parallel jobs to use when synching.
137
138Attribute sync-c: Set to true to only sync the given Git branch (specified in the revision attribute) rather than the whole ref space. Project elements lacking a sync-c element of their own will use this value.
139
140Attribute sync-s: Set to true to also sync sub-projects.
141
142Attribute sync-tags: Set to false to only sync the given Git branch (specified in the revision attribute) rather than the other ref tags.
143
144Element manifest-server
145At most one manifest-server may be specified. The url attribute is used to specify the URL of a manifest server, which is an XML RPC service.
146
147The manifest server should implement the following RPC methods:
148
149GetApprovedManifest(branch, target)
150Return a manifest in which each project is pegged to a known good revision for the current branch and target. This is used by repo sync when the --smart-sync option is given.
151
152The target to use is defined by environment variables TARGET_PRODUCT and TARGET_BUILD_VARIANT. These variables are used to create a string of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug. If one of those variables or both are not present, the program will call GetApprovedManifest without the target parameter and the manifest server should choose a reasonable default target.
153
154GetManifest(tag)
155Return a manifest in which each project is pegged to the revision at the specified tag. This is used by repo sync when the --smart-tag option is given.
156
157Element project
158One or more project elements may be specified. Each element describes a single Git repository to be cloned into the repo client workspace. You may specify Git-submodules by creating a nested project. Git-submodules will be automatically recognized and inherit their parent's attributes, but those may be overridden by an explicitly specified project element.
159
160Attribute name: A unique name for this project. The project‘s name is appended onto its remote’s fetch URL to generate the actual URL to configure the Git remote with. The URL gets formed as:
161
162${remote_fetch}/${project_name}.git
163where ${remote_fetch} is the remote‘s fetch attribute and ${project_name} is the project’s name attribute. The suffix “.git†is always appended as repo assumes the upstream is a forest of bare Git repositories. If the project has a parent element, its name will be prefixed by the parent's.
164
165The project name must match the name Gerrit knows, if Gerrit is being used for code reviews.
166
167Attribute path: An optional path relative to the top directory of the repo client where the Git working directory for this project should be placed. If not supplied the project name is used. If the project has a parent element, its path will be prefixed by the parent's.
168
169Attribute remote: Name of a previously defined remote element. If not supplied the remote given by the default element is used.
170
171Attribute revision: Name of the Git branch the manifest wants to track for this project. Names can be relative to refs/heads (e.g. just “masterâ€) or absolute (e.g. “refs/heads/masterâ€). Tags and/or explicit SHA-1s should work in theory, but have not been extensively tested. If not supplied the revision given by the remote element is used if applicable, else the default element is used.
172
173Attribute dest-branch: Name of a Git branch (e.g. master). When using repo upload, changes will be submitted for code review on this branch. If unspecified both here and in the default element, revision is used instead.
174
175Attribute groups: List of groups to which this project belongs, whitespace or comma separated. All projects belong to the group “allâ€, and each project automatically belongs to a group of its name:name and path:path. E.g. for , that project definition is implicitly in the following manifest groups: default, name:monkeys, and path:barrel-of. If you place a project in the group “notdefaultâ€, it will not be automatically downloaded by repo. If the project has a parent element, the name and path here are the prefixed ones.
176
177Attribute sync-c: Set to true to only sync the given Git branch (specified in the revision attribute) rather than the whole ref space.
178
179Attribute sync-s: Set to true to also sync sub-projects.
180
181Attribute upstream: Name of the Git ref in which a sha1 can be found. Used when syncing a revision locked manifest in -c mode to avoid having to sync the entire ref space.
182
183Attribute clone-depth: Set the depth to use when fetching this project. If specified, this value will override any value given to repo init with the --depth option on the command line.
184
185Attribute force-path: Set to true to force this project to create the local mirror repository according to its path attribute (if supplied) rather than the name attribute. This attribute only applies to the local mirrors syncing, it will be ignored when syncing the projects in a client working directory.
186
187Element extend-project
188Modify the attributes of the named project.
189
190This element is mostly useful in a local manifest file, to modify the attributes of an existing project without completely replacing the existing project definition. This makes the local manifest more robust against changes to the original manifest.
191
192Attribute path: If specified, limit the change to projects checked out at the specified path, rather than all projects with the given name.
193
194Attribute groups: List of additional groups to which this project belongs. Same syntax as the corresponding element of project.
195
196Attribute revision: If specified, overrides the revision of the original project. Same syntax as the corresponding element of project.
197
198Element annotation
199Zero or more annotation elements may be specified as children of a project element. Each element describes a name-value pair that will be exported into each project's environment during a ‘forall’ command, prefixed with REPO__. In addition, there is an optional attribute “keep†which accepts the case insensitive values “true†(default) or “falseâ€. This attribute determines whether or not the annotation will be kept when exported with the manifest subcommand.
200
201Element copyfile
202Zero or more copyfile elements may be specified as children of a project element. Each element describes a src-dest pair of files; the “src†file will be copied to the “dest†place during repo sync command. “src†is project relative, “dest†is relative to the top of the tree.
203
204Element linkfile
205It's just like copyfile and runs at the same time as copyfile but instead of copying it creates a symlink.
206
207Element remove-project
208Deletes the named project from the internal manifest table, possibly allowing a subsequent project element in the same manifest file to replace the project with a different source.
209
210This element is mostly useful in a local manifest file, where the user can remove a project, and possibly replace it with their own definition.
211
212Element include
213This element provides the capability of including another manifest file into the originating manifest. Normal rules apply for the target manifest to include - it must be a usable manifest on its own.
214
215Attribute name: the manifest to include, specified relative to the manifest repository's root.
216
217Local Manifests
218Additional remotes and projects may be added through local manifest files stored in $TOP_DIR/.repo/local_manifests/*.xml.
219
220For example:
221
222$ ls .repo/local_manifests
223local_manifest.xml
224another_local_manifest.xml
225
226$ cat .repo/local_manifests/local_manifest.xml
227<?xml version="1.0" encoding="UTF-8"?>
228<manifest>
229 <project path="manifest"
230 name="tools/manifest" />
231 <project path="platform-manifest"
232 name="platform/manifest" />
233</manifest>
234Users may add projects to the local manifest(s) prior to a repo sync invocation, instructing repo to automatically download and manage these extra projects.
235
236Manifest files stored in $TOP_DIR/.repo/local_manifests/*.xml will be loaded in alphabetical order.
237
238Additional remotes and projects may also be added through a local manifest, stored in $TOP_DIR/.repo/local_manifest.xml. This method is deprecated in favor of using multiple manifest files as mentioned above.
239
240If $TOP_DIR/.repo/local_manifest.xml exists, it will be loaded before any manifest files stored in $TOP_DIR/.repo/local_manifests/*.xml.
241
242Powered by Gitiles| Privacy