1.. _west-config:
2
3Configuration
4#############
5
6This page documents west's configuration file system, the ``west config``
7command, and configuration options used by built-in commands. For API
8documentation on the ``west.configuration`` module, see
9:ref:`west-apis-configuration`.
10
11West Configuration Files
12------------------------
13
14West's configuration file syntax is INI-like; here is an example file:
15
16.. code-block:: ini
17
18   [manifest]
19   path = zephyr
20
21   [zephyr]
22   base = zephyr
23
24Above, the ``manifest`` section has option ``path`` set to ``zephyr``. Another
25way to say the same thing is that ``manifest.path`` is ``zephyr`` in this file.
26
27There are three types of configuration file:
28
291. **System**: Settings in this file affect west's behavior for every user
30   logged in to the computer. Its location depends on the platform:
31
32   - Linux: :file:`/etc/westconfig`
33   - macOS: :file:`/usr/local/etc/westconfig`
34   - Windows: :file:`%PROGRAMDATA%\\west\\config`
35
362. **Global** (per user): Settings in this file affect how west behaves when
37   run by a particular user on the computer.
38
39   - All platforms: the default is :file:`.westconfig` in the user's home
40     directory.
41   - Linux note: if the environment variable :envvar:`XDG_CONFIG_HOME` is set,
42     then :file:`$XDG_CONFIG_HOME/west/config` is used.
43   - Windows note: the following environment variables are tested to find the
44     home directory: :envvar:`%HOME%`, then :envvar:`%USERPROFILE%`, then a
45     combination of :envvar:`%HOMEDRIVE%` and :envvar:`%HOMEPATH%`.
46
473. **Local**: Settings in this file affect west's behavior for the
48   current :term:`west workspace`. The file is :file:`.west/config`, relative
49   to the workspace's root directory.
50
51A setting in a file which appears lower down on this list overrides an earlier
52setting. For example, if ``color.ui`` is ``true`` in the system's configuration
53file, but ``false`` in the workspace's, then the final value is
54``false``. Similarly, settings in the user configuration file override system
55settings, and so on.
56
57.. _west-config-cmd:
58
59west config
60-----------
61
62The built-in ``config`` command can be used to get and set configuration
63values. You can pass ``west config`` the options ``--system``, ``--global``, or
64``--local`` to specify which configuration file to use. Only one of these can
65be used at a time. If none is given, then writes default to ``--local``, and
66reads show the final value after applying overrides.
67
68Some examples for common uses follow; run ``west config -h`` for detailed help,
69and see :ref:`west-config-index` for more details on built-in options.
70
71To set ``manifest.path`` to :file:`some-other-manifest`:
72
73.. code-block:: console
74
75   west config manifest.path some-other-manifest
76
77Doing the above means that commands like ``west update`` will look for the
78:term:`west manifest` inside the :file:`some-other-manifest` directory
79(relative to the workspace root directory) instead of the directory given to
80``west init``, so be careful!
81
82To read ``zephyr.base``, the value which will be used as ``ZEPHYR_BASE`` if it
83is unset in the calling environment (also relative to the workspace root):
84
85.. code-block:: console
86
87   west config zephyr.base
88
89You can switch to another zephyr repository without changing ``manifest.path``
90-- and thus the behavior of commands like ``west update`` -- using:
91
92.. code-block:: console
93
94   west config zephyr.base some-other-zephyr
95
96This can be useful if you use commands like ``git worktree`` to create your own
97zephyr directories, and want commands like ``west build`` to use them instead
98of the zephyr repository specified in the manifest. (You can go back to using
99the directory in the upstream manifest by running ``west config zephyr.base
100zephyr``.)
101
102To set ``color.ui`` to ``false`` in the global (user-wide) configuration file,
103so that west will no longer print colored output for that user when run in any
104workspace:
105
106.. code-block:: console
107
108   west config --global color.ui false
109
110To undo the above change:
111
112.. code-block:: console
113
114   west config --global color.ui true
115
116.. _west-config-index:
117
118Built-in Configuration Options
119------------------------------
120
121The following table documents configuration options supported by west's
122built-in commands. Configuration options supported by Zephyr's extension
123commands are documented in the pages for those commands.
124
125.. NOTE: docs authors: keep this table sorted by section, then option.
126
127.. list-table::
128   :widths: 10 30
129   :header-rows: 1
130
131   * - Option
132     - Description
133   * - ``color.ui``
134     - Boolean. If ``true`` (the default), then west output is colorized when
135       stdout is a terminal.
136   * - ``commands.allow_extensions``
137     - Boolean, default ``true``, disables :ref:`west-extensions` if ``false``
138   * - ``manifest.file``
139     - String, default ``west.yml``. Relative path from the manifest repository
140       root directory to the manifest file used by ``west init`` and other
141       commands which parse the manifest.
142   * - ``manifest.group-filter``
143     - String, default empty. A comma-separated list of project groups to
144       enable and disable within the workspace. Prefix enabled groups with
145       ``+`` and disabled groups with ``-``. For example, the value
146       ``"+foo,-bar"`` enables group ``foo`` and disables ``bar``. See
147       :ref:`west-manifest-groups`.
148   * - ``manifest.path``
149     - String, relative path from the :term:`west workspace` root directory
150       to the manifest repository used by ``west update`` and other commands
151       which parse the manifest. Set locally by ``west init``.
152   * - ``update.fetch``
153     - String, one of ``"smart"`` (the default behavior starting in v0.6.1) or
154       ``"always"`` (the previous behavior). If set to ``"smart"``, the
155       :ref:`west-update` command will skip fetching
156       from project remotes when those projects' revisions in the manifest file
157       are SHAs or tags which are already available locally. The ``"always"``
158       behavior is to unconditionally fetch from the remote.
159   * - ``update.name-cache``
160     - String. If non-empty, ``west update`` will use its value as the
161       ``--name-cache`` option's value if not given on the command line.
162   * - ``update.narrow``
163     - Boolean. If ``true``, ``west update`` behaves as if ``--narrow`` was
164       given on the command line. The default is ``false``.
165   * - ``update.path-cache``
166     - String. If non-empty, ``west update`` will use its value as the
167       ``--path-cache`` option's value if not given on the command line.
168   * - ``update.sync-submodules``
169     - Boolean. If ``true`` (the default), :ref:`west-update` will synchronize
170       Git submodules before updating them.
171   * - ``zephyr.base``
172     - String, default value to set for the :envvar:`ZEPHYR_BASE` environment
173       variable while the west command is running. By default, this is set to
174       the path to the manifest project with path :file:`zephyr` (if there is
175       one) during ``west init``. If the variable is already set, then this
176       setting is ignored unless ``zephyr.base-prefer`` is ``"configfile"``.
177   * - ``zephyr.base-prefer``
178     - String, one the values ``"env"`` and ``"configfile"``. If set to
179       ``"env"`` (the default), setting :envvar:`ZEPHYR_BASE` in the calling
180       environment overrides the value of the ``zephyr.base`` configuration
181       option. If set to ``"configfile"``, the configuration option wins
182       instead.
183