This page contains detailed information about west’s multiple repository model
and manifest files. For API documentation on the
west.manifest module, see
west.manifest. For a more general introduction and command
overview, see Multiple Repository Management.
Multiple Repository Model¶
West’s view of the repositories in a west installation, and their history, looks like the following figure (though some parts of this example are specific to upstream Zephyr’s use of west):
The history of the manifest repository is the line of Git commits which is “floating” on top of the gray plane. Parent commits point to child commits using solid arrows. The plane below contains the Git commit history of the repositories in the installation, with each project repository boxed in by a rectangle. Parent/child commit relationships in each repository are also shown with solid arrows.
The commits in the manifest repository (again, for upstream Zephyr this is the zephyr repository itself) each have a manifest file. The manifest file in each commit specifies the corresponding commits which it expects in each of the project repositories. This relationship is shown using dotted line arrows in the diagram. Each dotted line arrow points from a commit in the manifest repository to a corresponding commit in a project repository.
Notice the following important details:
Projects can be added (like
P1between manifest repository commits
E) and removed (
P2between the same manifest repository commits)
Project and manifest repository histories don’t have to move forwards or backwards together:
P2stays the same from
A → B, as do
F → G.
P3moves forward from
A → B.
P3moves backward from
C → D.
One use for moving backward in project history is to “revert” a regression by going back to a revision before it was introduced.
Project repository commits can be “skipped”:
P3moves forward multiple commits in its history from
B → C.
In the above diagram, no project repository has two revisions “at the same time”: every manifest file refers to exactly one commit in the projects it cares about. This can be relaxed by using a branch name as a manifest revision, at the cost of being able to bisect manifest repository history.
A west manifest is a YAML file named
west.yml. Manifests have two
manifest, like this:
west: # contents of west section manifest: # contents of manifest section
In YAML terms, the manifest file contains a mapping, with two keys relevant to
west at top level. These keys are the scalar strings
manifest. Their contents are described next.
Support for this feature will be removed in a future version of west, when the west repository is no longer cloned into the installation.
west section specifies the URL and revision of the west repository
which is cloned into the installation. For example:
west: url: https://example.com/west revision: v0.5.6
This specifies cloning the west repository from URL
https://example.com/west (any URL accepted by
git clone will work), at
v0.5.6. The revision can be a Git branch, tag, or SHA.
That is, the west section also contains a mapping, with permitted keys
revision. These specify the fetch URL and Git revision for the west
repository to clone into the installation, as described in
West Structure. If not given, the default URL is
https://github.com/zephyrproject-rtos/west, and the default revision is
west-schema.yml in the west source code repository contains a
pykwalify schema for this section’s contents.
This is the main section in the manifest file. There are four subsections:
self. In YAML terms, the value
manifest key is also a mapping, with these “subsections” as keys.
manifest: defaults: # contents of defaults subsection remotes: # contents of remotes subsection projects: # contents of projects subsection self: # contents of self subsection
projects subsections are the only mandatory ones, so
we’ll cover them first.
remotes subsection contains a sequence which specifies the base URLs
where projects can be fetched from. Each sequence element has a name and a “URL
base”. These are used to form the complete fetch URL for each project. For
manifest: # [...] remotes: - name: remote1 url-base: https://example.com/base1 - name: remote2 url-base: https://example.com/base2
Above, two remotes are given, with names
remote2. Their URL
bases are respectively
https://example.com/base2. You can use SSH URL bases as well; for example,
you might use
remote1 supported Git over SSH
as well. Anything acceptable to Git will work.
projects subsection contains a sequence describing the
project repositories in the west installation. Each project has a
name and a remote; the project’s name is appended to the remote URL
base to form the Git fetch URL west uses to clone the project and keep
it up to date. Here is a simple example; we’ll assume the
manifest: # [...] projects: - name: proj1 remote: remote1 path: extra/project-1 - name: proj2 remote: remote1 revision: v1.3 - name: proj3 remote: remote2 revision: abcde413a111
This example has three projects:
remote1, so its Git fetch URL is
https://example.com/base1/proj1(note that west adds the
/between the URL base and project name). This project will be cloned at path
extra/project-1relative to the west installation’s root directory. Since the project has no
revision, the current tip of the
masterbranch will be checked out as a detached
proj2has the same remote, so its fetch URL is
https://example.com/base1/proj2. Since the project has no
pathspecified, it will be cloned at
proj2(i.e. a project’s
nameis used as its default
path). The commit pointed to by the
v1.3tag will be checked out.
proj3has fetch URL
https://example.com/base2/proj3and will be cloned at path
abcde413a111will be checked out.
Each element in the
projects sequence can contain the following keys. Some
of the description refers to the
defaults subsection, which will be
name: Mandatory, the name of the project. The fetch URL is formed as remote url-base + ‘/’ +
name. The name cannot be one of the reserved values “west” and “manifest”.
remote: The name of the project’s remote. If not given, the
remotevalue in the
defaultssubsection is tried next. If both are missing, the manifest is invalid.
repo-path: Optional. If given, this is concatenated on to the remote’s
url-baseinstead of the project’s
nameto form its fetch URL.
url: Optional. If given, this is the project’s complete fetch URL. It cannot be combined with either
repo-path. Note that this overrides any default remote.
revision: Optional. The current project revision used by
west update. If not given, the value from the
defaultssubsection will be used if present. If both are missing,
masteris used. A project revision can be a branch, tag, or SHA. The names of unqualified branch and tag revisions are fetched as-is. For qualified refs, like
refs/heads/foo, the last component (
foo) is used.
path: Optional. Where to clone the repository locally. If missing, it’s cloned in the west installation’s root subdirectory given by the project’s name.
clone-depth: Optional. If given, a positive integer which creates a shallow history in the cloned repository limited to the given number of commits.
west-commands: Optional. If given, a relative path to a YAML file within the project which describes additional west commands provided by that project. This file is named
west-commands.ymlby convention. See Extensions for details.
defaults subsection can provide default values for project-related
values. In particular, the default remote name and revision can be specified
here. Another way to write the same manifest we have been describing so far
manifest: defaults: remote: remote1 revision: v1.3 remotes: - name: remote1 url-base: https://example.com/base1 - name: remote2 url-base: https://example.com/base2 projects: - name: proj1 path: extra/project-1 revision: master - name: proj2 - name: proj3 remote: remote2 revision: abcde413a111
self subsection can be used to control the behavior of the
manifest repository itself. Its value is a map with the following keys:
path: Optional. The path to clone the manifest repository into, relative to the west installation’s root directory. If not given, the basename of the path component in the manifest repository URL will be used by default. For example, if the URL is
https://example.com/project-repo, the manifest repository would be cloned to the directory
west-commands: Optional. This is analogous to the same key in a project sequence element.
As an example, let’s consider this snippet from the zephyr repository’s
manifest: # [...] self: path: zephyr west-commands: scripts/west-commands.yml
This ensures that the zephyr repository is cloned into path
as explained above that would have happened anyway if cloning from the default
https://github.com/zephyrproject-rtos/zephyr. Since the
zephyr repository does contain extension commands, its
self entry declares
the location of the corresponding
west-commands.yml relative to the
The pykwalify schema
manifest-schema.yml in the west source code
repository is used to validate the manifest section.