.. _west-built-in-cmds: Built-in commands ################# This page describes west's built-in commands, some of which were introduced in :ref:`west-basics`, in more detail. Some commands are related to Git commands with the same name, but operate on the entire workspace. For example, ``west diff`` shows local changes in multiple Git repositories in the workspace. Some commands take projects as arguments. These arguments can be project names as specified in the manifest file, or (as a fallback) paths to them on the local file system. Omitting project arguments to commands which accept them (such as ``west list``, ``west forall``, etc.) usually defaults to using all projects in the manifest file plus the manifest repository itself. For additional help, run ``west -h`` (e.g. ``west init -h``). .. _west-init: west init ********* This command creates a west workspace. It can be used in two ways: 1. Cloning a new manifest repository from a remote URL 2. Creating a workspace around an existing local manifest repository **Option 1**: to clone a new manifest repository from a remote URL, use: .. code-block:: none west init [-m URL] [--mr REVISION] [--mf FILE] [directory] The new workspace is created in the given :file:`directory`, creating a new :file:`.west` inside this directory. You can give the manifest URL using the ``-m`` switch, the initial revision to check out using ``--mr``, and the location of the manifest file within the repository using ``--mf``. For example, running: .. code-block:: shell west init -m https://github.com/zephyrproject-rtos/zephyr --mr v1.14.0 zp would clone the upstream official zephyr repository into :file:`zp/zephyr`, and check out the ``v1.14.0`` release. This command creates :file:`zp/.west`, and set the ``manifest.path`` :ref:`configuration option ` to ``zephyr`` to record the location of the manifest repository in the workspace. The default manifest file location is used. The ``-m`` option defaults to ``https://github.com/zephyrproject-rtos/zephyr``. The ``--mf`` option defaults to ``west.yml``. Since west v0.10.1, west will use the default branch in the manifest repository unless the ``--mr`` option is used to override it. (In prior versions, ``--mr`` defaulted to ``master``.) If no ``directory`` is given, the current working directory is used. **Option 2**: to create a workspace around an existing local manifest repository, use: .. code-block:: none west init -l [--mf FILE] directory This creates :file:`.west` **next to** :file:`directory` in the file system, and sets ``manifest.path`` to ``directory``. As above, ``--mf`` defaults to ``west.yml``. **Reconfiguring the workspace**: If you change your mind later, you are free to change ``manifest.path`` and ``manifest.file`` using :ref:`west-config-cmd` after running ``west init``. Just be sure to run ``west update`` afterwards to update your workspace to match the new manifest file. .. _west-update: west update *********** .. code-block:: none west update [-f {always,smart}] [-k] [-r] [--group-filter FILTER] [--stats] [PROJECT ...] **Which projects are updated:** By default, this command parses the manifest file, usually :file:`west.yml`, and updates each project specified there. If your manifest uses :ref:`project groups `, then only the active projects are updated. To operate on a subset of projects only, give ``PROJECT`` argument(s). Each ``PROJECT`` is either a project name as given in the manifest file, or a path that points to the project within the workspace. If you specify projects explicitly, they are updated regardless of whether they are active. **Project update procedure:** For each project that is updated, this command: #. Initializes a local Git repository for the project in the workspace, if it does not already exist #. Inspects the project's ``revision`` field in the manifest, and fetches it from the remote if it is not already available locally #. Sets the project's :ref:`manifest-rev ` branch to the commit specified by the revision in the previous step #. Checks out ``manifest-rev`` in the local working copy as a `detached HEAD `_ #. If the manifest file specifies a :ref:`submodules ` key for the project, recursively updates the project's submodules as described below. To avoid unnecessary fetches, ``west update`` will not fetch project ``revision`` values which are Git SHAs or tags that are already available locally. This is the behavior when the ``-f`` (``--fetch``) option has its default value, ``smart``. To force this command to fetch from project remotes even if the revisions appear to be available locally, either use ``-f always`` or set the ``update.fetch`` :ref:`configuration option ` to ``always``. SHAs may be given as unique prefixes as long as they are acceptable to Git [#fetchall]_. If the project ``revision`` is a Git ref that is neither a tag nor a SHA (i.e. if the project is tracking a branch), ``west update`` always fetches, regardless of ``-f`` and ``update.fetch``. Some branch names might look like short SHAs, like ``deadbeef``. West treats these like SHAs. You can disambiguate by prefixing the ``revision`` value with ``refs/heads/``, e.g. ``revision: refs/heads/deadbeef``. For safety, ``west update`` uses ``git checkout --detach`` to check out a detached ``HEAD`` at the manifest revision for each updated project, leaving behind any branches which were already checked out. This is typically a safe operation that will not modify any of your local branches. However, if you had added some local commits onto a previously detached ``HEAD`` checked out by west, then git will warn you that you've left behind some commits which are no longer referred to by any branch. These may be garbage-collected and lost at some point in the future. To avoid this if you have local commits in the project, make sure you have a local branch checked out before running ``west update``. If you would rather rebase any locally checked out branches instead, use the ``-r`` (``--rebase``) option. If you would like ``west update`` to keep local branches checked out as long as they point to commits that are descendants of the new ``manifest-rev``, use the ``-k`` (``--keep-descendants``) option. .. note:: ``west update --rebase`` will fail in projects that have git conflicts between your branch and new commits brought in by the manifest. You should immediately resolve these conflicts as you usually do with ``git``, or you can use ``git -C rebase --abort`` to ignore incoming changes for the moment. With a clean working tree, a plain ``west update`` never fails because it does not try to hold on to your commits and simply leaves them aside. ``west update --keep-descendants`` offers an intermediate option that never fails either but does not treat all projects the same: - in projects where your branch diverged from the incoming commits, it does not even try to rebase and leaves your branches behind just like a plain ``west update`` does; - in all other projects where no rebase or merge is needed it keeps your branches in place. **One-time project group manipulation:** The ``--group-filter`` option can be used to change which project groups are enabled or disabled for the duration of a single ``west update`` command. See :ref:`west-manifest-groups` for details on the project group feature. The ``west update`` command behaves as if the ``--group-filter`` option's value were appended to the ``manifest.group-filter`` :ref:`configuration option `. For example, running ``west update --group-filter=+foo,-bar`` would behave the same way as if you had temporarily appended the string ``"+foo,-bar"`` to the value of ``manifest.group-filter``, run ``west update``, then restored ``manifest.group-filter`` to its original value. Note that using the syntax ``--group-filter=VALUE`` instead of ``--group-filter VALUE`` avoids issues parsing command line options if you just want to disable a single group, e.g. ``--group-filter=-bar``. **Submodule update procedure:** If a project in the manifest has a ``submodules`` key, the submodules are updated as follows, depending on the value of the ``submodules`` key. If the project has ``submodules: true``, west first synchronizes the project's submodules with: .. code-block:: git submodule sync --recursive West then runs one of the following in the project repository, depending on whether you run ``west update`` with the ``--rebase`` option or without it: .. code-block:: # without --rebase, e.g. "west update": git submodule update --init --checkout --recursive # with --rebase, e.g. "west update --rebase": git submodule update --init --rebase --recursive Otherwise, the project has ``submodules: ``. In this case, west synchronizes the project's submodules with: .. code-block:: git submodule sync --recursive -- Then it updates each submodule in the list as follows, depending on whether you run ``west update`` with the ``--rebase`` option or without it: .. code-block:: # without --rebase, e.g. "west update": git submodule update --init --checkout --recursive # with --rebase, e.g. "west update --rebase": git submodule update --init --rebase --recursive The ``git submodule sync`` commands are skipped if the ``update.sync-submodules`` :ref:`west-config` option is false. .. _west-built-in-misc: Other project commands ********************** West has a few more commands for managing the projects in the workspace, which are summarized here. Run ``west -h`` for detailed help. - ``west compare``: compare the state of the workspace against the manifest - ``west diff``: run ``git diff`` in local project repositories - ``west forall``: run an arbitrary command in local project repositories - ``west grep``: search for patterns in local project repositories - ``west list``: print a line of information about each project in the manifest, according to a format string - ``west manifest``: manage the manifest file. See :ref:`west-manifest-cmd`. - ``west status``: run ``git status`` in local project repositories Other built-in commands *********************** Finally, here is a summary of other built-in commands. - ``west config``: get or set :ref:`configuration options ` - ``west topdir``: print the top level directory of the west workspace - ``west help``: get help about a command, or print information about all commands in the workspace, including :ref:`west-extensions` .. rubric:: Footnotes .. [#fetchall] West may fetch all refs from the Git server when given a SHA as a revision. This is because some Git servers have historically not allowed fetching SHAs directly.