| .. _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. |