1REPO(1) Repo Manual REPO(1)
2
6 repo - repo manifest - manual page for repo manifest
7
9 repo manifest [-o {-|NAME.xml}] [-m MANIFEST.xml] [-r]
10
12 Summary
13 Manifest inspection utility
15
17 -h, --help
18 show this help message and exit
19 -r, --revision-as-HEAD
21 save revisions as current HEAD
22 -m NAME.xml, --manifest-name=NAME.xml
24 temporary manifest to use for this sync
25 --suppress-upstream-revision
27 if in -r mode, do not write the upstream field (only of use if
28 the branch names for a sha1 manifest are sensitive)
29 --suppress-dest-branch
31 if in -r mode, do not write the dest-branch field (only of use
32 if the branch names for a sha1 manifest are sensitive)
33 --json output manifest in JSON format (experimental)
35 --pretty
37 format output for humans to read
38 --no-local-manifests
40 ignore local manifests
41 -o -|NAME.xml, --output-file=-|NAME.xml
43 file to save the manifest to
44 Logging options:
46 -v, --verbose
47 show all output
48 -q, --quiet
50 only show errors
51 Run `repo help manifest` to view the detailed manual.
53
55 With the -o option, exports the current manifest for inspection. The
56 manifest and (if present) local_manifests/ are combined together to
57 produce a single manifest file. This file can be stored in a Git repos‐
58 itory for use during future 'repo init' invocations.
59 The -r option can be used to generate a manifest file with project re‐
61 visions set to the current commit hash. These are known as "revision
62 locked manifests", as they don't follow a particular branch. In this
63 case, the 'upstream' attribute is set to the ref we were on when the
64 manifest was generated. The 'dest-branch' attribute is set to indicate
65 the remote ref to push changes to via 'repo upload'.
66 repo Manifest Format
68 A repo manifest describes the structure of a repo client; that is the
70 directories that are visible and where they should be obtained from
71 with git.
72 The basic structure of a manifest is a bare Git repository holding a
74 single `default.xml` XML file in the top level directory.
75 Manifests are inherently version controlled, since they are kept within
77 a Git repository. Updates to manifests are automatically obtained by
78 clients during `repo sync`.
79 [TOC]
81 XML File Format
83 A manifest XML file (e.g. `default.xml`) roughly conforms to the fol‐
85 lowing DTD:
86 ```xml <!DOCTYPE manifest [
88 <!ELEMENT manifest (notice?,
90 remote*, default?, manifest-server?, remove-project*, project*,
91 extend-project*, repo-hooks?, superproject?, contactinfo?, in‐
92 clude*)>
93 <!ELEMENT notice (#PCDATA)>
95 <!ELEMENT remote (annotation*)> <!ATTLIST remote name ID
97 #REQUIRED> <!ATTLIST remote alias CDATA #IMPLIED> <!AT‐
98 TLIST remote fetch CDATA #REQUIRED> <!ATTLIST remote
99 pushurl CDATA #IMPLIED> <!ATTLIST remote review CDATA
100 #IMPLIED> <!ATTLIST remote revision CDATA #IMPLIED>
101 <!ELEMENT default EMPTY> <!ATTLIST default remote IDREF
103 #IMPLIED> <!ATTLIST default revision CDATA #IMPLIED> <!AT‐
104 TLIST default dest-branch CDATA #IMPLIED> <!ATTLIST default up‐
105 stream CDATA #IMPLIED> <!ATTLIST default sync-j CDATA
106 #IMPLIED> <!ATTLIST default sync-c CDATA #IMPLIED> <!AT‐
107 TLIST default sync-s CDATA #IMPLIED> <!ATTLIST default
108 sync-tags CDATA #IMPLIED>
109 <!ELEMENT manifest-server EMPTY> <!ATTLIST manifest-server url
111 CDATA #REQUIRED>
112 <!ELEMENT project (annotation*,
114 project*, copyfile*, linkfile*)>
115 <!ATTLIST project name
117 CDATA #REQUIRED>
118 <!ATTLIST project path
120 CDATA #IMPLIED>
121 <!ATTLIST project remote
123 IDREF #IMPLIED>
124 <!ATTLIST project revision
126 CDATA #IMPLIED>
127 <!ATTLIST project dest-branch CDATA #IMPLIED> <!ATTLIST project
129 groups CDATA #IMPLIED> <!ATTLIST project sync-c CDATA
130 #IMPLIED> <!ATTLIST project sync-s CDATA #IMPLIED> <!AT‐
131 TLIST project sync-tags CDATA #IMPLIED> <!ATTLIST project up‐
132 stream CDATA #IMPLIED> <!ATTLIST project clone-depth CDATA #IM‐
133 PLIED> <!ATTLIST project force-path CDATA #IMPLIED>
134 <!ELEMENT annotation EMPTY> <!ATTLIST annotation name CDATA
136 #REQUIRED> <!ATTLIST annotation value CDATA #REQUIRED> <!ATTLIST
137 annotation keep CDATA "true">
138 <!ELEMENT copyfile EMPTY> <!ATTLIST copyfile src CDATA #RE‐
140 QUIRED> <!ATTLIST copyfile dest CDATA #REQUIRED>
141 <!ELEMENT linkfile EMPTY> <!ATTLIST linkfile src CDATA #RE‐
143 QUIRED> <!ATTLIST linkfile dest CDATA #REQUIRED>
144 <!ELEMENT extend-project EMPTY> <!ATTLIST extend-project name
146 CDATA #REQUIRED> <!ATTLIST extend-project path CDATA #IMPLIED>
147 <!ATTLIST extend-project dest-path CDATA #IMPLIED> <!ATTLIST ex‐
148 tend-project groups CDATA #IMPLIED> <!ATTLIST extend-project re‐
149 vision CDATA #IMPLIED> <!ATTLIST extend-project remote CDATA
150 #IMPLIED>
151 <!ELEMENT remove-project EMPTY> <!ATTLIST remove-project name
153 CDATA #REQUIRED> <!ATTLIST remove-project optional CDATA #IM‐
154 PLIED>
155 <!ELEMENT repo-hooks EMPTY> <!ATTLIST repo-hooks in-project
157 CDATA #REQUIRED> <!ATTLIST repo-hooks enabled-list CDATA #RE‐
158 QUIRED>
159 <!ELEMENT superproject EMPTY> <!ATTLIST superproject name
161 CDATA #REQUIRED> <!ATTLIST superproject remote IDREF #IMPLIED>
162 <!ATTLIST superproject revision CDATA #IMPLIED>
163 <!ELEMENT contactinfo EMPTY> <!ATTLIST contactinfo bugurl CDATA
165 #REQUIRED>
166 <!ELEMENT include EMPTY> <!ATTLIST include name CDATA #RE‐
168 QUIRED> <!ATTLIST include groups CDATA #IMPLIED>
169 ]> ```
171 For compatibility purposes across repo releases, all unknown elements
173 are silently ignored. However, repo reserves all possible names for it‐
174 self for future use. If you want to use custom elements, the `x-*`
175 namespace is reserved for that purpose, and repo guarantees to never
176 allocate any corresponding names.
177 A description of the elements and their attributes follows.
179 Element manifest
181 The root element of the file.
183 Element notice
185 Arbitrary text that is displayed to users whenever `repo sync` fin‐
187 ishes. The content is simply passed through as it exists in the mani‐
188 fest.
189 Element remote
191 One or more remote elements may be specified. Each remote element spec‐
193 ifies a Git URL shared by one or more projects and (optionally) the
194 Gerrit review server those projects upload changes through.
195 Attribute `name`: A short name unique to this manifest file. The name
197 specified here is used as the remote name in each project's .git/con‐
198 fig, and is therefore automatically available to commands like `git
199 fetch`, `git remote`, `git pull` and `git push`.
200 Attribute `alias`: The alias, if specified, is used to override `name`
202 to be set as the remote name in each project's .git/config. Its value
203 can be duplicated while attribute `name` has to be unique in the mani‐
204 fest file. This helps each project to be able to have same remote name
205 which actually points to different remote url.
206 Attribute `fetch`: The Git URL prefix for all projects which use this
208 remote. Each project's name is appended to this prefix to form the ac‐
209 tual URL used to clone the project.
210 Attribute `pushurl`: The Git "push" URL prefix for all projects which
212 use this remote. Each project's name is appended to this prefix to form
213 the actual URL used to "git push" the project. This attribute is op‐
214 tional; if not specified then "git push" will use the same URL as the
215 `fetch` attribute.
216 Attribute `review`: Hostname of the Gerrit server where reviews are up‐
218 loaded to by `repo upload`. This attribute is optional; if not speci‐
219 fied then `repo upload` will not function.
220 Attribute `revision`: Name of a Git branch (e.g. `main` or
222 `refs/heads/main`). Remotes with their own revision will override the
223 default revision.
224 Element default
226 At most one default element may be specified. Its remote and revision
228 attributes are used when a project element does not specify its own re‐
229 mote or revision attribute.
230 Attribute `remote`: Name of a previously defined remote element.
232 Project elements lacking a remote attribute of their own will use this
233 remote.
234 Attribute `revision`: Name of a Git branch (e.g. `main` or
236 `refs/heads/main`). Project elements lacking their own revision attri‐
237 bute will use this revision.
238 Attribute `dest-branch`: Name of a Git branch (e.g. `main`). Project
240 elements not setting their own `dest-branch` will inherit this value.
241 If this value is not set, projects will use `revision` by default in‐
242 stead.
243 Attribute `upstream`: Name of the Git ref in which a sha1 can be found.
245 Used when syncing a revision locked manifest in -c mode to avoid having
246 to sync the entire ref space. Project elements not setting their own
247 `upstream` will inherit this value.
248 Attribute `sync-j`: Number of parallel jobs to use when synching.
250 Attribute `sync-c`: Set to true to only sync the given Git branch
252 (specified in the `revision` attribute) rather than the whole ref
253 space. Project elements lacking a sync-c element of their own will use
254 this value.
255 Attribute `sync-s`: Set to true to also sync sub-projects.
257 Attribute `sync-tags`: Set to false to only sync the given Git branch
259 (specified in the `revision` attribute) rather than the other ref tags.
260 Element manifest-server
262 At most one manifest-server may be specified. The url attribute is used
264 to specify the URL of a manifest server, which is an XML RPC service.
265 The manifest server should implement the following RPC methods:
267 GetApprovedManifest(branch, target)
269 Return a manifest in which each project is pegged to a known good revi‐
271 sion for the current branch and target. This is used by repo sync when
272 the --smart-sync option is given.
273 The target to use is defined by environment variables TARGET_PRODUCT
275 and TARGET_BUILD_VARIANT. These variables are used to create a string
276 of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userde‐
277 bug. If one of those variables or both are not present, the program
278 will call GetApprovedManifest without the target parameter and the man‐
279 ifest server should choose a reasonable default target.
280 GetManifest(tag)
282 Return a manifest in which each project is pegged to the revision at
284 the specified tag. This is used by repo sync when the --smart-tag op‐
285 tion is given.
286 Element project
288 One or more project elements may be specified. Each element describes a
290 single Git repository to be cloned into the repo client workspace. You
291 may specify Git-submodules by creating a nested project. Git-submodules
292 will be automatically recognized and inherit their parent's attributes,
293 but those may be overridden by an explicitly specified project element.
294 Attribute `name`: A unique name for this project. The project's name is
296 appended onto its remote's fetch URL to generate the actual URL to con‐
297 figure the Git remote with. The URL gets formed as:
298 ${remote_fetch}/${project_name}.git
300 where ${remote_fetch} is the remote's fetch attribute and
302 ${project_name} is the project's name attribute. The suffix ".git" is
303 always appended as repo assumes the upstream is a forest of bare Git
304 repositories. If the project has a parent element, its name will be
305 prefixed by the parent's.
306 The project name must match the name Gerrit knows, if Gerrit is being
308 used for code reviews.
309 "name" must not be empty, and may not be an absolute path or use "." or
311 ".." path components. It is always interpreted relative to the re‐
312 mote's fetch settings, so if a different base path is needed, declare a
313 different remote with the new settings needed. These restrictions are
314 not enforced for [Local Manifests].
315 Attribute `path`: An optional path relative to the top directory of the
317 repo client where the Git working directory for this project should be
318 placed. If not supplied the project "name" is used. If the project has
319 a parent element, its path will be prefixed by the parent's.
320 "path" may not be an absolute path or use "." or ".." path components.
322 These restrictions are not enforced for [Local Manifests].
323 If you want to place files into the root of the checkout (e.g. a README
325 or Makefile or another build script), use the [copyfile] or [linkfile]
326 elements instead.
327 Attribute `remote`: Name of a previously defined remote element. If not
329 supplied the remote given by the default element is used.
330 Attribute `revision`: Name of the Git branch the manifest wants to
332 track for this project. Names can be relative to refs/heads (e.g. just
333 "main") or absolute (e.g. "refs/heads/main"). Tags and/or explicit
334 SHA-1s should work in theory, but have not been extensively tested. If
335 not supplied the revision given by the remote element is used if appli‐
336 cable, else the default element is used.
337 Attribute `dest-branch`: Name of a Git branch (e.g. `main`). When using
339 `repo upload`, changes will be submitted for code review on this
340 branch. If unspecified both here and in the default element, `revision`
341 is used instead.
342 Attribute `groups`: List of groups to which this project belongs,
344 whitespace or comma separated. All projects belong to the group "all",
345 and each project automatically belongs to a group of its name:`name`
346 and path:`path`. E.g. for `<project name="monkeys" path="barrel-of"/>`,
347 that project definition is implicitly in the following manifest groups:
348 default, name:monkeys, and path:barrel-of. If you place a project in
349 the group "notdefault", it will not be automatically downloaded by
350 repo. If the project has a parent element, the `name` and `path` here
351 are the prefixed ones.
352 Attribute `sync-c`: Set to true to only sync the given Git branch
354 (specified in the `revision` attribute) rather than the whole ref
355 space.
356 Attribute `sync-s`: Set to true to also sync sub-projects.
358 Attribute `upstream`: Name of the Git ref in which a sha1 can be found.
360 Used when syncing a revision locked manifest in -c mode to avoid having
361 to sync the entire ref space.
362 Attribute `clone-depth`: Set the depth to use when fetching this
364 project. If specified, this value will override any value given to repo
365 init with the --depth option on the command line.
366 Attribute `force-path`: Set to true to force this project to create the
368 local mirror repository according to its `path` attribute (if supplied)
369 rather than the `name` attribute. This attribute only applies to the
370 local mirrors syncing, it will be ignored when syncing the projects in
371 a client working directory.
372 Element extend-project
374 Modify the attributes of the named project.
376 This element is mostly useful in a local manifest file, to modify the
378 attributes of an existing project without completely replacing the ex‐
379 isting project definition. This makes the local manifest more robust
380 against changes to the original manifest.
381 Attribute `path`: If specified, limit the change to projects checked
383 out at the specified path, rather than all projects with the given
384 name.
385 Attribute `dest-path`: If specified, a path relative to the top direc‐
387 tory of the repo client where the Git working directory for this
388 project should be placed. This is used to move a project in the check‐
389 out by overriding the existing `path` setting.
390 Attribute `groups`: List of additional groups to which this project be‐
392 longs. Same syntax as the corresponding element of `project`.
393 Attribute `revision`: If specified, overrides the revision of the orig‐
395 inal project. Same syntax as the corresponding element of `project`.
396 Attribute `remote`: If specified, overrides the remote of the original
398 project. Same syntax as the corresponding element of `project`.
399 Element annotation
401 Zero or more annotation elements may be specified as children of a
403 project or remote element. Each element describes a name-value pair.
404 For projects, this name-value pair will be exported into each project's
405 environment during a 'forall' command, prefixed with `REPO__`. In addi‐
406 tion, there is an optional attribute "keep" which accepts the case in‐
407 sensitive values "true" (default) or "false". This attribute determines
408 whether or not the annotation will be kept when exported with the mani‐
409 fest subcommand.
410 Element copyfile
412 Zero or more copyfile elements may be specified as children of a
414 project element. Each element describes a src-dest pair of files; the
415 "src" file will be copied to the "dest" place during `repo sync` com‐
416 mand.
417 "src" is project relative, "dest" is relative to the top of the tree.
419 Copying from paths outside of the project or to paths outside of the
420 repo client is not allowed.
421 "src" and "dest" must be files. Directories or symlinks are not al‐
423 lowed. Intermediate paths must not be symlinks either.
424 Parent directories of "dest" will be automatically created if missing.
426 Element linkfile
428 It's just like copyfile and runs at the same time as copyfile but in‐
430 stead of copying it creates a symlink.
431 The symlink is created at "dest" (relative to the top of the tree) and
433 points to the path specified by "src" which is a path in the project.
434 Parent directories of "dest" will be automatically created if missing.
436 The symlink target may be a file or directory, but it may not point
438 outside of the repo client.
439 Element remove-project
441 Deletes the named project from the internal manifest table, possibly
443 allowing a subsequent project element in the same manifest file to re‐
444 place the project with a different source.
445 This element is mostly useful in a local manifest file, where the user
447 can remove a project, and possibly replace it with their own defini‐
448 tion.
449 Attribute `optional`: Set to true to ignore remove-project elements
451 with no matching `project` element.
452 Element repo-hooks
454 NB: See the [practical documentation](./repo-hooks.md) for using repo
456 hooks.
457 Only one repo-hooks element may be specified at a time. Attempting to
459 redefine it will fail to parse.
460 Attribute `in-project`: The project where the hooks are defined. The
462 value must match the `name` attribute (**not** the `path` attribute) of
463 a previously defined `project` element.
464 Attribute `enabled-list`: List of hooks to use, whitespace or comma
466 separated.
467 Element superproject
469 *** *Note*: This is currently a WIP. ***
471 NB: See the [git superprojects documentation]( https://en.wiki‐
473 books.org/wiki/Git/Submodules_and_Superprojects) for background infor‐
474 mation.
475 This element is used to specify the URL of the superproject. It has
477 "name" and "remote" as atrributes. Only "name" is required while the
478 others have reasonable defaults. At most one superproject may be speci‐
479 fied. Attempting to redefine it will fail to parse.
480 Attribute `name`: A unique name for the superproject. This attribute
482 has the same meaning as project's name attribute. See the [element
483 project](#element-project) for more information.
484 Attribute `remote`: Name of a previously defined remote element. If not
486 supplied the remote given by the default element is used.
487 Attribute `revision`: Name of the Git branch the manifest wants to
489 track for this superproject. If not supplied the revision given by the
490 remote element is used if applicable, else the default element is used.
491 Element contactinfo
493 *** *Note*: This is currently a WIP. ***
495 This element is used to let manifest authors self-register contact
497 info. It has "bugurl" as a required atrribute. This element can be re‐
498 peated, and any later entries will clobber earlier ones. This would al‐
499 low manifest authors who extend manifests to specify their own contact
500 info.
501 Attribute `bugurl`: The URL to file a bug against the manifest owner.
503 Element include
505 This element provides the capability of including another manifest file
507 into the originating manifest. Normal rules apply for the target mani‐
508 fest to include - it must be a usable manifest on its own.
509 Attribute `name`: the manifest to include, specified relative to the
511 manifest repository's root.
512 "name" may not be an absolute path or use "." or ".." path components.
514 These restrictions are not enforced for [Local Manifests].
515 Attribute `groups`: List of additional groups to which all projects in
517 the included manifest belong. This appends and recurses, meaning all
518 projects in sub-manifests carry all parent include groups. Same syntax
519 as the corresponding element of `project`.
520 Local Manifests
522 Additional remotes and projects may be added through local manifest
524 files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
525 For example:
527 $ ls .repo/local_manifests
529 local_manifest.xml another_local_manifest.xml
531 $ cat .repo/local_manifests/local_manifest.xml
533 <?xml version="1.0" encoding="UTF-8"?> <manifest>
535 <project path="manifest"
537 name="tools/manifest" />
539 <project path="platform-manifest"
541 name="platform/manifest" />
543 </manifest>
545 Users may add projects to the local manifest(s) prior to a `repo sync`
547 invocation, instructing repo to automatically download and manage these
548 extra projects.
549 Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will be
551 loaded in alphabetical order.
552 Projects from local manifest files are added into local::<local mani‐
554 fest filename> group.
555 The legacy `$TOP_DIR/.repo/local_manifest.xml` path is no longer sup‐
557 ported.
558 [copyfile]: #Element-copyfile [linkfile]: #Element-linkfile [Local Mani‐
560 fests]:
561 #local-manifests
562repo manifest November 2021 REPO(1)