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