1.. _west-aliases:
2
3West aliases
4############
5
6West allows to add alias commands to the local, global or system configuration files.
7These aliases make it easy to add shortcuts for frequently used, or hard to memorize
8commands for ease of development.
9
10Similar to how ``git`` aliases work, the alias command is replaced with the alias'
11full text and parsed as a new shell argument list (using the Python function
12`shlex.split()`_ internally to split the value). This enables adding argument
13parameters as they were passed to the original command. Spaces are considered
14argument separators; use proper escaping if arguments shouldn't be split.
15
16.. _shlex.split(): https://docs.python.org/3/library/shlex.html#shlex.split
17
18To add a new alias simply call the ``west config`` command:
19
20.. code-block:: shell
21
22   west config alias.mylist "list -f '{name} {revision}'"
23
24To list aliases, use :samp:`west help {some_alias}`.
25
26Recursive aliases are allowed as an alias command can contain other aliases, effectively
27building more complex but easy-to-remember commands.
28
29It is possible to override an existing command, for example to pass default arguments:
30
31.. code-block:: shell
32
33   west config alias.update "update -o=--depth=1 -n"
34
35.. warning::
36
37   Overriding/shadowing other or built-in commands is an advanced use case, it can lead to
38   strange side-effects and should be done with great care.
39
40Examples
41--------
42
43Add ``west run`` and ``west menuconfig`` shortcuts to your global configuration to
44call ``west build`` with the corresponding CMake targets:
45
46.. code-block:: shell
47
48   west config --global alias.run "build --pristine=never --target run"
49   west config --global alias.menuconfig "build --pristine=never --target menuconfig"
50
51Create an alias for the sample you are actively developing with additional options:
52
53.. code-block:: shell
54
55   west config alias.sample "build -b native_sim samples/hello_world -t run -- -DCONFIG_ASSERT=y"
56
57Override ``west update`` to check a local cache:
58
59.. code-block:: shell
60
61   west config alias.update "update --path-cache $HOME/.cache/zephyrproject"
62