blob: 562e66e2fe8d73d3cd310d6ae1e0aa2e94517035 [file] [log] [blame]
Shawn O. Pearce3e548192008-11-04 11:19:36 -08001repo Manifest Format
2====================
3
4A repo manifest describes the structure of a repo client; that is
5the directories that are visible and where they should be obtained
6from with git.
7
8The basic structure of a manifest is a bare Git repository holding
9a single 'default.xml' XML file in the top level directory.
10
11Manifests are inherently version controlled, since they are kept
12within a Git repository. Updates to manifests are automatically
13obtained by clients during `repo sync`.
14
15
16XML File Format
17---------------
18
19A manifest XML file (e.g. 'default.xml') roughly conforms to the
20following DTD:
21
22<!DOCTYPE manifest [
Shawn O. Pearce70939e22008-11-06 11:07:14 -080023 <!ELEMENT manifest (remote*,
24 default?,
Shawn O. Pearce03eaf072008-11-20 11:42:22 -080025 remove-project*,
Shawn O. Pearce70939e22008-11-06 11:07:14 -080026 project*,
27 add-remote*)>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080028
29 <!ELEMENT remote (EMPTY)>
Shawn O. Pearceae6e0942008-11-06 10:25:35 -080030 <!ATTLIST remote name ID #REQUIRED>
31 <!ATTLIST remote fetch CDATA #REQUIRED>
32 <!ATTLIST remote review CDATA #IMPLIED>
33 <!ATTLIST remote project-name CDATA #IMPLIED>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080034
35 <!ELEMENT default (EMPTY)>
36 <!ATTLIST default remote IDREF #IMPLIED>
37 <!ATTLIST default revision CDATA #IMPLIED>
38
39 <!ELEMENT project (remote*)>
40 <!ATTLIST project name CDATA #REQUIRED>
41 <!ATTLIST project path CDATA #IMPLIED>
42 <!ATTLIST project remote IDREF #IMPLIED>
43 <!ATTLIST project revision CDATA #IMPLIED>
Shawn O. Pearce70939e22008-11-06 11:07:14 -080044
45 <!ELEMENT add-remote (EMPTY)>
46 <!ATTLIST add-remote to-project ID #REQUIRED>
47 <!ATTLIST add-remote name ID #REQUIRED>
48 <!ATTLIST add-remote fetch CDATA #REQUIRED>
49 <!ATTLIST add-remote review CDATA #IMPLIED>
50 <!ATTLIST add-remote project-name CDATA #IMPLIED>
Shawn O. Pearce03eaf072008-11-20 11:42:22 -080051
52 <!ELEMENT remove-project (EMPTY)>
53 <!ATTLIST remove-project name CDATA #REQUIRED>
Shawn O. Pearce3e548192008-11-04 11:19:36 -080054]>
55
56A description of the elements and their attributes follows.
57
58
59Element manifest
60----------------
61
62The root element of the file.
63
64
65Element remote
66--------------
67
68One or more remote elements may be specified. Each remote element
69specifies a Git URL shared by one or more projects and (optionally)
70the Gerrit review server those projects upload changes through.
71
72Attribute `name`: A short name unique to this manifest file. The
73name specified here is used as the remote name in each project's
74.git/config, and is therefore automatically available to commands
75like `git fetch`, `git remote`, `git pull` and `git push`.
76
77Attribute `fetch`: The Git URL prefix for all projects which use
78this remote. Each project's name is appended to this prefix to
79form the actual URL used to clone the project.
80
81Attribute `review`: Hostname of the Gerrit server where reviews
82are uploaded to by `repo upload`. This attribute is optional;
83if not specified then `repo upload` will not function.
84
Shawn O. Pearceae6e0942008-11-06 10:25:35 -080085Attribute `project-name`: Specifies the name of this project used
86by the review server given in the review attribute of this element.
87Only permitted when the remote element is nested inside of a project
88element (see below). If not given, defaults to the name supplied
89in the project's name attribute.
90
Shawn O. Pearce70939e22008-11-06 11:07:14 -080091Element add-remote
92------------------
93
94Adds a remote to an existing project, whose name is given by the
95to-project attribute. This is functionally equivalent to nesting
96a remote element under the project, but has the advantage that it
97can be specified in the uesr's `local_manifest.xml` to add a remote
98to a project declared by the normal manifest.
99
100The element can be used to add a fork of an existing project that
101the user needs to work with.
102
Shawn O. Pearce3e548192008-11-04 11:19:36 -0800103
104Element default
105---------------
106
107At most one default element may be specified. Its remote and
108revision attributes are used when a project element does not
109specify its own remote or revision attribute.
110
111Attribute `remote`: Name of a previously defined remote element.
112Project elements lacking a remote attribute of their own will use
113this remote.
114
115Attribute `revision`: Name of a Git branch (e.g. `master` or
116`refs/heads/master`). Project elements lacking their own
117revision attribute will use this revision.
118
119
120Element project
121---------------
122
123One or more project elements may be specified. Each element
124describes a single Git repository to be cloned into the repo
125client workspace.
126
127Attribute `name`: A unique name for this project. The project's
128name is appended onto its remote's fetch URL to generate the actual
129URL to configure the Git remote with. The URL gets formed as:
130
131 ${remote_fetch}/${project_name}.git
132
133where ${remote_fetch} is the remote's fetch attribute and
134${project_name} is the project's name attribute. The suffix ".git"
135is always appended as repo assumes the upstream is a forrest of
136bare Git repositories.
137
138The project name must match the name Gerrit knows, if Gerrit is
139being used for code reviews.
140
141Attribute `path`: An optional path relative to the top directory
142of the repo client where the Git working directory for this project
143should be placed. If not supplied the project name is used.
144
145Attribute `remote`: Name of a previously defined remote element.
146If not supplied the remote given by the default element is used.
147
148Attribute `revision`: Name of the Git branch the manifest wants
149to track for this project. Names can be relative to refs/heads
150(e.g. just "master") or absolute (e.g. "refs/heads/master").
151Tags and/or explicit SHA-1s should work in theory, but have not
152been extensively tested. If not supplied the revision given by
153the default element is used.
154
155Child element `remote`: Described like the top-level remote element,
156but adds an additional remote to only this project. These additional
157remotes are fetched from first on the initial `repo sync`, causing
158the majority of the project's object database to be obtained through
159these additional remotes.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800160
161
Shawn O. Pearce03eaf072008-11-20 11:42:22 -0800162Element remove-project
163----------------------
164
165Deletes the named project from the internal manifest table, possibly
166allowing a subsequent project element in the same manifest file to
167replace the project with a different source.
168
169This element is mostly useful in the local_manifest.xml, where
170the user can remove a project, and possibly replace it with their
171own definition.
172
173
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800174Local Manifest
175==============
176
177Additional remotes and projects may be added through a local
178manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`.
179
180For example:
181
182----
183 $ cat .repo/local_manifest.xml
184 <?xml version="1.0" encoding="UTF-8"?>
185 <manifest>
186 <project path="manifest"
187 name="tools/manifest" />
188 <project path="platform-manifest"
189 name="platform/manifest" />
190 </manifest>
191----
192
193Users may add projects to the local manifest prior to a `repo sync`
194invocation, instructing repo to automatically download and manage
195these extra projects.
196
197Currently the only supported feature of a local manifest is to
198add new remotes and/or projects. In the future a local manifest
199may support picking different revisions of a project, or deleting
200projects specified in the default manifest.