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>
173 <!ELEMENT remove-project EMPTY> <!ATTLIST remove-project name
175 CDATA #REQUIRED> <!ATTLIST remove-project optional CDATA #IM‐
176 PLIED>
177 <!ELEMENT repo-hooks EMPTY> <!ATTLIST repo-hooks in-project
179 CDATA #REQUIRED> <!ATTLIST repo-hooks enabled-list CDATA #RE‐
180 QUIRED>
181 <!ELEMENT superproject EMPTY> <!ATTLIST superproject name
183 CDATA #REQUIRED> <!ATTLIST superproject remote IDREF #IMPLIED>
184 <!ATTLIST superproject revision CDATA #IMPLIED>
185 <!ELEMENT contactinfo EMPTY> <!ATTLIST contactinfo bugurl CDATA
187 #REQUIRED>
188 <!ELEMENT include EMPTY> <!ATTLIST include name CDATA #RE‐
190 QUIRED> <!ATTLIST include groups CDATA #IMPLIED>
191 ]> ```
193 For compatibility purposes across repo releases, all unknown elements
195 are silently ignored. However, repo reserves all possible names for it‐
196 self for future use. If you want to use custom elements, the `x-*`
197 namespace is reserved for that purpose, and repo guarantees to never
198 allocate any corresponding names.
199 A description of the elements and their attributes follows.
201 Element manifest
203 The root element of the file.
205 Element notice
207 Arbitrary text that is displayed to users whenever `repo sync` fin‐
209 ishes. The content is simply passed through as it exists in the mani‐
210 fest.
211 Element remote
213 One or more remote elements may be specified. Each remote element spec‐
215 ifies a Git URL shared by one or more projects and (optionally) the
216 Gerrit review server those projects upload changes through.
217 Attribute `name`: A short name unique to this manifest file. The name
219 specified here is used as the remote name in each project's .git/con‐
220 fig, and is therefore automatically available to commands like `git
221 fetch`, `git remote`, `git pull` and `git push`.
222 Attribute `alias`: The alias, if specified, is used to override `name`
224 to be set as the remote name in each project's .git/config. Its value
225 can be duplicated while attribute `name` has to be unique in the mani‐
226 fest file. This helps each project to be able to have same remote name
227 which actually points to different remote url.
228 Attribute `fetch`: The Git URL prefix for all projects which use this
230 remote. Each project's name is appended to this prefix to form the ac‐
231 tual URL used to clone the project.
232 Attribute `pushurl`: The Git "push" URL prefix for all projects which
234 use this remote. Each project's name is appended to this prefix to form
235 the actual URL used to "git push" the project. This attribute is op‐
236 tional; if not specified then "git push" will use the same URL as the
237 `fetch` attribute.
238 Attribute `review`: Hostname of the Gerrit server where reviews are up‐
240 loaded to by `repo upload`. This attribute is optional; if not speci‐
241 fied then `repo upload` will not function.
242 Attribute `revision`: Name of a Git branch (e.g. `main` or
244 `refs/heads/main`). Remotes with their own revision will override the
245 default revision.
246 Element default
248 At most one default element may be specified. Its remote and revision
250 attributes are used when a project element does not specify its own re‐
251 mote or revision attribute.
252 Attribute `remote`: Name of a previously defined remote element.
254 Project elements lacking a remote attribute of their own will use this
255 remote.
256 Attribute `revision`: Name of a Git branch (e.g. `main` or
258 `refs/heads/main`). Project elements lacking their own revision attri‐
259 bute will use this revision.
260 Attribute `dest-branch`: Name of a Git branch (e.g. `main`). Project
262 elements not setting their own `dest-branch` will inherit this value.
263 If this value is not set, projects will use `revision` by default in‐
264 stead.
265 Attribute `upstream`: Name of the Git ref in which a sha1 can be found.
267 Used when syncing a revision locked manifest in -c mode to avoid having
268 to sync the entire ref space. Project elements not setting their own
269 `upstream` will inherit this value.
270 Attribute `sync-j`: Number of parallel jobs to use when synching.
272 Attribute `sync-c`: Set to true to only sync the given Git branch
274 (specified in the `revision` attribute) rather than the whole ref
275 space. Project elements lacking a sync-c element of their own will use
276 this value.
277 Attribute `sync-s`: Set to true to also sync sub-projects.
279 Attribute `sync-tags`: Set to false to only sync the given Git branch
281 (specified in the `revision` attribute) rather than the other ref tags.
282 Element manifest-server
284 At most one manifest-server may be specified. The url attribute is used
286 to specify the URL of a manifest server, which is an XML RPC service.
287 The manifest server should implement the following RPC methods:
289 GetApprovedManifest(branch, target)
291 Return a manifest in which each project is pegged to a known good revi‐
293 sion for the current branch and target. This is used by repo sync when
294 the --smart-sync option is given.
295 The target to use is defined by environment variables TARGET_PRODUCT
297 and TARGET_BUILD_VARIANT. These variables are used to create a string
298 of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userde‐
299 bug. If one of those variables or both are not present, the program
300 will call GetApprovedManifest without the target parameter and the man‐
301 ifest server should choose a reasonable default target.
302 GetManifest(tag)
304 Return a manifest in which each project is pegged to the revision at
306 the specified tag. This is used by repo sync when the --smart-tag op‐
307 tion is given.
308 Element submanifest
310 One or more submanifest elements may be specified. Each element de‐
312 scribes a single manifest to be checked out as a child.
313 Attribute `name`: A unique name (within the current (sub)manifest) for
315 this submanifest. It acts as a default for `revision` below. The same
316 name can be used for submanifests with different parent (sub)manifests.
317 Attribute `remote`: Name of a previously defined remote element. If not
319 supplied the remote given by the default element is used.
320 Attribute `project`: The manifest project name. The project's name is
322 appended onto its remote's fetch URL to generate the actual URL to con‐
323 figure the Git remote with. The URL gets formed as:
324 ${remote_fetch}/${project_name}.git
326 where ${remote_fetch} is the remote's fetch attribute and
328 ${project_name} is the project's name attribute. The suffix ".git" is
329 always appended as repo assumes the upstream is a forest of bare Git
330 repositories. If the project has a parent element, its name will be
331 prefixed by the parent's.
332 The project name must match the name Gerrit knows, if Gerrit is being
334 used for code reviews.
335 `project` must not be empty, and may not be an absolute path or use "."
337 or ".." path components. It is always interpreted relative to the re‐
338 mote's fetch settings, so if a different base path is needed, declare a
339 different remote with the new settings needed.
340 If not supplied the remote and project for this manifest will be used:
342 `remote` cannot be supplied.
343 Projects from a submanifest and its submanifests are added to the sub‐
345 manifest::path:<path_prefix> group.
346 Attribute `manifest-name`: The manifest filename in the manifest
348 project. If not supplied, `default.xml` is used.
349 Attribute `revision`: Name of a Git branch (e.g. "main" or
351 "refs/heads/main"), tag (e.g. "refs/tags/stable"), or a commit hash. If
352 not supplied, `name` is used.
353 Attribute `path`: An optional path relative to the top directory of the
355 repo client where the submanifest repo client top directory should be
356 placed. If not supplied, `revision` is used.
357 `path` may not be an absolute path or use "." or ".." path components.
359 Attribute `groups`: List of additional groups to which all projects in
361 the included submanifest belong. This appends and recurses, meaning all
362 projects in submanifests carry all parent submanifest groups. Same syn‐
363 tax as the corresponding element of `project`.
364 Attribute `default-groups`: The list of manifest groups to sync if no
366 `--groups=` parameter was specified at init. When that list is empty,
367 use this list instead of "default" as the list of groups to sync.
368 Element project
370 One or more project elements may be specified. Each element describes a
372 single Git repository to be cloned into the repo client workspace. You
373 may specify Git-submodules by creating a nested project. Git-submodules
374 will be automatically recognized and inherit their parent's attributes,
375 but those may be overridden by an explicitly specified project element.
376 Attribute `name`: A unique name for this project. The project's name is
378 appended onto its remote's fetch URL to generate the actual URL to con‐
379 figure the Git remote with. The URL gets formed as:
380 ${remote_fetch}/${project_name}.git
382 where ${remote_fetch} is the remote's fetch attribute and
384 ${project_name} is the project's name attribute. The suffix ".git" is
385 always appended as repo assumes the upstream is a forest of bare Git
386 repositories. If the project has a parent element, its name will be
387 prefixed by the parent's.
388 The project name must match the name Gerrit knows, if Gerrit is being
390 used for code reviews.
391 "name" must not be empty, and may not be an absolute path or use "." or
393 ".." path components. It is always interpreted relative to the re‐
394 mote's fetch settings, so if a different base path is needed, declare a
395 different remote with the new settings needed. These restrictions are
396 not enforced for [Local Manifests].
397 Attribute `path`: An optional path relative to the top directory of the
399 repo client where the Git working directory for this project should be
400 placed. If not supplied the project "name" is used. If the project has
401 a parent element, its path will be prefixed by the parent's.
402 "path" may not be an absolute path or use "." or ".." path components.
404 These restrictions are not enforced for [Local Manifests].
405 If you want to place files into the root of the checkout (e.g. a README
407 or Makefile or another build script), use the [copyfile] or [linkfile]
408 elements instead.
409 Attribute `remote`: Name of a previously defined remote element. If not
411 supplied the remote given by the default element is used.
412 Attribute `revision`: Name of the Git branch the manifest wants to
414 track for this project. Names can be relative to refs/heads (e.g. just
415 "main") or absolute (e.g. "refs/heads/main"). Tags and/or explicit
416 SHA-1s should work in theory, but have not been extensively tested. If
417 not supplied the revision given by the remote element is used if appli‐
418 cable, else the default element is used.
419 Attribute `dest-branch`: Name of a Git branch (e.g. `main`). When using
421 `repo upload`, changes will be submitted for code review on this
422 branch. If unspecified both here and in the default element, `revision`
423 is used instead.
424 Attribute `groups`: List of groups to which this project belongs,
426 whitespace or comma separated. All projects belong to the group "all",
427 and each project automatically belongs to a group of its name:`name`
428 and path:`path`. E.g. for `<project name="monkeys" path="barrel-of"/>`,
429 that project definition is implicitly in the following manifest groups:
430 default, name:monkeys, and path:barrel-of. If you place a project in
431 the group "notdefault", it will not be automatically downloaded by
432 repo. If the project has a parent element, the `name` and `path` here
433 are the prefixed ones.
434 Attribute `sync-c`: Set to true to only sync the given Git branch
436 (specified in the `revision` attribute) rather than the whole ref
437 space.
438 Attribute `sync-s`: Set to true to also sync sub-projects.
440 Attribute `upstream`: Name of the Git ref in which a sha1 can be found.
442 Used when syncing a revision locked manifest in -c mode to avoid having
443 to sync the entire ref space.
444 Attribute `clone-depth`: Set the depth to use when fetching this
446 project. If specified, this value will override any value given to repo
447 init with the --depth option on the command line.
448 Attribute `force-path`: Set to true to force this project to create the
450 local mirror repository according to its `path` attribute (if supplied)
451 rather than the `name` attribute. This attribute only applies to the
452 local mirrors syncing, it will be ignored when syncing the projects in
453 a client working directory.
454 Element extend-project
456 Modify the attributes of the named project.
458 This element is mostly useful in a local manifest file, to modify the
460 attributes of an existing project without completely replacing the ex‐
461 isting project definition. This makes the local manifest more robust
462 against changes to the original manifest.
463 Attribute `path`: If specified, limit the change to projects checked
465 out at the specified path, rather than all projects with the given
466 name.
467 Attribute `dest-path`: If specified, a path relative to the top direc‐
469 tory of the repo client where the Git working directory for this
470 project should be placed. This is used to move a project in the check‐
471 out by overriding the existing `path` setting.
472 Attribute `groups`: List of additional groups to which this project be‐
474 longs. Same syntax as the corresponding element of `project`.
475 Attribute `revision`: If specified, overrides the revision of the orig‐
477 inal project. Same syntax as the corresponding element of `project`.
478 Attribute `remote`: If specified, overrides the remote of the original
480 project. Same syntax as the corresponding element of `project`.
481 Element annotation
483 Zero or more annotation elements may be specified as children of a
485 project or remote element. Each element describes a name-value pair.
486 For projects, this name-value pair will be exported into each project's
487 environment during a 'forall' command, prefixed with `REPO__`. In addi‐
488 tion, there is an optional attribute "keep" which accepts the case in‐
489 sensitive values "true" (default) or "false". This attribute determines
490 whether or not the annotation will be kept when exported with the mani‐
491 fest subcommand.
492 Element copyfile
494 Zero or more copyfile elements may be specified as children of a
496 project element. Each element describes a src-dest pair of files; the
497 "src" file will be copied to the "dest" place during `repo sync` com‐
498 mand.
499 "src" is project relative, "dest" is relative to the top of the tree.
501 Copying from paths outside of the project or to paths outside of the
502 repo client is not allowed.
503 "src" and "dest" must be files. Directories or symlinks are not al‐
505 lowed. Intermediate paths must not be symlinks either.
506 Parent directories of "dest" will be automatically created if missing.
508 Element linkfile
510 It's just like copyfile and runs at the same time as copyfile but in‐
512 stead of copying it creates a symlink.
513 The symlink is created at "dest" (relative to the top of the tree) and
515 points to the path specified by "src" which is a path in the project.
516 Parent directories of "dest" will be automatically created if missing.
518 The symlink target may be a file or directory, but it may not point
520 outside of the repo client.
521 Element remove-project
523 Deletes the named project from the internal manifest table, possibly
525 allowing a subsequent project element in the same manifest file to re‐
526 place the project with a different source.
527 This element is mostly useful in a local manifest file, where the user
529 can remove a project, and possibly replace it with their own defini‐
530 tion.
531 Attribute `optional`: Set to true to ignore remove-project elements
533 with no matching `project` element.
534 Element repo-hooks
536 NB: See the [practical documentation](./repo-hooks.md) for using repo
538 hooks.
539 Only one repo-hooks element may be specified at a time. Attempting to
541 redefine it will fail to parse.
542 Attribute `in-project`: The project where the hooks are defined. The
544 value must match the `name` attribute (**not** the `path` attribute) of
545 a previously defined `project` element.
546 Attribute `enabled-list`: List of hooks to use, whitespace or comma
548 separated.
549 Element superproject
551 *** *Note*: This is currently a WIP. ***
553 NB: See the [git superprojects documentation]( https://en.wiki‐
555 books.org/wiki/Git/Submodules_and_Superprojects) for background infor‐
556 mation.
557 This element is used to specify the URL of the superproject. It has
559 "name" and "remote" as atrributes. Only "name" is required while the
560 others have reasonable defaults. At most one superproject may be speci‐
561 fied. Attempting to redefine it will fail to parse.
562 Attribute `name`: A unique name for the superproject. This attribute
564 has the same meaning as project's name attribute. See the [element
565 project](#element-project) for more information.
566 Attribute `remote`: Name of a previously defined remote element. If not
568 supplied the remote given by the default element is used.
569 Attribute `revision`: Name of the Git branch the manifest wants to
571 track for this superproject. If not supplied the revision given by the
572 remote element is used if applicable, else the default element is used.
573 Element contactinfo
575 *** *Note*: This is currently a WIP. ***
577 This element is used to let manifest authors self-register contact
579 info. It has "bugurl" as a required atrribute. This element can be re‐
580 peated, and any later entries will clobber earlier ones. This would al‐
581 low manifest authors who extend manifests to specify their own contact
582 info.
583 Attribute `bugurl`: The URL to file a bug against the manifest owner.
585 Element include
587 This element provides the capability of including another manifest file
589 into the originating manifest. Normal rules apply for the target mani‐
590 fest to include - it must be a usable manifest on its own.
591 Attribute `name`: the manifest to include, specified relative to the
593 manifest repository's root.
594 "name" may not be an absolute path or use "." or ".." path components.
596 These restrictions are not enforced for [Local Manifests].
597 Attribute `groups`: List of additional groups to which all projects in
599 the included manifest belong. This appends and recurses, meaning all
600 projects in included manifests carry all parent include groups. Same
601 syntax as the corresponding element of `project`.
602 Local Manifests
604 Additional remotes and projects may be added through local manifest
606 files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
607 For example:
609 $ ls .repo/local_manifests
611 local_manifest.xml another_local_manifest.xml
613 $ cat .repo/local_manifests/local_manifest.xml
615 <?xml version="1.0" encoding="UTF-8"?> <manifest>
617 <project path="manifest"
619 name="tools/manifest" />
621 <project path="platform-manifest"
623 name="platform/manifest" />
625 </manifest>
627 Users may add projects to the local manifest(s) prior to a `repo sync`
629 invocation, instructing repo to automatically download and manage these
630 extra projects.
631 Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will be
633 loaded in alphabetical order.
634 Projects from local manifest files are added into local::<local mani‐
636 fest filename> group.
637 The legacy `$TOP_DIR/.repo/local_manifest.xml` path is no longer sup‐
639 ported.
640 [copyfile]: #Element-copyfile [linkfile]: #Element-linkfile [Local Mani‐
642 fests]:
643 #local-manifests
644repo manifest July 2022 REPO(1)