Repo Tool & Manifests

repo tool is a wrapper around the git version control system to manage multiple git repositories, it simplifies several git operations, in particular the sync (download) of software sources to a local environment.

To achieve this, repo uses a manifest file, which is a collection of repositories with some attributes to specify for example the revision of a particular repository or the local path that repository will have once downloaded to our local environment.

Manifest File in Detail

A manifest file is written in Extensible Markup Language (XML), for a full list of supported elements and attributes please see repo manifest format.

Take the excerpt of an existing manifest file in Neoverse reference design gitlab repository to understand how manifests are defined.

1<manifest>
2  <remote fetch="https://git.gitlab.arm.com/infra-solutions/reference-design/" name="arm"/>
3  <remote fetch="https://github.com/" name="github"/>
4
5  <project remote="arm" name="platsw/scp-firmware" path="scp" revision="refs/tags/RD-INFRA-2023.12.22"/>
6</manifest>
Line #2, the element remote defines two attributes, fetch and name.
- fetch is the base url of a git repository.
- name is an alias for that repository.
Line #5, the element project also defines the attributes name, path and revision.
- name is the name of the project in the git repository.
- path is the local path where the project will be cloned to, relative to where the manifest is initialised.
- revision is the git revision to clone, this can be a branch, a tag or a commit sha id.

A remote can have multiple repositories, the link from a remote to a project is given by the alias set in line #2 and used in line #5 as remote="arm".

The revision attribute when set to tag or a commit sha id is what makes the software stack being reproducible because it will fetch the same software sources consistently. More details provided in the section Pinned vs Non-Pinned.

Translating the syntax of a manifest file to git, the underlying command of line #5 to run would be:

git clone --branch refs/tags/RD-INFRA-2023.12.22 https://git.gitlab.arm.com/infra-solutions/reference-design/platsw/scp-firmware ./scp

Manifest (Pinned vs Non-Pinned)

Now that the user knows how a manifest file is defined, let’s stablish the concept of Pinned and Non-Pinned manifests.

When we release a software stack, we test the integration of all the components and validate that they work together to achieve the goal of providing users with a usable code base, thus we tag the manifest and the components to have a reference of this code base validity. This is the Pinned manifest and the file name convention is pinned-<platform>.xml.

But as software evolves, new features and/or security fixes will be made availble in the participating components of the software stack, therefore we provide a manifest where the revision of the components is set to a branch that is updated more frequently with their upstream counterparts. This is the Non-Pinned manifest, and the file name simply is the platform name, i.e.: <platform>.xml.