mirror of
https://gerrit.googlesource.com/git-repo
synced 2024-12-23 07:16:21 +00:00
b292b98c3e
The `alias` is an optional attribute in element `remote`. It can be
used to override attibute `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 across the manifest file. This helps each
project to be able to have same remote name which actually points
to different remote url.
It eases some automation scripts to be able to checkout/push to same
remote name but actually different remote url, like:
repo forall -c "git checkout -b work same_remote/work"
repo forall -c "git push same_remote work:work"
for example:
The manifest with 'alias' will look like:
<?xml version='1.0' encoding='UTF-8'?>
<manifest>
<remote alias="same_alias" fetch="git://git.external1.org/" name="ext1"
review="http://review.external1.org"/>
<remote alias="same_alias" fetch="git://git.external2.org/" name="ext2"
review="http://review.external2.org"/>
<remote alias="same_alias" fetch="ssh://git.internal.com:29418" name="int"
review="http://review.internal.com"/>
<default remote="int" revision="int-branch" sync-j="2"/>
<project name="path/to/project1" path="project1" remote="ext1"/>
<project name="path/to/project2" path="project2" remote="ext2"/>
<project name="path/to/project3" path="project3"/>
...
</manifest>
In each project, use command "git remote -v"
project1:
same_alias git://git.external1.org/project1 (fetch)
same_alias git://git.external1.org/project1 (push)
project2:
same_alias git://git.external2.org/project2 (fetch)
same_alias git://git.external2.org/project2 (push)
project3:
same_alias ssh://git.internal.com:29418/project3 (fetch)
same_alias ssh://git.internal.com:29418/project3 (push)
Change-Id: I2c48263097ff107f0c978f3e83966ae71d06cb90
240 lines
8.3 KiB
Plaintext
240 lines
8.3 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 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 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.
|