diff --git a/doc/guides/west/config.rst b/doc/guides/west/config.rst index 67c3758d6e3..9b87b0a03ec 100644 --- a/doc/guides/west/config.rst +++ b/doc/guides/west/config.rst @@ -139,6 +139,13 @@ commands are documented in the pages for those commands. - String, relative path from the :term:`west installation` root directory to the manifest repository used by ``west update`` and other commands which parse the manifest. Set locally by ``west init``. + * - ``update.fetch`` + - String, one of ``"smart"`` (the default behavior starting in v0.6.1) or + ``"always"`` (the previous behavior). If set to ``"smart"``, the + :ref:`west update ` command will skip fetching + from project remotes when those projects' revisions in the manifest file + are SHAs or tags which are already available locally. The ``"always"`` + behavior is to unconditionally fetch from the remote. * - ``zephyr.base`` - String, default value to set for the :envvar:`ZEPHYR_BASE` environment variable while the west command is running. By default, this is set to diff --git a/doc/guides/west/release-notes.rst b/doc/guides/west/release-notes.rst index cb4ebc7ec1b..78badca2340 100644 --- a/doc/guides/west/release-notes.rst +++ b/doc/guides/west/release-notes.rst @@ -1,7 +1,48 @@ West Release Notes ################## -v0.6.x +v0.6.1 +****** + +The user-visible features in this point release are: + +- The `west update ` command has a new ``--fetch`` + command line flag and ``update.fetch`` :ref:`configuration option + `. The default value, "smart", skips fetching SHAs and tags + which are available locally. +- Better and more consistent error-handling in the ``west diff``, ``west + status``, ``west forall``, and ``west update`` commands. Each of these + commands can operate on multiple projects; if a subprocess related to one + project fails, these commands now continue to operate on the rest of the + projects. All of them also now report a nonzero error code from the west + process if any of these subprocesses fails (this was previously not true of + ``west forall`` in particular). +- The :ref:`west manifest ` command also handles errors + better. +- The :ref:`west list ` command now works even when the + projects are not cloned, as long as its format string only requires + information which can be read from the manifest file. It still fails if the + format string requires data stored in the project repository, e.g. if it + includes the ``{sha}`` format string key. +- Commands and options which operate on git revisions now accept abbreviated + SHAs. For example, ``west init --mr SHA_PREFIX`` now works. Previously, the + ``--mr`` argument needed to be the entire 40 character SHA if it wasn't a + branch or a tag. + +The developer-visible changes to the :ref:`west-apis` are: + +- west.log.banner(): new +- west.log.small_banner(): new +- west.manifest.Manifest.get_projects(): new +- west.manifest.Project.is_cloned(): new +- west.commands.WestCommand instances can now access the parsed + Manifest object via a new self.manifest property during the + do_run() call. If read, it returns the Manifest object or + aborts the command if it could not be parsed. +- west.manifest.Project.git() now has a capture_stderr kwarg + + +v0.6.0 ****** - No separate bootstrapper diff --git a/doc/guides/west/repo-tool.rst b/doc/guides/west/repo-tool.rst index 42dfd3b0941..c5cbe93a0d4 100644 --- a/doc/guides/west/repo-tool.rst +++ b/doc/guides/west/repo-tool.rst @@ -155,6 +155,8 @@ This distribution also includes a launcher executable, also named ``west``. When west is installed, the launcher is placed by :file:`pip3` somewhere in the user's ``PATH``. This is the command-line entry point. +.. _west-manifest-rev: + The ``manifest-rev`` branch *************************** @@ -223,13 +225,27 @@ important to understand. (``-m`` defaults to https://github.com/zephyrproject-rtos/zephyr, and the ``-mr`` default is overridden to ``v1.15.0``). -- ``west update [--rebase] [--keep-descendants] [--exclude-west] [PROJECT - ...]``: clone and update the specified projects based +- ``west update [--fetch {always,smart}] [--rebase] [--keep-descendants] + [PROJECT ...]``: clone and update the specified projects based on the current :term:`west manifest`. - This command parses the manifest, clones any project repositories that are - not already present locally, and checks out the project revisions specified - in the manifest file, updating ``manifest-rev`` branches along the way. + By default, this command: + + #. Parses the manifest file, :file:`west.yml` + #. Clones any project repositories that are not already present locally + #. Fetches any project revisions in the manifest file which are not already + pulled from the remote + #. Sets each project's :ref:`manifest-rev ` branch to the + current manifest revision + #. Checks out those revisions in local working trees + + To operate on a subset of projects only, specify them using the ``PROJECT`` + positional arguments, which can be either project names as given in the + manifest file, or paths to the local project clones. + + To force this command to fetch from project remotes even if the revisions + appear to be available locally, either use ``--fetch always`` or set the + ``update.fetch`` :ref:`configuration option ` to ``"always"``. For safety, ``west update`` uses ``git checkout --detach`` to check out a detached ``HEAD`` at the manifest revision for each updated project, leaving diff --git a/doc/guides/west/west-apis.rst b/doc/guides/west/west-apis.rst index 070f9892d38..b474edfab90 100644 --- a/doc/guides/west/west-apis.rst +++ b/doc/guides/west/west-apis.rst @@ -41,14 +41,14 @@ provided. .. automethod:: __init__ - .. versionadded:: 0.6 + .. versionadded:: 0.6.0 The *requires_installation* parameter. Methods: .. automethod:: run - .. versionchanged:: 0.6 + .. versionchanged:: 0.6.0 The *topdir* argument was added. .. automethod:: add_parser @@ -86,6 +86,16 @@ provided. The argument parser created by calling ``WestCommand.add_parser()``. + Instance properties: + + .. py:attribute:: manifest + + A read-only property which returns the :py:class:`west.manifest.Manifest` + instance for the current manifest file or aborts the program if one was + not provided. This is only safe to use from the ``do_run()`` method. + + .. versionadded:: 0.6.1 + .. autoclass:: west.commands.CommandError :show-inheritance: @@ -119,7 +129,7 @@ west.configuration .. autofunction:: west.configuration.read_config -.. versionchanged:: 0.6 +.. versionchanged:: 0.6.0 Errors due to an inability to find a local configuration file are ignored. .. autofunction:: west.configuration.update_config @@ -136,7 +146,7 @@ west.log ******** .. automodule:: west.log - :members: set_verbosity, VERBOSE_NONE, VERBOSE_NORMAL, VERBOSE_VERY, VERBOSE_EXTREME, dbg, inf, wrn, err, die + :members: set_verbosity, VERBOSE_NONE, VERBOSE_NORMAL, VERBOSE_VERY, VERBOSE_EXTREME, dbg, inf, wrn, err, die, banner, small_banner .. _west-apis-manifest: @@ -163,6 +173,10 @@ west.manifest .. automethod:: get_remote + .. automethod:: get_projects + + .. versionadded:: 0.6.1 + .. automethod:: as_frozen_dict .. autoclass:: west.manifest.Defaults @@ -174,14 +188,35 @@ west.manifest :member-order: groupwise .. autoclass:: west.manifest.Project - :members: - :member-order: groupwise + + .. automethod:: __init__ + + .. automethod:: as_dict + + .. automethod:: format + + .. automethod:: git + + .. versionchanged:: 0.6.1 + The ``capture_stderr`` kwarg. + + .. automethod:: sha + + .. automethod:: is_ancestor_of + + .. automethod:: is_cloned + + .. versionadded:: 0.6.1 + + .. automethod:: is_up_to_date_with + + .. automethod:: is_up_to_date .. autoclass:: west.manifest.ManifestProject :members: :member-order: groupwise -.. versionadded:: 0.6 +.. versionadded:: 0.6.0 .. autoclass:: west.manifest.MalformedManifest :show-inheritance: