1REPO(1) Repo Manual REPO(1)
2
3
4
6 repo - repo manifest - manual page for repo manifest
7
9 repo manifest [-o {-|NAME.xml}] [-m MANIFEST.xml] [-r]
10
12 Summary
13
14 Manifest inspection utility
15
17 -h, --help
18 show this help message and exit
19
20 -r, --revision-as-HEAD
21 save revisions as current HEAD
22
23 -m NAME.xml, --manifest-name=NAME.xml
24 temporary manifest to use for this sync
25
26 --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
30 --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
34 --json output manifest in JSON format (experimental)
35
36 --pretty
37 format output for humans to read
38
39 --no-local-manifests
40 ignore local manifests
41
42 -o -|NAME.xml, --output-file=-|NAME.xml
43 file to save the manifest to. (Filename prefix for multi-tree.)
44
45 Logging options:
46 -v, --verbose
47 show all output
48
49 -q, --quiet
50 only show errors
51
52 Multi-manifest options:
53 --outer-manifest
54 operate starting at the outermost manifest
55
56 --no-outer-manifest
57 do not operate on outer manifests
58
59 --this-manifest-only
60 only operate on this (sub)manifest
61
62 --no-this-manifest-only, --all-manifests
63 operate on this manifest and its submanifests
64
65 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
73 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
80 repo Manifest Format
81
82 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
86 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
89 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
93 [TOC]
94
95 XML File Format
96
97 A manifest XML file (e.g. `default.xml`) roughly conforms to the fol‐
98 lowing DTD:
99
100 ```xml <!DOCTYPE manifest [
101
102 <!ELEMENT manifest (notice?,
103 remote*, default?, manifest-server?, submanifest*?, re‐
104 move-project*, project*, extend-project*, repo-hooks?, superpro‐
105 ject?, contactinfo?, include*)>
106
107 <!ELEMENT notice (#PCDATA)>
108
109 <!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
115 <!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
123 <!ELEMENT manifest-server EMPTY> <!ATTLIST manifest-server url
124 CDATA #REQUIRED>
125
126 <!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
135 <!ELEMENT project (annotation*,
136 project*, copyfile*, linkfile*)>
137
138 <!ATTLIST project name
139 CDATA #REQUIRED>
140
141 <!ATTLIST project path
142 CDATA #IMPLIED>
143
144 <!ATTLIST project remote
145 IDREF #IMPLIED>
146
147 <!ATTLIST project revision
148 CDATA #IMPLIED>
149
150 <!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
157 <!ELEMENT annotation EMPTY> <!ATTLIST annotation name CDATA
158 #REQUIRED> <!ATTLIST annotation value CDATA #REQUIRED> <!ATTLIST
159 annotation keep CDATA "true">
160
161 <!ELEMENT copyfile EMPTY> <!ATTLIST copyfile src CDATA #RE‐
162 QUIRED> <!ATTLIST copyfile dest CDATA #REQUIRED>
163
164 <!ELEMENT linkfile EMPTY> <!ATTLIST linkfile src CDATA #RE‐
165 QUIRED> <!ATTLIST linkfile dest CDATA #REQUIRED>
166
167 <!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
174 <!ELEMENT remove-project EMPTY> <!ATTLIST remove-project name
175 CDATA #REQUIRED> <!ATTLIST remove-project optional CDATA #IM‐
176 PLIED>
177
178 <!ELEMENT repo-hooks EMPTY> <!ATTLIST repo-hooks in-project
179 CDATA #REQUIRED> <!ATTLIST repo-hooks enabled-list CDATA #RE‐
180 QUIRED>
181
182 <!ELEMENT superproject EMPTY> <!ATTLIST superproject name
183 CDATA #REQUIRED> <!ATTLIST superproject remote IDREF #IMPLIED>
184 <!ATTLIST superproject revision CDATA #IMPLIED>
185
186 <!ELEMENT contactinfo EMPTY> <!ATTLIST contactinfo bugurl CDATA
187 #REQUIRED>
188
189 <!ELEMENT include EMPTY> <!ATTLIST include name CDATA #RE‐
190 QUIRED> <!ATTLIST include groups CDATA #IMPLIED>
191
192 ]> ```
193
194 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
200 A description of the elements and their attributes follows.
201
202 Element manifest
203
204 The root element of the file.
205
206 Element notice
207
208 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
212 Element remote
213
214 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
218 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
223 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
229 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
233 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
239 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
243 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
247 Element default
248
249 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
253 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
257 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
261 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
266 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
271 Attribute `sync-j`: Number of parallel jobs to use when synching.
272
273 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
278 Attribute `sync-s`: Set to true to also sync sub-projects.
279
280 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
283 Element manifest-server
284
285 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
288 The manifest server should implement the following RPC methods:
289
290 GetApprovedManifest(branch, target)
291
292 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
296 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
303 GetManifest(tag)
304
305 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
309 Element submanifest
310
311 One or more submanifest elements may be specified. Each element de‐
312 scribes a single manifest to be checked out as a child.
313
314 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
318 Attribute `remote`: Name of a previously defined remote element. If not
319 supplied the remote given by the default element is used.
320
321 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
325 ${remote_fetch}/${project_name}.git
326
327 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
333 The project name must match the name Gerrit knows, if Gerrit is being
334 used for code reviews.
335
336 `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
341 If not supplied the remote and project for this manifest will be used:
342 `remote` cannot be supplied.
343
344 Projects from a submanifest and its submanifests are added to the sub‐
345 manifest::path:<path_prefix> group.
346
347 Attribute `manifest-name`: The manifest filename in the manifest
348 project. If not supplied, `default.xml` is used.
349
350 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
354 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
358 `path` may not be an absolute path or use "." or ".." path components.
359
360 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
365 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
369 Element project
370
371 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
377 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
381 ${remote_fetch}/${project_name}.git
382
383 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
389 The project name must match the name Gerrit knows, if Gerrit is being
390 used for code reviews.
391
392 "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
398 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
403 "path" may not be an absolute path or use "." or ".." path components.
404 These restrictions are not enforced for [Local Manifests].
405
406 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
410 Attribute `remote`: Name of a previously defined remote element. If not
411 supplied the remote given by the default element is used.
412
413 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
420 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
425 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
435 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
439 Attribute `sync-s`: Set to true to also sync sub-projects.
440
441 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
445 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
449 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
455 Element extend-project
456
457 Modify the attributes of the named project.
458
459 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
464 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
468 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
473 Attribute `groups`: List of additional groups to which this project be‐
474 longs. Same syntax as the corresponding element of `project`.
475
476 Attribute `revision`: If specified, overrides the revision of the orig‐
477 inal project. Same syntax as the corresponding element of `project`.
478
479 Attribute `remote`: If specified, overrides the remote of the original
480 project. Same syntax as the corresponding element of `project`.
481
482 Element annotation
483
484 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
493 Element copyfile
494
495 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
500 "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
504 "src" and "dest" must be files. Directories or symlinks are not al‐
505 lowed. Intermediate paths must not be symlinks either.
506
507 Parent directories of "dest" will be automatically created if missing.
508
509 Element linkfile
510
511 It's just like copyfile and runs at the same time as copyfile but in‐
512 stead of copying it creates a symlink.
513
514 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
517 Parent directories of "dest" will be automatically created if missing.
518
519 The symlink target may be a file or directory, but it may not point
520 outside of the repo client.
521
522 Element remove-project
523
524 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
528 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
532 Attribute `optional`: Set to true to ignore remove-project elements
533 with no matching `project` element.
534
535 Element repo-hooks
536
537 NB: See the [practical documentation](./repo-hooks.md) for using repo
538 hooks.
539
540 Only one repo-hooks element may be specified at a time. Attempting to
541 redefine it will fail to parse.
542
543 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
547 Attribute `enabled-list`: List of hooks to use, whitespace or comma
548 separated.
549
550 Element superproject
551
552 *** *Note*: This is currently a WIP. ***
553
554 NB: See the [git superprojects documentation]( https://en.wiki‐
555 books.org/wiki/Git/Submodules_and_Superprojects) for background infor‐
556 mation.
557
558 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
563 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
567 Attribute `remote`: Name of a previously defined remote element. If not
568 supplied the remote given by the default element is used.
569
570 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
574 Element contactinfo
575
576 *** *Note*: This is currently a WIP. ***
577
578 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
584 Attribute `bugurl`: The URL to file a bug against the manifest owner.
585
586 Element include
587
588 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
592 Attribute `name`: the manifest to include, specified relative to the
593 manifest repository's root.
594
595 "name" may not be an absolute path or use "." or ".." path components.
596 These restrictions are not enforced for [Local Manifests].
597
598 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
603 Local Manifests
604
605 Additional remotes and projects may be added through local manifest
606 files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.
607
608 For example:
609
610 $ ls .repo/local_manifests
611
612 local_manifest.xml another_local_manifest.xml
613
614 $ cat .repo/local_manifests/local_manifest.xml
615
616 <?xml version="1.0" encoding="UTF-8"?> <manifest>
617
618 <project path="manifest"
619
620 name="tools/manifest" />
621
622 <project path="platform-manifest"
623
624 name="platform/manifest" />
625
626 </manifest>
627
628 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
632 Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will be
633 loaded in alphabetical order.
634
635 Projects from local manifest files are added into local::<local mani‐
636 fest filename> group.
637
638 The legacy `$TOP_DIR/.repo/local_manifest.xml` path is no longer sup‐
639 ported.
640
641 [copyfile]: #Element-copyfile [linkfile]: #Element-linkfile [Local Mani‐
642 fests]:
643 #local-manifests
644
645
646
647repo manifest July 2022 REPO(1)