Repo Manifest 格式(XML文件)

最近研究了下Repo相关的东西，在Repo工具包里看了一个关于repo manifest格式（其实就是XML文件了）的文件，叫manifest-format.txt。于是就翻译了下，译得不好，莫见怪。下面是对应的原文和相应的译文。不喜勿喷！

------------------------------------------------------------------------------------------------------------------

--------------------------------------  原  文  如  下  -----------------------------------------------

------------------------------------------------------------------------------------------------------------------

repo Manifest Format
====================

A repo manifest describes the structure of a repo client; that is the directories that are visible and where they should be obtained from with git.

The basic structure of a manifest is a bare Git repository holding a single 'default.xml' XML file in the top level directory.

Manifests are inherently version controlled, since they are kept within a Git repository.  Updates to manifests are automatically obtained by clients during `repo sync`.

XML File Format
---------------

A manifest XML file (e.g. 'default.xml') roughly conforms to the following DTD:

  <!DOCTYPE manifest [
    <!ELEMENT manifest (notice?,
                        remote*,
                        default?,
                        manifest-server?,
                        remove-project*,
                        project*,
                        repo-hooks?)>
  
    <!ELEMENT notice (#PCDATA)>
  
    <!ELEMENT remote (EMPTY)>
    <!ATTLIST remote name         ID    #REQUIRED>
    <!ATTLIST remote alias        CDATA #IMPLIED>
    <!ATTLIST remote fetch        CDATA #REQUIRED>
    <!ATTLIST remote review       CDATA #IMPLIED>
  
    <!ELEMENT default (EMPTY)>
    <!ATTLIST default remote   IDREF #IMPLIED>
    <!ATTLIST default revision CDATA #IMPLIED>
    <!ATTLIST default sync-j   CDATA #IMPLIED>
    <!ATTLIST default sync-c   CDATA #IMPLIED>

    <!ELEMENT manifest-server (EMPTY)>
    <!ATTLIST url              CDATA #REQUIRED>
  
    <!ELEMENT project (annotation?)>
    <!ATTLIST project name     CDATA #REQUIRED>
    <!ATTLIST project path     CDATA #IMPLIED>
    <!ATTLIST project remote   IDREF #IMPLIED>
    <!ATTLIST project revision CDATA #IMPLIED>
    <!ATTLIST project groups   CDATA #IMPLIED>
    <!ATTLIST project sync-c   CDATA #IMPLIED>

    <!ELEMENT annotation (EMPTY)>
    <!ATTLIST annotation name  CDATA #REQUIRED>
    <!ATTLIST annotation value CDATA #REQUIRED>
    <!ATTLIST annotation keep  CDATA "true">
  
    <!ELEMENT remove-project (EMPTY)>
    <!ATTLIST remove-project name  CDATA #REQUIRED>

    <!ELEMENT repo-hooks (EMPTY)>
    <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
    <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>

    <!ELEMENT include      (EMPTY)>
    <!ATTLIST include name CDATA #REQUIRED>
  ]>

A description of the elements and their attributes follows.

Element manifest
----------------

The root element of the file.

Element remote
--------------

One or more remote elements may be specified.  Each remote element specifies a Git URL shared by one or more projects and (optionally) the Gerrit review server those projects upload changes through.

Attribute `name`: A short name unique to this manifest file.  The name specified here is used as the remote name in each project's .git/config, and is therefore automatically available to commands like `git fetch`, `git remote`, `git pull` and `git push`.

Attribute `alias`: The alias, if specified, is used to override `name` to be set as the remote name in each project's .git/config. Its value can be duplicated while attribute `name` has to be unique in the manifest file. This helps each project to be able to have same remote name which actually points to different remote url.

Attribute `fetch`: The Git URL prefix for all projects which use this remote.  Each project's name is appended to this prefix to form the actual URL used to clone the project.

Attribute `review`: Hostname of the Gerrit server where reviews are uploaded to by `repo upload`.  This attribute is optional; if not specified then `repo upload` will not function.

Element default
---------------------

At most one default element may be specified.  Its remote and revision attributes are used when a project element does not specify its own remote or revision attribute.

Attribute `remote`: Name of a previously defined remote element. Project elements lacking a remote attribute of their own will use this remote.

Attribute `revision`: Name of a Git branch (e.g. `master` or `refs/heads/master`).  Project elements lacking their own revision attribute will use this revision.

Element manifest-server
---------------------------------

At most one manifest-server may be specified. The url attribute is used to specify the URL of a manifest server, which is an XML RPC service.

The manifest server should implement the following RPC methods:

GetApprovedManifest(branch, target)

Return a manifest in which each project is pegged to a known good revision for the current branch and target.


The target to use is defined by environment variables TARGET_PRODUCT and TARGET_BUILD_VARIANT. These variables are used to create a string of the form $TARGET_PRODUCT-$TARGET_BUILD_VARIANT, e.g. passion-userdebug. If one of those variables or both are not present, the program will call GetApprovedManifest without the target parameter and the manifest server should choose a reasonable default target.

GetManifest(tag)

Return a manifest in which each project is pegged to the revision at the specified tag.

Element project
---------------------

One or more project elements may be specified.  Each element describes a single Git repository to be cloned into the repo client workspace.


Attribute `name`: A unique name for this project.  The project's name is appended onto its remote's fetch URL to generate the actual URL to configure the Git remote with.  The URL gets formed as:

 ${remote_fetch}/${project_name}.git

where ${remote_fetch} is the remote's fetch attribute and ${project_name} is the project's name attribute.  The suffix ".git" is always appended as repo assumes the upstream is a forest of bare Git repositories.

The project name must match the name Gerrit knows, if Gerrit is being used for code reviews.

Attribute `path`: An optional path relative to the top directory of the repo client where the Git working directory for this project should be placed.  If not supplied the project name is used.

Attribute `remote`: Name of a previously defined remote element. If not supplied the remote given by the default element is used.

Attribute `revision`: Name of the Git branch the manifest wants to track for this project.  Names can be relative to refs/heads (e.g. just "master") or absolute (e.g. "refs/heads/master"). Tags and/or explicit SHA-1s should work in theory, but have not been extensively tested.  If not supplied the revision given by the default element is used.

Attribute `groups`: List of groups to which this project belongs, whitespace or comma separated.  All projects belong to the group "all", and each project automatically belongs to a group of its name:`name` and path:`path`.  E.g. for <project name="monkeys" path="barrel-of"/>, that project definition is implicitly in the following manifest groups: default, name:monkeys, and path:barrel-of.  If you place a project in the group "notdefault", it will not be automatically downloaded by repo.

Element annotation
--------------------------

Zero or more annotation elements may be specified as children of a project element. Each element describes a name-value pair that will be exported into each project's environment during a 'forall' command, prefixed with REPO__.  In addition, there is an optional attribute "keep" which accepts the case insensitive values "true" (default) or
"false".  This attribute determines whether or not the annotation will be kept when exported with the manifest subcommand.

Element remove-project
--------------------------------

Deletes the named project from the internal manifest table, possibly allowing a subsequent project element in the same manifest file to replace the project with a different source.

This element is mostly useful in the local_manifest.xml, where the user can remove a project, and possibly replace it with their own definition.

Element include
---------------------

This element provides the capability of including another manifest file into the originating manifest.  Normal rules apply for the target manifest to include- it must be a usable manifest on it's own.

Attribute `name`; the manifest to include, specified relative to the manifest repositories root.

Local Manifest
===========

Additional remotes and projects may be added through a local manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`.

For example:

$ cat .repo/local_manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<project path="manifest" name="tools/manifest" />
<project path="platform-manifest" name="platform/manifest" />
   </manifest>

Users may add projects to the local manifest prior to a `repo sync` invocation, instructing repo to automatically download and manage these extra projects.       

------------------------------------------------------------------------------------------------------------------

--------------------------------------  原  文  如  下  -----------------------------------------------

------------------------------------------------------------------------------------------------------------------

repo Manifest 格式

==================

repo manifest描述了repo客户端的组织结构，它是一个可见的类似字典的文件，通过它我们可以清楚得知道我们将要从什么地方获取git仓库。

一个最简单的manifest仓库的结构就是仅有一个`default.xml`文件在顶级目录。

一旦Manifests被包含到一个git仓库，它就会受版本管控。 在执行`repo sync`命令时，客户端会自动更新manifests仓库。

XML 文件格式
------------

一个manifest xml文件（例如`default.xml`）大体上是遵从如下DTD规范的：

  <!DOCTYPE manifest [
    <!ELEMENT manifest (notice?,
                        remote*,
                        default?,
                        manifest-server?,
                        remove-project*,
                        project*,
                        repo-hooks?)>
  
    <!ELEMENT notice (#PCDATA)>
  
    <!ELEMENT remote (EMPTY)>
    <!ATTLIST remote name         ID    #REQUIRED>
    <!ATTLIST remote alias        CDATA #IMPLIED>
    <!ATTLIST remote fetch        CDATA #REQUIRED>
    <!ATTLIST remote review       CDATA #IMPLIED>
  
    <!ELEMENT default (EMPTY)>
    <!ATTLIST default remote   IDREF #IMPLIED>
    <!ATTLIST default revision CDATA #IMPLIED>
    <!ATTLIST default sync-j   CDATA #IMPLIED>
    <!ATTLIST default sync-c   CDATA #IMPLIED>

    <!ELEMENT manifest-server (EMPTY)>
    <!ATTLIST url              CDATA #REQUIRED>
  
    <!ELEMENT project (annotation?)>
    <!ATTLIST project name     CDATA #REQUIRED>
    <!ATTLIST project path     CDATA #IMPLIED>
    <!ATTLIST project remote   IDREF #IMPLIED>
    <!ATTLIST project revision CDATA #IMPLIED>
    <!ATTLIST project groups   CDATA #IMPLIED>
    <!ATTLIST project sync-c   CDATA #IMPLIED>

    <!ELEMENT annotation (EMPTY)>
    <!ATTLIST annotation name  CDATA #REQUIRED>
    <!ATTLIST annotation value CDATA #REQUIRED>
    <!ATTLIST annotation keep  CDATA "true">
  
    <!ELEMENT remove-project (EMPTY)>
    <!ATTLIST remove-project name  CDATA #REQUIRED>

    <!ELEMENT repo-hooks (EMPTY)>
    <!ATTLIST repo-hooks in-project CDATA #REQUIRED>
    <!ATTLIST repo-hooks enabled-list CDATA #REQUIRED>


    <!ELEMENT include      (EMPTY)>
    <!ATTLIST include name CDATA #REQUIRED>
  ]>

下面是对它的元素和属性的描述。

manifest 元素
-------------

文件的根元素。

remote 元素
-----------

可以指定一个或多个remote元素。每个remote元素指定一个Git URL路径和一个Gerrit代码审核服务器，这个Git　URL路径可以被多个项目共用，而每一次的代码提交都会首先经过这个Gerrit服务器。

属性`name`：对于manifest文件来说它是一个唯一的简短名称。这个名称在这里是用来指定每个项目的.git/config中的远程名称，当使用命令`git fetch`、`git remote`、`git pull`和`git push`的时候，会自动使用这个名称。

属性`alias`：如果指定了别名，那么别名可以覆盖默认的名称作为每个项目的.git/config中的远程名称。当属性`name`是唯一的时候，别名可以重复。

属性`fetch`：当使用远程分支时，该值作为远程分支的Git URL的前缀。该值加上每个项目的名称就是我们实际的克隆的URL。

属性`review`：当使用命令`repo upload`进行代码上传时，代码会先提交到Gerrit代码审核服务器，该值就是Gerrit服务器的主机名。这个属性是可选的，当它没有指定具体的值时，命令`repo upload`不会起作用。

default 元素
------------

只能有一个default元素。当某个项目元素没有指定`remote`名称或者`revision`名称时，这里指定的`remote`和`revision`属性会作为默认值使用。

属性`remote`：指定之前定义的`remote`元素。该值作为`project`元素`remote`属性的缺省值。

属性`revision`：相应project的Git分支的名称（例如`master`或者`refs/heads/master`）。该值作为`project`元素`revison`属性的缺省值。

manifest-server 元素
--------------------

只能指定一个manifest-server元素。它的`url`属性定义了通过XMLRPC提供实时更新清单的服务器URL。

manifest server应该事先下面的RPC方法：
GetApprovedManifest(branch, target) 返回一个manifest，用来指定所有projects的分支和编译目标。

target参数来自环境变量TARGET_PRODUCT和PRODUCT_BUILD_VARIANT。这些环境变量用来组成字符串$TARGET_PRODUCT-$TARGET_BUILD_VARIANT，形如passion-userdebug。如果这些变量中的部分没有定义，程序会调用GetApprovedManifest()方法(无target参数)，manifest服务会选择一个默认的合理编译目标。
GetManifest(tag) 返回指定tag的manifest。

project 元素
------------

可以指定多个project元素。每个project元素描述一个需要clone的Git仓库。

属性`name`：唯一的名字标示project，远程分支的fetch URL加上这个名字构成了Git仓库的URL。URL的格式如下：
${remote_fetch}/${project_name}.git

如果Gerrit作为代码审核服务器的话，project的名字就必须是Gerrit已知的。

属性`path`：可选的路径。指定clone出来的代码存放在本地的子目录。如果没有指定，则以name作为子目录名。

属性`remote`：指定之前定义的`remote`元素。如果没有指定该值，则将`default`元素的`remote`值作为当前值。

属性`revision`：manifest根据这个分支名来跟踪project。这个分支名可以是相对于refs/heads(例如，'master')或者是全名称（例如，'refs/heads/master'）。tag和SHA-1值理论上也是可以作为分支名的。如果没有指定该值，则将`default`元素的`revision`值作为当前值。

属性`group`：列出project所属的组，一空格或者逗号分隔多个组名。所有的project都自动属于'all'组。每个project自动属于name:'name'和path:'path'组。例如，<project name="monkeys" path="barrel-of"/>，它自动属于default，name:monkeys和path:barrel-of组。如果一个project属于'notdefault'组，则使用命令'repo sync'是不会下载。

annotation 元素
---------------

可以指定多个annotation元素，它采用name-value pair的格式。在'repo forall'命令中，这些值会被导入到环境变量中。它有一个可选属性`keep`去保存'true'或'false'（不区分大小写）。这个属性决定了当annotaion和manifest子命令一起输出时，annotation是否会被保留。

remove-project 元素
-------------------

从内部manifest表中删除指定的project。它通常用在这local_manifest.xml中，用户可以替换一个project的定义。

include 元素
------------

这个元素允许引入另一个manifest文件。通过name属性可以引入另外一个manifest文件，路径相对于manifest仓库的根路径。

本地 Manifest
=============

可以通过本地Manifest 来添加projects和remotes到远程。本地的manifest文件存放在`$TOP_DIR/.repo/local_manifest.xml`。

例如：
$ cat .repo/local_manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
<project path="manifest" name="tools/manifest" />
<project path="platform-manifest" name="platform/manifest" />
</manifest>

在执行'repo sync'命令之前，用户可以先添加项目到本地的manifest文件，然后让repo去自动下载和管理这些额外的projects。