diff options
Diffstat (limited to 'docs/manifest-format.txt')
| -rw-r--r-- | docs/manifest-format.txt | 186 |
1 files changed, 0 insertions, 186 deletions
diff --git a/docs/manifest-format.txt b/docs/manifest-format.txt deleted file mode 100644 index 2e1c8c35..00000000 --- a/docs/manifest-format.txt +++ /dev/null | |||
| @@ -1,186 +0,0 @@ | |||
| 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 [ | ||
| 23 | <!ELEMENT manifest (notice?, | ||
| 24 | remote*, | ||
| 25 | default?, | ||
| 26 | manifest-server?, | ||
| 27 | remove-project*, | ||
| 28 | project*)> | ||
| 29 | |||
| 30 | <!ELEMENT notice (#PCDATA)> | ||
| 31 | |||
| 32 | <!ELEMENT remote (EMPTY)> | ||
| 33 | <!ATTLIST remote name ID #REQUIRED> | ||
| 34 | <!ATTLIST remote fetch CDATA #REQUIRED> | ||
| 35 | <!ATTLIST remote review CDATA #IMPLIED> | ||
| 36 | |||
| 37 | <!ELEMENT default (EMPTY)> | ||
| 38 | <!ATTLIST default remote IDREF #IMPLIED> | ||
| 39 | <!ATTLIST default revision CDATA #IMPLIED> | ||
| 40 | |||
| 41 | <!ELEMENT manifest-server (EMPTY)> | ||
| 42 | <!ATTLIST url CDATA #REQUIRED> | ||
| 43 | |||
| 44 | <!ELEMENT project (EMPTY)> | ||
| 45 | <!ATTLIST project name CDATA #REQUIRED> | ||
| 46 | <!ATTLIST project path CDATA #IMPLIED> | ||
| 47 | <!ATTLIST project remote IDREF #IMPLIED> | ||
| 48 | <!ATTLIST project revision CDATA #IMPLIED> | ||
| 49 | |||
| 50 | <!ELEMENT remove-project (EMPTY)> | ||
| 51 | <!ATTLIST remove-project name CDATA #REQUIRED> | ||
| 52 | ]> | ||
| 53 | |||
| 54 | A description of the elements and their attributes follows. | ||
| 55 | |||
| 56 | |||
| 57 | Element manifest | ||
| 58 | ---------------- | ||
| 59 | |||
| 60 | The root element of the file. | ||
| 61 | |||
| 62 | |||
| 63 | Element remote | ||
| 64 | -------------- | ||
| 65 | |||
| 66 | One or more remote elements may be specified. Each remote element | ||
| 67 | specifies a Git URL shared by one or more projects and (optionally) | ||
| 68 | the Gerrit review server those projects upload changes through. | ||
| 69 | |||
| 70 | Attribute `name`: A short name unique to this manifest file. The | ||
| 71 | name specified here is used as the remote name in each project's | ||
| 72 | .git/config, and is therefore automatically available to commands | ||
| 73 | like `git fetch`, `git remote`, `git pull` and `git push`. | ||
| 74 | |||
| 75 | Attribute `fetch`: The Git URL prefix for all projects which use | ||
| 76 | this remote. Each project's name is appended to this prefix to | ||
| 77 | form the actual URL used to clone the project. | ||
| 78 | |||
| 79 | Attribute `review`: Hostname of the Gerrit server where reviews | ||
| 80 | are uploaded to by `repo upload`. This attribute is optional; | ||
| 81 | if not specified then `repo upload` will not function. | ||
| 82 | |||
| 83 | Element default | ||
| 84 | --------------- | ||
| 85 | |||
| 86 | At most one default element may be specified. Its remote and | ||
| 87 | revision attributes are used when a project element does not | ||
| 88 | specify its own remote or revision attribute. | ||
| 89 | |||
| 90 | Attribute `remote`: Name of a previously defined remote element. | ||
| 91 | Project elements lacking a remote attribute of their own will use | ||
| 92 | this remote. | ||
| 93 | |||
| 94 | Attribute `revision`: Name of a Git branch (e.g. `master` or | ||
| 95 | `refs/heads/master`). Project elements lacking their own | ||
| 96 | revision attribute will use this revision. | ||
| 97 | |||
| 98 | |||
| 99 | Element manifest-server | ||
| 100 | ----------------------- | ||
| 101 | |||
| 102 | At most one manifest-server may be specified. The url attribute | ||
| 103 | is used to specify the URL of a manifest server, which is an | ||
| 104 | XML RPC service that will return a manifest in which each project | ||
| 105 | is pegged to a known good revision for the current branch and | ||
| 106 | target. | ||
| 107 | |||
| 108 | The manifest server should implement: | ||
| 109 | |||
| 110 | GetApprovedManifest(branch, target) | ||
| 111 | |||
| 112 | The target to use is defined by environment variables TARGET_PRODUCT | ||
| 113 | and TARGET_BUILD_VARIANT. These variables are used to create a string | ||
| 114 | of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug. | ||
| 115 | If one of those variables or both are not present, the program will call | ||
| 116 | GetApprovedManifest without the target paramater and the manifest server | ||
| 117 | should choose a reasonable default target. | ||
| 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 | Element remove-project | ||
| 156 | ---------------------- | ||
| 157 | |||
| 158 | Deletes the named project from the internal manifest table, possibly | ||
| 159 | allowing a subsequent project element in the same manifest file to | ||
| 160 | replace the project with a different source. | ||
| 161 | |||
| 162 | This element is mostly useful in the local_manifest.xml, where | ||
| 163 | the user can remove a project, and possibly replace it with their | ||
| 164 | own definition. | ||
| 165 | |||
| 166 | |||
| 167 | Local Manifest | ||
| 168 | ============== | ||
| 169 | |||
| 170 | Additional remotes and projects may be added through a local | ||
| 171 | manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. | ||
| 172 | |||
| 173 | For example: | ||
| 174 | |||
| 175 | $ cat .repo/local_manifest.xml | ||
| 176 | <?xml version="1.0" encoding="UTF-8"?> | ||
| 177 | <manifest> | ||
| 178 | <project path="manifest" | ||
| 179 | name="tools/manifest" /> | ||
| 180 | <project path="platform-manifest" | ||
| 181 | name="platform/manifest" /> | ||
| 182 | </manifest> | ||
| 183 | |||
| 184 | Users may add projects to the local manifest prior to a `repo sync` | ||
| 185 | invocation, instructing repo to automatically download and manage | ||
| 186 | these extra projects. | ||
