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. (Filename prefix for multi-tree.)
44 Logging options:
46 -v, --verbose
47 show all output
48 -q, --quiet
50 only show errors
51 Multi-manifest options:
53 --outer-manifest
54 operate starting at the outermost manifest
55 --no-outer-manifest
57 do not operate on outer manifests
58 --this-manifest-only
60 only operate on this (sub)manifest
61 --no-this-manifest-only, --all-manifests
63 operate on this manifest and its submanifests
64 Run `repo help manifest` to view the detailed manual.
66
68 With the -o option, exports the current manifest for inspection. The
69 manifest and (if present) local_manifests/ are combined together to
70 produce a single manifest file. This file can be stored in a Git repos‐
71 itory for use during future 'repo init' invocations.
72 The -r option can be used to generate a manifest file with project re‐
74 visions set to the current commit hash. These are known as "revision
75 locked manifests", as they don't follow a particular branch. In this
76 case, the 'upstream' attribute is set to the ref we were on when the
77 manifest was generated. The 'dest-branch' attribute is set to indicate
78 the remote ref to push changes to via 'repo upload'.
79 repo Manifest Format
81 A repo manifest describes the structure of a repo client; that is the
83 directories that are visible and where they should be obtained from
84 with git.
85 The basic structure of a manifest is a bare Git repository holding a
87 single `default.xml` XML file in the top level directory.
88 Manifests are inherently version controlled, since they are kept within
90 a Git repository. Updates to manifests are automatically obtained by
91 clients during `repo sync`.
92 [TOC]
94 XML File Format
96 A manifest XML file (e.g. `default.xml`) roughly conforms to the fol‐
98 lowing DTD:
99 ```xml <!DOCTYPE manifest [
101 <!ELEMENT manifest (notice?,
103 remote*, default?, manifest-server?, submanifest*?, re‐
104 move-project*, project*, extend-project*, repo-hooks?, superpro‐
105 ject?, contactinfo?, include*)>
106 <!ELEMENT notice (#PCDATA)>
108 <!ELEMENT remote (annotation*)> <!ATTLIST remote name ID
110 #REQUIRED> <!ATTLIST remote alias CDATA #IMPLIED> <!AT‐
111 TLIST remote fetch CDATA #REQUIRED> <!ATTLIST remote
112 pushurl CDATA #IMPLIED> <!ATTLIST remote review CDATA
113 #IMPLIED> <!ATTLIST remote revision CDATA #IMPLIED>
114 <!ELEMENT default EMPTY> <!ATTLIST default remote IDREF
116 #IMPLIED> <!ATTLIST default revision CDATA #IMPLIED> <!AT‐
117 TLIST default dest-branch CDATA #IMPLIED> <!ATTLIST default up‐
118 stream CDATA #IMPLIED> <!ATTLIST default sync-j CDATA
119 #IMPLIED> <!ATTLIST default sync-c CDATA #IMPLIED> <!AT‐
120 TLIST default sync-s CDATA #IMPLIED> <!ATTLIST default
121 sync-tags CDATA #IMPLIED>
122 <!ELEMENT manifest-server EMPTY> <!ATTLIST manifest-server url
124 CDATA #REQUIRED>
125 <!ELEMENT submanifest EMPTY> <!ATTLIST submanifest name
127 ID #REQUIRED> <!ATTLIST submanifest remote IDREF #IM‐
128 PLIED> <!ATTLIST submanifest project CDATA #IMPLIED>
129 <!ATTLIST submanifest manifest-name CDATA #IMPLIED> <!ATTLIST
130 submanifest revision CDATA #IMPLIED> <!ATTLIST submanifest
131 path CDATA #IMPLIED> <!ATTLIST submanifest groups
132 CDATA #IMPLIED> <!ATTLIST submanifest default-groups CDATA #IM‐
133 PLIED>
134 <!ELEMENT project (annotation*,
136 project*, copyfile*, linkfile*)>
137 <!ATTLIST project name
139 CDATA #REQUIRED>
140 <!ATTLIST project path
142 CDATA #IMPLIED>
143 <!ATTLIST project remote
145 IDREF #IMPLIED>
146 <!ATTLIST project revision
148 CDATA #IMPLIED>
149 <!ATTLIST project dest-branch CDATA #IMPLIED> <!ATTLIST project
151 groups CDATA #IMPLIED> <!ATTLIST project sync-c CDATA
152 #IMPLIED> <!ATTLIST project sync-s CDATA #IMPLIED> <!AT‐
153 TLIST project sync-tags CDATA #IMPLIED> <!ATTLIST project up‐
154 stream CDATA #IMPLIED> <!ATTLIST project clone-depth CDATA #IM‐
155 PLIED> <!ATTLIST project force-path CDATA #IMPLIED>
156 <!ELEMENT annotation EMPTY> <!ATTLIST annotation name CDATA
158 #REQUIRED> <!ATTLIST annotation value CDATA #REQUIRED> <!ATTLIST
159 annotation keep CDATA "true">
160 <!ELEMENT copyfile EMPTY> <!ATTLIST copyfile src CDATA #RE‐
162 QUIRED> <!ATTLIST copyfile dest CDATA #REQUIRED>
163 <!ELEMENT linkfile EMPTY> <!ATTLIST linkfile src CDATA #RE‐
165 QUIRED> <!ATTLIST linkfile dest CDATA #REQUIRED>
166 <!ELEMENT extend-project EMPTY> <!ATTLIST extend-project name
168 CDATA #REQUIRED> <!ATTLIST extend-project path CDATA #IMPLIED>
169 <!ATTLIST extend-project dest-path CDATA #IMPLIED> <!ATTLIST ex‐
170 tend-project groups CDATA #IMPLIED> <!ATTLIST extend-project re‐
171 vision CDATA #IMPLIED> <!ATTLIST extend-project remote CDATA
172 #IMPLIED> <!ATTLIST extend-project dest-branch CDATA #IMPLIED>
173 <!ATTLIST extend-project upstream CDATA #IMPLIED>
174 <!ELEMENT remove-project EMPTY> <!ATTLIST remove-project name
176 CDATA #REQUIRED> <!ATTLIST remove-project optional CDATA #IM‐
177 PLIED>
178 <!ELEMENT repo-hooks EMPTY> <!ATTLIST repo-hooks in-project
180 CDATA #REQUIRED> <!ATTLIST repo-hooks enabled-list CDATA #RE‐
181 QUIRED>
182 <!ELEMENT superproject EMPTY> <!ATTLIST superproject name
184 CDATA #REQUIRED> <!ATTLIST superproject remote IDREF #IMPLIED>
185 <!ATTLIST superproject revision CDATA #IMPLIED>
186 <!ELEMENT contactinfo EMPTY> <!ATTLIST contactinfo bugurl CDATA
188 #REQUIRED>
189 <!ELEMENT include EMPTY> <!ATTLIST include name CDATA #RE‐
191 QUIRED> <!ATTLIST include groups CDATA #IMPLIED>
192 ]> ```
194 For compatibility purposes across repo releases, all unknown elements
196 are silently ignored. However, repo reserves all possible names for it‐
197 self for future use. If you want to use custom elements, the `x-*`
198 namespace is reserved for that purpose, and repo guarantees to never
199 allocate any corresponding names.
200 A description of the elements and their attributes follows.
202 Element manifest
204 The root element of the file.
206 Element notice
208 Arbitrary text that is displayed to users whenever `repo sync` fin‐
210 ishes. The content is simply passed through as it exists in the mani‐
211 fest.
212 Element remote
214 One or more remote elements may be specified. Each remote element spec‐
216 ifies a Git URL shared by one or more projects and (optionally) the
217 Gerrit review server those projects upload changes through.
218 Attribute `name`: A short name unique to this manifest file. The name
220 specified here is used as the remote name in each project's .git/con‐
221 fig, and is therefore automatically available to commands like `git
222 fetch`, `git remote`, `git pull` and `git push`.
223 Attribute `alias`: The alias, if specified, is used to override `name`
225 to be set as the remote name in each project's .git/config. Its value
226 can be duplicated while attribute `name` has to be unique in the mani‐
227 fest file. This helps each project to be able to have same remote name
228 which actually points to different remote url.
229 Attribute `fetch`: The Git URL prefix for all projects which use this
231 remote. Each project's name is appended to this prefix to form the ac‐
232 tual URL used to clone the project.
233 Attribute `pushurl`: The Git "push" URL prefix for all projects which
235 use this remote. Each project's name is appended to this prefix to form
236 the actual URL used to "git push" the project. This attribute is op‐
237 tional; if not specified then "git push" will use the same URL as the
238 `fetch` attribute.
239 Attribute `review`: Hostname of the Gerrit server where reviews are up‐
241 loaded to by `repo upload`. This attribute is optional; if not speci‐
242 fied then `repo upload` will not function.
243 Attribute `revision`: Name of a Git branch (e.g. `main` or
245 `refs/heads/main`). Remotes with their own revision will override the
246 default revision.
247 Element default
249 At most one default element may be specified. Its remote and revision
251 attributes are used when a project element does not specify its own re‐
252 mote or revision attribute.
253 Attribute `remote`: Name of a previously defined remote element.
255 Project elements lacking a remote attribute of their own will use this
256 remote.
257 Attribute `revision`: Name of a Git branch (e.g. `main` or
259 `refs/heads/main`). Project elements lacking their own revision attri‐
260 bute will use this revision.
261 Attribute `dest-branch`: Name of a Git branch (e.g. `main`). Project
263 elements not setting their own `dest-branch` will inherit this value.
264 If this value is not set, projects will use `revision` by default in‐
265 stead.
266 Attribute `upstream`: Name of the Git ref in which a sha1 can be found.
268 Used when syncing a revision locked manifest in -c mode to avoid having
269 to sync the entire ref space. Project elements not setting their own
270 `upstream` will inherit this value.
271 Attribute `sync-j`: Number of parallel jobs to use when synching.
273 Attribute `sync-c`: Set to true to only sync the given Git branch
275 (specified in the `revision` attribute) rather than the whole ref
276 space. Project elements lacking a sync-c element of their own will use
277 this value.
278 Attribute `sync-s`: Set to true to also sync sub-projects.
280 Attribute `sync-tags`: Set to false to only sync the given Git branch
282 (specified in the `revision` attribute) rather than the other ref tags.
283 Element manifest-server
285 At most one manifest-server may be specified. The url attribute is used
287 to specify the URL of a manifest server, which is an XML RPC service.
288 The manifest server should implement the following RPC methods:
290 GetApprovedManifest(branch, target)
292 Return a manifest in which each project is pegged to a known good revi‐
294 sion for the current branch and target. This is used by repo sync when
295 the --smart-sync option is given.
296 The target to use is defined by environment variables TARGET_PRODUCT
298 and TARGET_BUILD_VARIANT. These variables are used to create a string
299 of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userde‐
300 bug. If one of those variables or both are not present, the program
301 will call GetApprovedManifest without the target parameter and the man‐
302 ifest server should choose a reasonable default target.
303 GetManifest(tag)
305 Return a manifest in which each project is pegged to the revision at
307 the specified tag. This is used by repo sync when the --smart-tag op‐
308 tion is given.
309 Element submanifest
311 One or more submanifest elements may be specified. Each element de‐
313 scribes a single manifest to be checked out as a child.
314 Attribute `name`: A unique name (within the current (sub)manifest) for
316 this submanifest. It acts as a default for `revision` below. The same
317 name can be used for submanifests with different parent (sub)manifests.
318 Attribute `remote`: Name of a previously defined remote element. If not
320 supplied the remote given by the default element is used.
321 Attribute `project`: The manifest project name. The project's name is
323 appended onto its remote's fetch URL to generate the actual URL to con‐
324 figure the Git remote with. The URL gets formed as:
325 ${remote_fetch}/${project_name}.git
327 where ${remote_fetch} is the remote's fetch attribute and
329 ${project_name} is the project's name attribute. The suffix ".git" is
330 always appended as repo assumes the upstream is a forest of bare Git
331 repositories. If the project has a parent element, its name will be
332 prefixed by the parent's.
333 The project name must match the name Gerrit knows, if Gerrit is being
335 used for code reviews.
336 `project` must not be empty, and may not be an absolute path or use "."
338 or ".." path components. It is always interpreted relative to the re‐
339 mote's fetch settings, so if a different base path is needed, declare a
340 different remote with the new settings needed.
341 If not supplied the remote and project for this manifest will be used:
343 `remote` cannot be supplied.
344 Projects from a submanifest and its submanifests are added to the sub‐
346 manifest::path:<path_prefix> group.
347 Attribute `manifest-name`: The manifest filename in the manifest
349 project. If not supplied, `default.xml` is used.
350 Attribute `revision`: Name of a Git branch (e.g. "main" or
352 "refs/heads/main"), tag (e.g. "refs/tags/stable"), or a commit hash. If
353 not supplied, `name` is used.
354 Attribute `path`: An optional path relative to the top directory of the
356 repo client where the submanifest repo client top directory should be
357 placed. If not supplied, `revision` is used.
358 `path` may not be an absolute path or use "." or ".." path components.
360 Attribute `groups`: List of additional groups to which all projects in
362 the included submanifest belong. This appends and recurses, meaning all
363 projects in submanifests carry all parent submanifest groups. Same syn‐
364 tax as the corresponding element of `project`.
365 Attribute `default-groups`: The list of manifest groups to sync if no
367 `--groups=` parameter was specified at init. When that list is empty,
368 use this list instead of "default" as the list of groups to sync.
369 Element project
371 One or more project elements may be specified. Each element describes a
373 single Git repository to be cloned into the repo client workspace. You
374 may specify Git-submodules by creating a nested project. Git-submodules
375 will be automatically recognized and inherit their parent's attributes,
376 but those may be overridden by an explicitly specified project element.
377 Attribute `name`: A unique name for this project. The project's name is
379 appended onto its remote's fetch URL to generate the actual URL to con‐
380 figure the Git remote with. The URL gets formed as:
381 ${remote_fetch}/${project_name}.git
383 where ${remote_fetch} is the remote's fetch attribute and
385 ${project_name} is the project's name attribute. The suffix ".git" is
386 always appended as repo assumes the upstream is a forest of bare Git
387 repositories. If the project has a parent element, its name will be
388 prefixed by the parent's.
389 The project name must match the name Gerrit knows, if Gerrit is being
391 used for code reviews.
392 "name" must not be empty, and may not be an absolute path or use "." or
394 ".." path components. It is always interpreted relative to the re‐
395 mote's fetch settings, so if a different base path is needed, declare a
396 different remote with the new settings needed. These restrictions are
397 not enforced for [Local Manifests].
398 Attribute `path`: An optional path relative to the top directory of the
400 repo client where the Git working directory for this project should be
401 placed. If not supplied the project "name" is used. If the project has
402 a parent element, its path will be prefixed by the parent's.
403 "path" may not be an absolute path or use "." or ".." path components.
405 These restrictions are not enforced for [Local Manifests].
406 If you want to place files into the root of the checkout (e.g. a README
408 or Makefile or another build script), use the [copyfile] or [linkfile]
409 elements instead.
410 Attribute `remote`: Name of a previously defined remote element. If not
412 supplied the remote given by the default element is used.
413 Attribute `revision`: Name of the Git branch the manifest wants to
415 track for this project. Names can be relative to refs/heads (e.g. just
416 "main") or absolute (e.g. "refs/heads/main"). Tags and/or explicit
417 SHA-1s should work in theory, but have not been extensively tested. If
418 not supplied the revision given by the remote element is used if appli‐
419 cable, else the default element is used.
420 Attribute `dest-branch`: Name of a Git branch (e.g. `main`). When using
422 `repo upload`, changes will be submitted for code review on this
423 branch. If unspecified both here and in the default element, `revision`
424 is used instead.
425 Attribute `groups`: List of groups to which this project belongs,
427 whitespace or comma separated. All projects belong to the group "all",
428 and each project automatically belongs to a group of its name:`name`
429 and path:`path`. E.g. for `<project name="monkeys" path="barrel-of"/>`,
430 that project definition is implicitly in the following manifest groups:
431 default, name:monkeys, and path:barrel-of. If you place a project in
432 the group "notdefault", it will not be automatically downloaded by
433 repo. If the project has a parent element, the `name` and `path` here
434 are the prefixed ones.
435 Attribute `sync-c`: Set to true to only sync the given Git branch
437 (specified in the `revision` attribute) rather than the whole ref
438 space.
439 Attribute `sync-s`: Set to true to also sync sub-projects.
441 Attribute `upstream`: Name of the Git ref in which a sha1 can be found.
443 Used when syncing a revision locked manifest in -c mode to avoid having
444 to sync the entire ref space.
445 Attribute `clone-depth`: Set the depth to use when fetching this
447 project. If specified, this value will override any value given to repo
448 init with the --depth option on the command line.
449 Attribute `force-path`: Set to true to force this project to create the
451 local mirror repository according to its `path` attribute (if supplied)
452 rather than the `name` attribute. This attribute only applies to the
453 local mirrors syncing, it will be ignored when syncing the projects in
454 a client working directory.
455 Element extend-project
457 Modify the attributes of the named project.
459 This element is mostly useful in a local manifest file, to modify the
461 attributes of an existing project without completely replacing the ex‐
462 isting project definition. This makes the local manifest more robust
463 against changes to the original manifest.
464 Attribute `path`: If specified, limit the change to projects checked
466 out at the specified path, rather than all projects with the given
467 name.
468 Attribute `dest-path`: If specified, a path relative to the top direc‐
470 tory of the repo client where the Git working directory for this
471 project should be placed. This is used to move a project in the check‐
472 out by overriding the existing `path` setting.
473 Attribute `groups`: List of additional groups to which this project be‐
475 longs. Same syntax as the corresponding element of `project`.
476 Attribute `revision`: If specified, overrides the revision of the orig‐
478 inal project. Same syntax as the corresponding element of `project`.
479 Attribute `remote`: If specified, overrides the remote of the original
481 project. Same syntax as the corresponding element of `project`.
482 Attribute `dest-branch`: If specified, overrides the dest-branch of the
484 original project. Same syntax as the corresponding element of
485 `project`.
486 Attribute `upstream`: If specified, overrides the upstream of the orig‐
488 inal project. Same syntax as the corresponding element of `project`.
489 Element annotation
491 Zero or more annotation elements may be specified as children of a
493 project or remote element. Each element describes a name-value pair.
494 For projects, this name-value pair will be exported into each project's
495 environment during a 'forall' command, prefixed with `REPO__`. In addi‐
496 tion, there is an optional attribute "keep" which accepts the case in‐
497 sensitive values "true" (default) or "false". This attribute determines
498 whether or not the annotation will be kept when exported with the mani‐
499 fest subcommand.
500 Element copyfile
502 Zero or more copyfile elements may be specified as children of a
504 project element. Each element describes a src-dest pair of files; the
505 "src" file will be copied to the "dest" place during `repo sync` com‐
506 mand.
507 "src" is project relative, "dest" is relative to the top of the tree.
509 Copying from paths outside of the project or to paths outside of the
510 repo client is not allowed.
511 "src" and "dest" must be files. Directories or symlinks are not al‐
513 lowed. Intermediate paths must not be symlinks either.
514 Parent directories of "dest" will be automatically created if missing.
516 Element linkfile
518 It's just like copyfile and runs at the same time as copyfile but in‐
520 stead of copying it creates a symlink.
521 The symlink is created at "dest" (relative to the top of the tree) and
523 points to the path specified by "src" which is a path in the project.
524 Parent directories of "dest" will be automatically created if missing.
526 The symlink target may be a file or directory, but it may not point
528 outside of the repo client.
529 Element remove-project
531 Deletes the named project from the internal manifest table, possibly
533 allowing a subsequent project element in the same manifest file to re‐
534 place the project with a different source.
535 This element is mostly useful in a local manifest file, where the user
537 can remove a project, and possibly replace it with their own defini‐
538 tion.
539 Attribute `optional`: Set to true to ignore remove-project elements
541 with no matching `project` element.
542 Element repo-hooks
544 NB: See the [practical documentation](./repo-hooks.md) for using repo
546 hooks.
547 Only one repo-hooks element may be specified at a time. Attempting to
549 redefine it will fail to parse.
550 Attribute `in-project`: The project where the hooks are defined. The
552 value must match the `name` attribute (**not** the `path` attribute) of
553 a previously defined `project` element.
554 Attribute `enabled-list`: List of hooks to use, whitespace or comma
556 separated.
557 Element superproject
559 *** *Note*: This is currently a WIP. ***
561 NB: See the [git superprojects documentation]( https://en.wiki‐
563 books.org/wiki/Git/Submodules_and_Superprojects) for background infor‐
564 mation.
565 This element is used to specify the URL of the superproject. It has
567 "name" and "remote" as atrributes. Only "name" is required while the
568 others have reasonable defaults. At most one superproject may be speci‐
569 fied. Attempting to redefine it will fail to parse.
570 Attribute `name`: A unique name for the superproject. This attribute
572 has the same meaning as project's name attribute. See the [element
573 project](#element-project) for more information.
574 Attribute `remote`: Name of a previously defined remote element. If not
576 supplied the remote given by the default element is used.
577 Attribute `revision`: Name of the Git branch the manifest wants to
579 track for this superproject. If not supplied the revision given by the
580 remote element is used if applicable, else the default element is used.
581 Element contactinfo
583 *** *Note*: This is currently a WIP. ***
585 This element is used to let manifest authors self-register contact
587 info. It has "bugurl" as a required atrribute. This element can be re‐
588 peated, and any later entries will clobber earlier ones. This would al‐
589 low manifest authors who extend manifests to specify their own contact
590 info.
591 Attribute `bugurl`: The URL to file a bug against the manifest owner.
593 Element include
595 This element provides the capability of including another manifest file
597 into the originating manifest. Normal rules apply for the target mani‐
598 fest to include - it must be a usable manifest on its own.
599 Attribute `name`: the manifest to include, specified relative to the
601 manifest repository's root.
602 "name" may not be an absolute path or use "." or ".." path components.
604 These restrictions are not enforced for [Local Manifests].
605 Attribute `groups`: List of additional groups to which all projects in
607 the included manifest belong. This appends and recurses, meaning all
608 projects in included manifests carry all parent include groups. Same
609 syntax as the corresponding element of `project`.
610 Local Manifests
612 Additional remotes and projects may be added through local manifest
614 files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
615 For example:
617 $ ls .repo/local_manifests
619 local_manifest.xml another_local_manifest.xml
621 $ cat .repo/local_manifests/local_manifest.xml
623 <?xml version="1.0" encoding="UTF-8"?> <manifest>
625 <project path="manifest"
627 name="tools/manifest" />
629 <project path="platform-manifest"
631 name="platform/manifest" />
633 </manifest>
635 Users may add projects to the local manifest(s) prior to a `repo sync`
637 invocation, instructing repo to automatically download and manage these
638 extra projects.
639 Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will be
641 loaded in alphabetical order.
642 Projects from local manifest files are added into local::<local mani‐
644 fest filename> group.
645 The legacy `$TOP_DIR/.repo/local_manifest.xml` path is no longer sup‐
647 ported.
648 [copyfile]: #Element-copyfile [linkfile]: #Element-linkfile [Local Mani‐
650 fests]:
651 #local-manifests
652repo manifest October 2022 REPO(1)