mirror of
https://gerrit.googlesource.com/git-repo
synced 2024-12-21 07:16:21 +00:00
7da1314e38
For CrOS, we have scenarios were people checkout a smaller version of our manifest via groups, and enable individual repositories as needed for their work. Previously this was via local_manifest manipulation, which breaks via manifest-groups would require a remove-project tag. Via injecting the projects name into the projects groups, this allows us to instead manipulate the configured groups allowing the user to turn on/off projects as necessary. Change-Id: I07b7918e16cc9dc28eb47e19a46a04dc4fd0be74
233 lines
7.9 KiB
Plaintext
233 lines
7.9 KiB
Plaintext
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 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 `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 that will return a manifest in which each project
|
|
is pegged to a known good revision for the current branch and
|
|
target.
|
|
|
|
The manifest server should implement:
|
|
|
|
GetApprovedManifest(branch, 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 paramater and the manifest server
|
|
should choose a reasonable default target.
|
|
|
|
|
|
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 forrest 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
|
|
"default", and each project automatically belongs to a group of
|
|
it's 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.
|
|
|
|
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.
|