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 ``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: ``%HOME%``, then ``%USERPROFILE%``, then a
45     combination of ``%HOMEDRIVE%`` and ``%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   * - :samp:`alias.{ALIAS}`
134     - String. If non-empty the ``<ALIAS>`` can be used as a west command.
135       See :ref:`west-aliases`.
136   * - ``color.ui``
137     - Boolean. If ``true`` (the default), then west output is colorized when
138       stdout is a terminal.
139   * - ``commands.allow_extensions``
140     - Boolean, default ``true``, disables :ref:`west-extensions` if ``false``
141   * - ``grep.color``
142     - String, default empty. Set this to ``never`` to disable ``west grep``
143       color output. If set, ``west grep`` passes the value to the grep tool's
144       ``--color`` option.
145   * - ``grep.tool``
146     - String, one of ``"git-grep"`` (default), ``"ripgrep"``, or ``"grep"``.
147       The grep tool that ``west grep`` should use.
148   * - ``grep.<TOOL>-args``
149     - String, default empty. The ``<TOOL>`` part is a pattern that can be any
150       ``grep.tool`` value, so ``grep.ripgrep-args`` is an example
151       configuration option. If set, arguments that ``west grep`` should pass
152       to the corresponding grep tool. Run ``west help grep`` for details.
153   * - ``grep.<TOOL>-path``
154     - String, default empty. The ``<TOOL>`` part is a pattern that can be any
155       ``grep.tool`` value, so ``grep.ripgrep-path`` is an example
156       configuration option. The path to the corresponding tool that ``west
157       grep`` should use instead of searching for the command. Run ``west help
158       grep`` for details.
159   * - ``manifest.file``
160     - String, default ``west.yml``. Relative path from the manifest repository
161       root directory to the manifest file used by ``west init`` and other
162       commands which parse the manifest.
163   * - ``manifest.group-filter``
164     - String, default empty. A comma-separated list of project groups to
165       enable and disable within the workspace. Prefix enabled groups with
166       ``+`` and disabled groups with ``-``. For example, the value
167       ``"+foo,-bar"`` enables group ``foo`` and disables ``bar``. See
168       :ref:`west-manifest-groups`.
169   * - ``manifest.path``
170     - String, relative path from the :term:`west workspace` root directory
171       to the manifest repository used by ``west update`` and other commands
172       which parse the manifest. Set locally by ``west init``.
173   * - ``manifest.project-filter``
174     - Comma-separated list of strings.
175
176       The option's value is a comma-separated list of regular expressions,
177       each prefixed with ``+`` or ``-``, like this:
178
179       .. code-block:: none
180
181          +re1,-re2,-re3
182
183       Project names are matched against each regular expression (``re1``,
184       ``re2``, ``re3``, ...) in the list, in order. If the entire project name
185       matches the regular expression, that element of the list either
186       deactivates or activates the project. The project is deactivated if the
187       element begins with ``-``. The project is activated if the element
188       begins with ``+``. (Project names cannot contain ``,`` if this option is
189       used, so the regular expressions do not need to contain a literal ``,``
190       character.)
191
192       If a project's name matches multiple regular expressions in the list,
193       the result from the last regular expression is used. For example,
194       if ``manifest.project-filter`` is:
195
196       .. code-block:: none
197
198          -hal_.*,+hal_foo
199
200       Then a project named ``hal_bar`` is inactive, but a project named
201       ``hal_foo`` is active.
202
203       If a project is made inactive or active by a list element, the project
204       is active or not regardless of whether any or all of its groups are
205       disabled. (This is currently the only way to make a project that has no
206       groups inactive.)
207
208       Otherwise, i.e. if a project does not match any regular expressions in
209       the list, it is active or inactive according to the usual rules related
210       to its groups (see :ref:`west-project-group-examples` for examples in
211       that case).
212
213       Within an element of a ``manifest.project-filter`` list, leading and
214       trailing whitespace are ignored. That means these example values
215       are equivalent:
216
217       .. code-block:: none
218
219          +foo,-bar
220          +foo , -bar
221
222       Any empty elements are ignored. That means these example values are
223       equivalent:
224
225       .. code-block:: none
226
227           +foo,,-bar
228           +foo,-bar
229
230   * - ``update.fetch``
231     - String, one of ``"smart"`` (the default behavior starting in v0.6.1) or
232       ``"always"`` (the previous behavior). If set to ``"smart"``, the
233       :ref:`west-update` command will skip fetching
234       from project remotes when those projects' revisions in the manifest file
235       are SHAs or tags which are already available locally. The ``"always"``
236       behavior is to unconditionally fetch from the remote.
237   * - ``update.name-cache``
238     - String. If non-empty, ``west update`` will use its value as the
239       ``--name-cache`` option's value if not given on the command line.
240   * - ``update.narrow``
241     - Boolean. If ``true``, ``west update`` behaves as if ``--narrow`` was
242       given on the command line. The default is ``false``.
243   * - ``update.path-cache``
244     - String. If non-empty, ``west update`` will use its value as the
245       ``--path-cache`` option's value if not given on the command line.
246   * - ``update.sync-submodules``
247     - Boolean. If ``true`` (the default), :ref:`west-update` will synchronize
248       Git submodules before updating them.
249   * - ``zephyr.base``
250     - String, default value to set for the :envvar:`ZEPHYR_BASE` environment
251       variable while the west command is running. By default, this is set to
252       the path to the manifest project with path :file:`zephyr` (if there is
253       one) during ``west init``. If the variable is already set, then this
254       setting is ignored unless ``zephyr.base-prefer`` is ``"configfile"``.
255   * - ``zephyr.base-prefer``
256     - String, one the values ``"env"`` and ``"configfile"``. If set to
257       ``"env"`` (the default), setting :envvar:`ZEPHYR_BASE` in the calling
258       environment overrides the value of the ``zephyr.base`` configuration
259       option. If set to ``"configfile"``, the configuration option wins
260       instead.
261