doc/develop/west/built-in.rst

.. _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 <command> -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
<west-config>` 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 <west-manifest-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 <west-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 <https://git-scm.com/docs/git-checkout#_detached_head>`_
#. If the manifest file specifies a :ref:`submodules
   <west-manifest-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 <west-config>` 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 <project_path> 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 <west-config-index>`.

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: <list-of-submodules>``. In this
case, west synchronizes the project's submodules with:

.. code-block::

   git submodule sync --recursive -- <submodule-path>

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 <submodule-path>

   # with --rebase, e.g. "west update --rebase":
   git submodule update --init --rebase --recursive <submodule-path>

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