blob: 409524bbbbf593099c8698c45c2320535d71dcf0 [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 [
23 <!ELEMENT manifest (remote*, default?, project*)>
24
25 <!ELEMENT remote (EMPTY)>
26 <!ATTLIST remote name ID #REQUIRED>
27 <!ATTLIST remote fetch CDATA #REQUIRED>
28 <!ATTLIST remote review CDATA #IMPLIED>
29
30 <!ELEMENT default (EMPTY)>
31 <!ATTLIST default remote IDREF #IMPLIED>
32 <!ATTLIST default revision CDATA #IMPLIED>
33
34 <!ELEMENT project (remote*)>
35 <!ATTLIST project name CDATA #REQUIRED>
36 <!ATTLIST project path CDATA #IMPLIED>
37 <!ATTLIST project remote IDREF #IMPLIED>
38 <!ATTLIST project revision CDATA #IMPLIED>
39]>
40
41A description of the elements and their attributes follows.
42
43
44Element manifest
45----------------
46
47The root element of the file.
48
49
50Element remote
51--------------
52
53One or more remote elements may be specified. Each remote element
54specifies a Git URL shared by one or more projects and (optionally)
55the Gerrit review server those projects upload changes through.
56
57Attribute `name`: A short name unique to this manifest file. The
58name specified here is used as the remote name in each project's
59.git/config, and is therefore automatically available to commands
60like `git fetch`, `git remote`, `git pull` and `git push`.
61
62Attribute `fetch`: The Git URL prefix for all projects which use
63this remote. Each project's name is appended to this prefix to
64form the actual URL used to clone the project.
65
66Attribute `review`: Hostname of the Gerrit server where reviews
67are uploaded to by `repo upload`. This attribute is optional;
68if not specified then `repo upload` will not function.
69
70
71Element default
72---------------
73
74At most one default element may be specified. Its remote and
75revision attributes are used when a project element does not
76specify its own remote or revision attribute.
77
78Attribute `remote`: Name of a previously defined remote element.
79Project elements lacking a remote attribute of their own will use
80this remote.
81
82Attribute `revision`: Name of a Git branch (e.g. `master` or
83`refs/heads/master`). Project elements lacking their own
84revision attribute will use this revision.
85
86
87Element project
88---------------
89
90One or more project elements may be specified. Each element
91describes a single Git repository to be cloned into the repo
92client workspace.
93
94Attribute `name`: A unique name for this project. The project's
95name is appended onto its remote's fetch URL to generate the actual
96URL to configure the Git remote with. The URL gets formed as:
97
98 ${remote_fetch}/${project_name}.git
99
100where ${remote_fetch} is the remote's fetch attribute and
101${project_name} is the project's name attribute. The suffix ".git"
102is always appended as repo assumes the upstream is a forrest of
103bare Git repositories.
104
105The project name must match the name Gerrit knows, if Gerrit is
106being used for code reviews.
107
108Attribute `path`: An optional path relative to the top directory
109of the repo client where the Git working directory for this project
110should be placed. If not supplied the project name is used.
111
112Attribute `remote`: Name of a previously defined remote element.
113If not supplied the remote given by the default element is used.
114
115Attribute `revision`: Name of the Git branch the manifest wants
116to track for this project. Names can be relative to refs/heads
117(e.g. just "master") or absolute (e.g. "refs/heads/master").
118Tags and/or explicit SHA-1s should work in theory, but have not
119been extensively tested. If not supplied the revision given by
120the default element is used.
121
122Child element `remote`: Described like the top-level remote element,
123but adds an additional remote to only this project. These additional
124remotes are fetched from first on the initial `repo sync`, causing
125the majority of the project's object database to be obtained through
126these additional remotes.
Shawn O. Pearce70cd4ab2008-11-06 08:48:44 -0800127
128
129Local Manifest
130==============
131
132Additional remotes and projects may be added through a local
133manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`.
134
135For example:
136
137----
138 $ cat .repo/local_manifest.xml
139 <?xml version="1.0" encoding="UTF-8"?>
140 <manifest>
141 <project path="manifest"
142 name="tools/manifest" />
143 <project path="platform-manifest"
144 name="platform/manifest" />
145 </manifest>
146----
147
148Users may add projects to the local manifest prior to a `repo sync`
149invocation, instructing repo to automatically download and manage
150these extra projects.
151
152Currently the only supported feature of a local manifest is to
153add new remotes and/or projects. In the future a local manifest
154may support picking different revisions of a project, or deleting
155projects specified in the default manifest.