doc: west: add tl;dr for moving to west and troubleshooting

   :maxdepth: 1

   install.rst

   moving-to-west.rst

   troubleshooting.rst

   repo-tool.rst

   manifest.rst

   config.rst

.. _moving-to-west:

Moving to West

##############

To convert a "pre-west" Zephyr setup on your computer to west, follow these

steps. If you are starting from scratch, use the :ref:`getting_started`

instead. See :ref:`west-troubleshooting` for advice on common issues.

#. Install west.

   On Linux::

     pip3 install --user -U west

   On Windows and macOS::

     pip3 install -U west

   For details, see :ref:`west-install`.

#. Move your zephyr repository to a new :file:`zephyrproject` parent directory,

   and change directory there.

   On Linux and macOS::

     mkdir zephyrproject

     mv zephyr zephyrproject

     cd zephyrproject

   On Windows ``cmd.exe``::

     mkdir zephyrproject

     move zephyr zephyrproject

     chdir zephyrproject

   The name :file:`zephyrproject` is recommended, but you can choose any name

   with no spaces anywhere in the path.

#. Create a :ref:`west installation <west-installation>` using the zephyr

   repository as a local manifest repository::

     west init -l zephyr

   This creates :file:`zephyrproject/.west`, marking the root of your

   installation, and does some other setup. It will not change the contents of

   the zephyr repository in any way.

#. Clone the rest of the repositories used by zephyr::

     west update

   **Make sure to run this command whenever you pull zephyr.** Otherwise, your

   local repositories will get out of sync. (Run ``west list`` for current

   information on these repositories.)

You are done: :file:`zephyrproject` is now set up to use west.

.. _west-troubleshooting:

Troubleshooting West

####################

This page covers common issues with west and how to solve them.

"invalid choice: 'post-init'"

*****************************

If you see this error when running ``west init``:

.. code-block:: none

   west: error: argument <command>: invalid choice: 'post-init'

   (choose from 'init', 'update', 'list', 'manifest', 'diff',

   'status', 'forall', 'config', 'selfupdate', 'help')

Then you have an old version of west installed, and are trying to use it in an

installation that requires a more recent version.

The easiest way to resolve this issue is to upgrade west and retry as follows:

#. Install the latest west with the ``-U`` option for ``pip3 install`` as shown

   in :ref:`west-install`.

#. Back up any contents of :file:`zephyrproject/.west/config` that you want to

   save. (If you don't have any configuration options set, it's safe to skip

   this step.)

#. Completely remove the :file:`zephyrproject/.west` directory (if you don't,

   you will get the "already in an installation" error message discussed next).

#. Run ``west init`` again.

"already in an installation"

****************************

You may see this error when running ``west init``:

.. code-block:: none

   FATAL ERROR: already in an installation (<some directory>), aborting

If this is unexpected and you're really trying to create a new installation,

then it's likely that west is using the :envvar:`ZEPHYR_BASE` :ref:`environment

variable <env_vars>` to locate a west installation elsewhere on your system.

This is intentional behavior; it allows you to put your Zephyr applications in

any directory and still use west.

To resolve this issue, unset :envvar:`ZEPHYR_BASE` and try again.