Workspaces

This page describes the west workspace concept introduced in Basics in more detail.

The `manifest-rev` branch

West creates and controls a Git branch named manifest-rev in each project. This branch points to the revision that the manifest file specified for the project at the time west update was last run. Other workspace management commands may use manifest-rev as a reference point for the upstream revision as of this latest update. Among other purposes, the manifest-rev branch allows the manifest file to use SHAs as project revisions.

Although manifest-rev is a normal Git branch, west will recreate and/or reset it on the next update. For this reason, it is dangerous to check it out or otherwise modify it yourself. For instance, any commits you manually add to this branch may be lost the next time you run west update. Instead, check out a local branch with another name, and either rebase it on top of a new manifest-rev, or merge manifest-rev into it.

Note

West does not create a manifest-rev branch in the manifest repository, since west does not manage the manifest repository’s branches or revisions.

The `refs/west/*` Git refs

West also reserves all Git refs that begin with refs/west/ (such as refs/west/foo) for itself in local project repositories. Unlike manifest-rev, these refs are not regular branches. West’s behavior here is an implementation detail; users should not rely on these refs’ existence or behavior.

Private repositories

You can use west to fetch from private repositories. There is nothing west-specific about this.

The west update command essentially runs git fetch YOUR_PROJECT_URL when a project’s manifest-rev branch must be updated to a newly fetched commit. It’s up to your environment to make sure the fetch succeeds.

You can either enter the password manually or use any of the credential helpers built in to Git. Since Git has credential storage built in, there is no need for a west-specific feature.

The following sections cover common cases for running west update without having to enter your password, as well as how to troubleshoot issues.

Fetching via HTTPS

On Windows when fetching from GitHub, recent versions of Git prompt you for your GitHub password in a graphical window once, then store it for future use (in a default installation). Passwordless fetching from GitHub should therefore work “out of the box” on Windows after you have done it once.

In general, you can store your credentials on disk using the “store” git credential helper. See the git-credential-store manual page for details.

To use this helper for all the repositories in your workspace, run:

west forall -c "git config credential.helper store"

To use this helper on just the projects foo and bar, run:

west forall -c "git config credential.helper store" foo bar

To use this helper by default on your computer, run:

git config --global credential.helper store

On GitHub, you can set up a personal access token to use in place of your account password. (This may be required if your account has two-factor authentication enabled, and may be preferable to storing your account password in plain text even if two-factor authentication is disabled.)

You can use the Git credential store to authenticate with a GitHub PAT (Personal Access Token) like so:

echo "https://x-access-token:$GH_TOKEN@github.com" >> ~/.git-credentials

If you don’t want to store any credentials on the file system, you can store them in memory temporarily using git-credential-cache instead.

If you setup fetching via SSH, you can use Git URL rewrite feature. The following command instructs Git to use SSH URLs for GitHub instead of HTTPS ones:

git config --global url."git@github.com:".insteadOf "https://github.com/"

Fetching via SSH

If your SSH key has no password, fetching should just work. If it does have a password, you can avoid entering it manually every time using ssh-agent.

On GitHub, see Connecting to GitHub with SSH for details on configuration and key creation.

Project locations

Projects can be located anywhere inside the workspace, but they may not “escape” it.

In other words, project repositories need not be located in subdirectories of the manifest repository or as immediate subdirectories of the topdir. However, projects must have paths inside the workspace.

You may replace a project’s repository directory within the workspace with a symbolic link to elsewhere on your computer, but west will not do this for you.

Topologies supported

The following are example source code topologies supported by west.

T1: star topology, zephyr is the manifest repository
T2: star topology, a Zephyr application is the manifest repository
T3: forest topology, freestanding manifest repository

T1: Star topology, zephyr is the manifest repository

The zephyr repository acts as the central repository and specifies its Modules (External projects) in its west.yml
Analogy with existing mechanisms: Git submodules with zephyr as the super-project

This is the default. See Workspace concepts for how mainline Zephyr is an example of this topology.

T2: Star topology, application is the manifest repository

Useful for those focused on a single application
A repository containing a Zephyr application acts as the central repository and names other projects required to build it in its west.yml. This includes the zephyr repository and any modules.
Analogy with existing mechanisms: Git submodules with the application as the super-project, zephyr and other projects as submodules

A workspace using this topology looks like this:

west-workspace/
│
├── application/         # .git/     │
│   ├── CMakeLists.txt               │
│   ├── prj.conf                     │  never modified by west
│   ├── src/                         │
│   │   └── main.c                   │
│   └── west.yml         # main manifest with optional import(s) and override(s)
│                                    │
├── modules/
│   └── lib/
│       └── zcbor/       # .git/ project from either the main manifest or some import.
│
└── zephyr/              # .git/ project
    └── west.yml         # This can be partially imported with lower precedence or ignored.
                         # Only the 'manifest-rev' version can be imported.

Here is an example application/west.yml which uses Manifest Imports, available since west 0.7, to import Zephyr v2.5.0 and its modules into the application manifest file:

# Example T2 west.yml, using manifest imports.
manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
  projects:
    - name: zephyr
      remote: zephyrproject-rtos
      revision: v2.5.0
      import: true
  self:
    path: application

You can still selectively “override” individual Zephyr modules if you use import: in this way; see Example 1.3: Downstream of a Zephyr release, with module fork for an example.

Another way to do the same thing is to copy/paste zephyr/west.yml to application/west.yml, adding an entry for the zephyr project itself, like this:

# Equivalent to the above, but with manually maintained Zephyr modules.
manifest:
  remotes:
    - name: zephyrproject-rtos
      url-base: https://github.com/zephyrproject-rtos
  defaults:
    remote: zephyrproject-rtos
  projects:
    - name: zephyr
      revision: v2.5.0
      west-commands: scripts/west-commands.yml
    - name: net-tools
      revision: some-sha-goes-here
      path: tools/net-tools
    # ... other Zephyr modules go here ...
  self:
    path: application

(The west-commands is there for Building, Flashing and Debugging and other Zephyr-specific Extensions. It’s not necessary when using import.)

The main advantage to using import is not having to track the revisions of imported projects separately. In the above example, using import means Zephyr’s module versions are automatically determined from the zephyr/west.yml revision, instead of having to be copy/pasted (and maintained) on their own.

T3: Forest topology

Useful for those supporting multiple independent applications or downstream distributions with no “central” repository
A dedicated manifest repository which contains no Zephyr source code, and specifies a list of projects all at the same “level”
Analogy with existing mechanisms: Google repo-based source distribution