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