{翻译} repo Manifest Format 【repo清单格式】

源文件: 0c957dd542b1476b34f3ad37736b06df38ea2fa8

repo清单格式

repo清单描述了repo客户端的结构;这是可见的目录，而且是git应该可以获取的目录。

清单的基本结构是一个裸Git存储库，可是在顶级目录中包含一个'default.xml'XML文件。

清单自己就是版本控制的，由于它们保存在Git存储库中。客户在repo sync期间自动获取清单更新。

XML文件格式

清单XML文件（例如'default.xml'）大体符合如下DTD：

<!DOCTYPE manifest [
    <!ELEMENT manifest (notice?,
                        remote*,
                        default?,
                        manifest-server?,
                        remove-project*,
                        project*,
                        extend-project*,
                        repo-hooks?,
                        include*)>
    <!ELEMENT notice (#PCDATA)>
    <!ELEMENT remote EMPTY>
    <!ATTLIST remote name         ID    #REQUIRED>
    <!ATTLIST remote alias        CDATA #IMPLIED>
    <!ATTLIST remote fetch        CDATA #REQUIRED>
    <!ATTLIST remote pushurl      CDATA #IMPLIED>
    <!ATTLIST remote review       CDATA #IMPLIED>
    <!ATTLIST remote revision     CDATA #IMPLIED>
    <!ELEMENT default EMPTY>
    <!ATTLIST default remote      IDREF #IMPLIED>
    <!ATTLIST default revision    CDATA #IMPLIED>
    <!ATTLIST default dest-branch CDATA #IMPLIED>
    <!ATTLIST default upstream    CDATA #IMPLIED>
    <!ATTLIST default sync-j      CDATA #IMPLIED>
    <!ATTLIST default sync-c      CDATA #IMPLIED>
    <!ATTLIST default sync-s      CDATA #IMPLIED>
    <!ATTLIST default sync-tags   CDATA #IMPLIED>
    <!ELEMENT manifest-server EMPTY>
    <!ATTLIST manifest-server url CDATA #REQUIRED>
    <!ELEMENT project (annotation*,
                       project*,
                       copyfile*,
                       linkfile*)>
    <!ATTLIST project name        CDATA #REQUIRED>
    <!ATTLIST project path        CDATA #IMPLIED>
    <!ATTLIST project remote      IDREF #IMPLIED>
    <!ATTLIST project revision    CDATA #IMPLIED>
    <!ATTLIST project dest-branch CDATA #IMPLIED>
    <!ATTLIST project groups      CDATA #IMPLIED>
    <!ATTLIST project sync-c      CDATA #IMPLIED>
    <!ATTLIST project sync-s      CDATA #IMPLIED>
    <!ATTLIST default sync-tags   CDATA #IMPLIED>
    <!ATTLIST project upstream CDATA #IMPLIED>
    <!ATTLIST project clone-depth CDATA #IMPLIED>
    <!ATTLIST project force-path CDATA #IMPLIED>
    <!ELEMENT annotation EMPTY>
    <!ATTLIST annotation name  CDATA #REQUIRED>
    <!ATTLIST annotation value CDATA #REQUIRED>
    <!ATTLIST annotation keep  CDATA "true">
    <!ELEMENT copyfile EMPTY>
    <!ATTLIST copyfile src  CDATA #REQUIRED>
    <!ATTLIST copyfile dest CDATA #REQUIRED>
    <!ELEMENT linkfile EMPTY>
    <!ATTLIST linkfile src CDATA #REQUIRED>
    <!ATTLIST linkfile dest CDATA #REQUIRED>
    <!ELEMENT extend-project EMPTY>
    <!ATTLIST extend-project name CDATA #REQUIRED>
    <!ATTLIST extend-project path CDATA #IMPLIED>
    <!ATTLIST extend-project groups CDATA #IMPLIED>
    <!ATTLIST extend-project revision CDATA #IMPLIED>
    <!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

能够指定一个或多个远程元素。每一个远程元素指定由一个或多个项目共享的Git URL，以及（可选）这些项目上载更改的Gerrit审阅服务器。

属性name：此清单文件惟一的短名称。这里指定的名称在每一个项目的.git / config中用做远程名称，所以能够自动用于git fetch，git remote，git pull和git push等命令。 属性alias：别名，若是指定，用于覆盖name，将其设置为每一个项目中的远程名称.git / config. 它的值能够重复，而属性name在清单中必须是惟一的文件。这有助于每一个项目可以具备实际指向不一样远程URL的相同远程名称。

属性fetch：使用此远程的全部项目的Git URL前缀。每一个项目的名称都附加到此前缀，以造成用于克隆项目的实际URL。

属性pushurl：使用此远程的全部项目的Git“推送”URL前缀。每一个项目的名称都附加到此前缀，以造成用于“git push”项目的实际URL。该属性是可选的;若是没有指定，那么“git push”将使用与fetch属性相同的URL。

属性review：Gerrit服务器的主机名，其中评论由repo upload上传到。该属性是可选的;若是没有指定，那么repo upload将不起做用。

属性revision：Git分支的名称（例如master或refs / heads / master）。具备本身revision值的remote将覆盖default的revision值。

元素default

最多能够指定一个default元素。当项目元素未指定其本身的remote或revision属性时，将使用他的remote和version属性。

属性remote：预先定义的remote元素的名称。缺乏本身的远程属性的项目元素将使用此remote值。

属性revision：Git分支的名称（例如master或refs / heads / master）。缺乏本身的revision属性的项目元素将使用此值。

属性'dest-branch：Git分支的名称（例如master）。不设置本身的dest-branch的项目元素将继承此值。若是未设置此值，项目将默认使用revision`。

属性upstream：能够找到sha1的Git ref的名称。在-c模式下同步修订锁定清单时使用，以免必须同步整个ref空间。不设置本身的upstream的项目元素将继承此值。

属性sync-j：同步时要使用的并行做业数。

属性sync-c：设置为true以仅同步给定的Git分支（在revision属性中指定）而不是整个ref空间。缺乏本身的sync-c元素的项目元素将使用此值。

属性sync-s：设置为true以同步子项目。

属性sync-tags：设置为false以仅同步给定的Git分支（在revision属性中指定）而不是其余ref标记。

元素 manifest-server

最多能够指定一个清单服务器。 url属性用于指定清单服务器的URL，该服务器是XML RPC服务。

清单服务器应该实现如下RPC方法：

GetApprovedManifest（branch，target）

返回一个清单，其中每一个项目都与当前分支和目标的已知良好修订挂钩。当给出--smart-sync选项时，repo sync会使用此选项。

要使用的目标由环境变量TARGET_PRODUCT和TARGET_BUILD_VARIANT定义。这些变量用于建立$ TARGET_PRODUCT- $ TARGET_BUILD_VARIANT形式的字符串，例如，passion-userdebug。若是其中一个变量或二者都不存在，程序将调用不带目标参数的GetApprovedManifest，清单服务器应选择合理的默认目标。

GetManifest（tag）

返回一个清单，其中每一个项目都与指定标记处的修订版挂钩。当给出--smart-tag选项时，repo sync会使用此选项。

元素 project

能够指定一个或多个项目元素。每一个元素都描述了一个克隆到repo客户端工做区的Git存储库。您能够经过建立嵌套项目来指定Git子模块。 Git子模块将被自动识别并继承其父级属性，但这些属性可能会被显式指定的项目元素覆盖。

属性name：此项目的惟一名称。项目的名称将附加到其远程的提取URL上，以生成用于配置Git远程的实际URL。 URL造成为：

${remote_fetch}/${PROJECT_NAME}.git

其中$ {remote_fetch}是远程的fetch属性，$ {project_name}是项目的name属性。始终附加后缀“.git”，由于repo假设上游是一个裸Git存储库。若是项目具备父元素，则其名称将以父元素为前缀。若是Gerrit用于代码审查，项目名称必须与Gerrit知道的名称相匹配。

属性path：相对于repo客户端的顶级目录的可选路径，其中应放置此项目的Git工做目录。若是未提供，则使用项目名称。若是项目具备父元素，则其路径将以父元素为前缀。

属性remote：先前定义的远程元素的名称。若是未提供，则使用默认元素给定的remote值。

属性revision：清单要为此项目跟踪的Git分支的名称。名称能够是refs / heads（例如只是“master”）或绝对名称（例如“refs / heads / master”）。标签和/或显式SHA-1应该在理论上有效，但还没有通过普遍测试。若是未提供，则使用远程元素给出的version（若是适用），不然使用default中的值。

属性dest-branch：Git分支的名称（例如master）。使用repo upload时，将提交更改以在此分支上进行代码审查。若是未在此处和default中指定，则使用revision。

属性groups：此项目所属的组列表，空格或逗号分隔。全部项目都属于“all”组，每一个项目自动属于一个名称组：name和path：path。例如。对于<project name =“monkeys”path =“barrel-of”/>，该项目定义隐含在如下清单组中：default，name：monkeys和path：barrel-of。若是您将项目放入“notdefault”组中，则不会经过repo自动下载该项目。若是项目有父元素，那么name和path就是前缀。

属性sync-c：设置为true以仅同步给定的Git分支（在revision属性中指定）而不是整个ref空间。

属性sync-s：设置为true以同步子项目。

属性upstream：能够找到sha1的Git ref的名称。在-c模式下同步修订锁定清单时使用，以免必须同步整个ref空间。

属性clone-depth：设置获取此项目时使用的深度。若是指定，则此值将覆盖使用命令行上的--depth选项为repo init指定的任何值。

属性force-path：设置为true以强制此项目根据其path属性（若是提供）而不是name属性建立本地镜像存储库。此属性仅适用于本地镜像同步，在同步客户端工做目录中的项目时将忽略该属性。

元素 extend-project

修改指定项目的属性。

此元素在本地清单文件中很是有用，能够在不彻底替换现有项目定义的状况下修改现有项目的属性。这使得本地清单对原始清单的更改更加健壮。

属性path：若是指定，则将更改限制为在指定路径检出的项目，而不是具备给定名称的全部项目。

属性groups：此项目所属的其余组的列表。与project的相应元素语法相同。

属性revision：若是指定，则覆盖原始项目的修订版。与project的相应元素语法相同。

元素 annotation

能够将零个或多个注释元素指定为项目元素的子元素。每一个元素都描述了一个名称 - 值对，它将在'forall'命令期间导出到每一个项目的环境中，前缀为REPO__。此外，还有一个可选属性“keep”，它接受不区分大小写的值“true”（默认值）或“false”。此属性肯定在使用manifest子命令导出时是否保留注释。

元素copyfile

能够将零个或多个copyfile元素指定为项目元素的子元素。每一个元素描述一对src-dest文件;在'repo sync'命令期间，“src”文件将被复制到“dest”位置。

“src”是项目相对的，“dest”是相对于树的顶部。

元素 linkfile

它就像copyfile同样，与copyfile同时运行，但不是复制它而是建立一个符号连接。

元素 remove-project

从内部清单表中删除命名项目，可能容许同一清单文件中的后续项目元素用不一样的源替换项目。

此元素在本地清单文件中很是有用，用户能够在其中删除项目，并可能使用本身的定义替换它。

元素include

此元素提供将另外一个清单文件包含到原始清单中的功能。正常规则适用于要包含的目标清单 - 它必须是一个可用的清单。

属性name：要包含的清单，相对于清单存储库的根目录指定。

本地清单

能够经过存储在$ TOP_DIR/.repo/local_manifests/*.xml中的本地清单文件添加其余远程和项目。 例如：

$ ls .repo/local_manifests
  local_manifest.xml
  another_local_manifest.xml
  $ cat .repo/local_manifests/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”调用以前将项目添加到本地清单，指示repo自动下载和管理这些额外项目。

存储在$ TOP_DIR/.repo/local_manifests/*.xml中的清单文件将按字母顺序加载。

其余remote和project也能够经过本地清单添加，存储在$TOP_DIR/.repo/local_manifest.xml中。不推荐使用此方法，而是使用上面提到的多个清单文件。

若是存在$TOP_DIR/.repo/local_manifest.xml，它将在任何存储在$TOP_DIR/.repo/local_manifests /*.xml中的清单文件以前加载。