repo

Documentation

Overview

repo is a limited implementation of the python repo git front end.

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`.

A manifest XML file (e.g. 'default.xml') roughly conforms to the following DTD. The python code is the only authoritative source.

Local Manifests

Additional remotes and projects may be added through local manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.

For example:

$ 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>

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

Manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml` will be loaded in alphabetical order.

Additional remotes and projects may also be added through a local manifest, stored in `$TOP_DIR/.repo/local_manifest.xml`. This method is deprecated in favor of using multiple manifest files as mentioned above.

If `$TOP_DIR/.repo/local_manifest.xml` exists, it will be loaded before any manifest files stored in `$TOP_DIR/.repo/local_manifests/*.xml`.

Index

• Variables
• func VerifySync(name string) error
• type Annotation
• type CopyFile
• type Default
• type ExtendProject
• type Include
• type LinkFile
• type Manifest
• type ManifestServer
• type Project
• type Remote
• type RemoveProject
• type RepoHooks

Variables

var (
	Unimplemented = errors.New("repo: unimplemented feature in manifest")
	MissingField  = errors.New("repo: missing required field in manifest")
	VerifyError   = errors.New("repo: failed verification")
)

Functions

func VerifySync

func VerifySync(name string) error

VerifySync takes a manifest name and asserts the current repo checkout matches it exactly. Currently only supports manifests flattened by the "repo manifest -r" command. A blank name means to use the default. TODO: check symbolic refs too? e.g. HEAD == refs/remotes/origin/master

Types

type Annotation

type Annotation struct {
	Name  string `xml:"name,attr"`
	Value string `xml:"value,attr"`
	Keep  string `xml:"keep,attr,omitempty"`
}

Annotation

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

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.

type CopyFile

type CopyFile struct {
	Src  string `xml:"src,attr"`
	Dest string `xml:"dest,attr"`
}

CopyFile

<!ELEMENT copyfile (EMPTY)>
<!ATTLIST src value  CDATA #REQUIRED>
<!ATTLIST dest value CDATA #REQUIRED>

Zero or more copyfile elements may be specified as children of a project element. Each element describes a src-dest pair of files; the "src" file will be copied to the "dest" place during 'repo sync' command. "src" is project relative, "dest" is relative to the top of the tree.

type Default

type Default struct {
	Remote          string `xml:"remote,attr,omitempty"`
	Revision        string `xml:"revision,attr,omitempty"`
	DestBranch      string `xml:"dest-branch,attr,omitempty"`
	SyncJobs        string `xml:"sync-j,attr,omitempty"`
	SyncBranch      string `xml:"sync-c,attr,omitempty"`
	SyncSubProjects string `xml:"sync-s,attr,omitempty"`
}

Default

<!ELEMENT default (EMPTY)>
<!ATTLIST default remote      IDREF #IMPLIED>
<!ATTLIST default revision    CDATA #IMPLIED>
<!ATTLIST default dest-branch CDATA #IMPLIED>
<!ATTLIST default sync-j      CDATA #IMPLIED>
<!ATTLIST default sync-c      CDATA #IMPLIED>
<!ATTLIST default sync-s      CDATA #IMPLIED>

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.

Attribute `dest-branch`: Name of a Git branch (e.g. `master`). Project elements not setting their own `dest-branch` will inherit this value. If this value is not set, projects will use `revision` by default instead.

Attribute `sync-j`: Number of parallel jobs to use when synching.

Attribute `sync-c`: Set to true to only sync the given Git branch (specified in the `revision` attribute) rather than the whole ref space. Project elements lacking a sync-c element of their own will use this value.

Attribute `sync-s`: Set to true to also sync sub-projects.

type ExtendProject

type ExtendProject struct {
	Name   string `xml:"name,attr"`
	Path   string `xml:"path,attr,omitempty"`
	Groups string `xml:"groups,attr,omitempty"`
}

ExtendProject

<!ELEMENT extend-project>
<!ATTLIST extend-project name   CDATA #REQUIRED>
<!ATTLIST extend-project path   CDATA #IMPLIED>
<!ATTLIST extend-project groups CDATA #IMPLIED>

Modify the attributes of the named project.

This element is mostly useful in a local manifest file, to modify the attributes of an existing project without completely replacing the existing project definition. This makes the local manifest more robust against changes to the original manifest.

Attribute `path`: If specified, limit the change to projects checked out at the specified path, rather than all projects with the given name.

Attribute `groups`: List of additional groups to which this project belongs. Same syntax as the corresponding element of `project`.

type Include

type Include struct {
	Name string `xml:"name,attr"`
}

Include

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

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 its own.

Attribute `name`: the manifest to include, specified relative to the manifest repository's root.

type LinkFile

type LinkFile struct {
	Src  string `xml:"src,attr"`
	Dest string `xml:"dest,attr"`
}

LinkFile

<!ELEMENT linkfile (EMPTY)>
<!ATTLIST src value  CDATA #REQUIRED>
<!ATTLIST dest value CDATA #REQUIRED>

It's just like copyfile and runs at the same time as copyfile but instead of copying it creates a symlink.

type Manifest

type Manifest struct {
	XMLName        xml.Name        `xml:"manifest"`
	Includes       []Include       `xml:"include"`
	Notice         string          `xml:"notice"`
	Remotes        []Remote        `xml:"remote"`
	Default        *Default        `xml:"default"`
	ManifestServer *ManifestServer `xml:"manifest-server"`
	Projects       []Project       `xml:"project"`
	ExtendProjects []ExtendProject `xml:"extend-project"`
	RemoveProjects []RemoveProject `xml:"remove-project"`
	RepoHooks      *RepoHooks      `xml:"repo-hooks"`
}

Manifest is the root element of the file.

<!ELEMENT manifest (include*,
                    notice?,
                    remote*,
                    default?,
                    manifest-server?,
                    project*,
                    extend-project*,
                    remove-project*,
                    repo-hooks?)>

<!ELEMENT notice (#PCDATA)>

type ManifestServer

type ManifestServer struct {
	URL string `xml:"url,attr"`
}

ManifestServer

<!ELEMENT manifest-server (EMPTY)>
<!ATTLIST url              CDATA #REQUIRED>

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.

type Project

type Project struct {
	Annotations     []Annotation `xml:"annotation"`
	SubProjects     []Project    `xml:"project"`
	CopyFiles       []CopyFile   `xml:"copyfile"`
	LinkFiles       []LinkFile   `xml:"linkfile"`
	Name            string       `xml:"name,attr"`
	Path            string       `xml:"path,attr,omitempty"`
	Remote          string       `xml:"remote,attr,omitempty"`
	Revision        string       `xml:"revision,attr,omitempty"`
	DestBranch      string       `xml:"dest-branch,attr,omitempty"`
	Groups          string       `xml:"groups,attr,omitempty"`
	SyncBranch      string       `xml:"sync-c,attr,omitempty"`
	SyncSubProjects string       `xml:"sync-s,attr,omitempty"`
	Upstream        string       `xml:"upstream,attr,omitempty"`
	CloneDepth      string       `xml:"clone-depth,attr,omitempty"`
	ForcePath       string       `xml:"force-path,attr,omitempty"`
}

Project

<!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 project upstream    CDATA #IMPLIED>
<!ATTLIST project clone-depth CDATA #IMPLIED>
<!ATTLIST project force-path  CDATA #IMPLIED>

One or more project elements may be specified. Each element describes a single Git repository to be cloned into the repo client workspace. You may specify Git-submodules by creating a nested project. Git-submodules will be automatically recognized and inherit their parent's attributes, but those may be overridden by an explicitly specified project element.

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. If the project has a parent element, its name will be prefixed by the parent's.

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. If the project has a parent element, its path will be prefixed by the parent's.

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 remote element is used if applicable, else the default element is used.

Attribute `dest-branch`: Name of a Git branch (e.g. `master`). When using `repo upload`, changes will be submitted for code review on this branch. If unspecified both here and in the default element, `revision` is used instead.

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. If the project has a parent element, the `name` and `path` here are the prefixed ones.

Attribute `sync-c`: Set to true to only sync the given Git branch (specified in the `revision` attribute) rather than the whole ref space.

Attribute `sync-s`: Set to true to also sync sub-projects.

Attribute `upstream`: Name of the Git ref in which a sha1 can be found. Used when syncing a revision locked manifest in -c mode to avoid having to sync the entire ref space.

Attribute `clone-depth`: Set the depth to use when fetching this project. If specified, this value will override any value given to repo init with the --depth option on the command line.

Attribute `force-path`: Set to true to force this project to create the local mirror repository according to its `path` attribute (if supplied) rather than the `name` attribute. This attribute only applies to the local mirrors syncing, it will be ignored when syncing the projects in a client working directory.

type Remote

type Remote struct {
	Name     string `xml:"name,attr"`
	Alias    string `xml:"alias,attr,omitempty"`
	Fetch    string `xml:"fetch,attr"`
	Review   string `xml:"review,attr,omitempty"`
	Revision string `xml:"revision,attr,omitempty"`
}

Remote

<!ELEMENT remote (EMPTY)>
<!ATTLIST remote name         ID    #REQUIRED>
<!ATTLIST remote alias        CDATA #IMPLIED>
<!ATTLIST remote fetch        CDATA #REQUIRED>
<!ATTLIST remote review       CDATA #IMPLIED>
<!ATTLIST remote revision     CDATA #IMPLIED>

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.

Attribute `revision`: Name of a Git branch (e.g. `master` or `refs/heads/master`). Remotes with their own revision will override the default revision.

type RemoveProject

type RemoveProject struct {
	Name string `xml:"name,attr"`
}

RemoveProject

<!ELEMENT remove-project (EMPTY)>
<!ATTLIST remove-project name CDATA #REQUIRED>

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 a local manifest file, where the user can remove a project, and possibly replace it with their own definition.

type RepoHooks

type RepoHooks struct {
	InProject   string `xml:"in-project,attr"`
	EnabledList string `xml:"enabled-list,attr"`
}

RepoHooks

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