274 lines
11 KiB
ReStructuredText
274 lines
11 KiB
ReStructuredText
.. _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.
|