Lines Matching +full:west +full:- +full:commands
1 .. _west-built-in-cmds:
3 Built-in commands
6 This page describes west's built-in commands, some of which were introduced in
7 :ref:`west-basics`, in more detail.
9 Some commands are related to Git commands with the same name, but operate
10 on the entire workspace. For example, ``west diff`` shows local changes in
13 Some commands take projects as arguments. These arguments can be project
15 on the local file system. Omitting project arguments to commands which
16 accept them (such as ``west list``, ``west forall``, etc.) usually defaults
20 For additional help, run ``west <command> -h`` (e.g. ``west init -h``).
22 .. _west-init:
24 west init
27 This command creates a west workspace. It can be used in two ways:
34 .. code-block:: none
36 west init [-m URL] [--mr REVISION] [--mf FILE] [directory]
39 :file:`.west` inside this directory. You can give the manifest URL using
40 the ``-m`` switch, the initial revision to check out using ``--mr``, and
41 the location of the manifest file within the repository using ``--mf``.
45 .. code-block:: shell
47 west init -m https://github.com/zephyrproject-rtos/zephyr --mr v1.14.0 zp
51 :file:`zp/.west`, and set the ``manifest.path`` :ref:`configuration option
52 <west-config>` to ``zephyr`` to record the location of the manifest
55 The ``-m`` option defaults to ``https://github.com/zephyrproject-rtos/zephyr``.
56 The ``--mf`` option defaults to ``west.yml``. Since west v0.10.1, west will use
57 the default branch in the manifest repository unless the ``--mr`` option
58 is used to override it. (In prior versions, ``--mr`` defaulted to ``master``.)
65 .. code-block:: none
67 west init -l [--mf FILE] directory
69 This creates :file:`.west` **next to** :file:`directory` in the file
72 As above, ``--mf`` defaults to ``west.yml``.
77 ``manifest.file`` using :ref:`west-config-cmd` after running ``west init``.
78 Just be sure to run ``west update`` afterwards to update your workspace to
81 .. _west-update:
83 west update
86 .. code-block:: none
88 west update [-f {always,smart}] [-k] [-r]
89 [--group-filter FILTER] [--stats] [PROJECT ...]
94 :file:`west.yml`, and updates each project specified there.
95 If your manifest uses :ref:`project groups <west-manifest-groups>`, then
111 #. Sets the project's :ref:`manifest-rev <west-manifest-rev>` branch to the
113 #. Checks out ``manifest-rev`` in the local working copy as a `detached
114 HEAD <https://git-scm.com/docs/git-checkout#_detached_head>`_
116 <west-manifest-submodules>` key for the project, recursively updates
119 To avoid unnecessary fetches, ``west update`` will not fetch project
121 locally. This is the behavior when the ``-f`` (``--fetch``) option has its
123 even if the revisions appear to be available locally, either use ``-f always``
124 or set the ``update.fetch`` :ref:`configuration option <west-config>` to
129 if the project is tracking a branch), ``west update`` always fetches,
130 regardless of ``-f`` and ``update.fetch``.
132 Some branch names might look like short SHAs, like ``deadbeef``. West treats
136 For safety, ``west update`` uses ``git checkout --detach`` to check out a
142 ``HEAD`` checked out by west, then git will warn you that you've left
144 may be garbage-collected and lost at some point in the future. To avoid
146 branch checked out before running ``west update``.
149 the ``-r`` (``--rebase``) option.
151 If you would like ``west update`` to keep local branches checked out as
153 ``manifest-rev``, use the ``-k`` (``--keep-descendants``) option.
157 ``west update --rebase`` will fail in projects that have git conflicts
160 ``git``, or you can use ``git -C <project_path> rebase --abort`` to
163 With a clean working tree, a plain ``west update`` never fails
167 ``west update --keep-descendants`` offers an intermediate option that
170 - in projects where your branch diverged from the incoming commits, it
172 plain ``west update`` does;
173 - in all other projects where no rebase or merge is needed it keeps
176 **One-time project group manipulation:**
178 The ``--group-filter`` option can be used to change which project groups
179 are enabled or disabled for the duration of a single ``west update`` command.
180 See :ref:`west-manifest-groups` for details on the project group feature.
182 The ``west update`` command behaves as if the ``--group-filter`` option's
183 value were appended to the ``manifest.group-filter``
184 :ref:`configuration option <west-config-index>`.
186 For example, running ``west update --group-filter=+foo,-bar`` would behave
187 the same way as if you had temporarily appended the string ``"+foo,-bar"``
188 to the value of ``manifest.group-filter``, run ``west update``, then restored
189 ``manifest.group-filter`` to its original value.
191 Note that using the syntax ``--group-filter=VALUE`` instead of
192 ``--group-filter VALUE`` avoids issues parsing command line options
193 if you just want to disable a single group, e.g. ``--group-filter=-bar``.
200 If the project has ``submodules: true``, west first synchronizes the project's
203 .. code-block::
205 git submodule sync --recursive
207 West then runs one of the following in the project repository, depending on
208 whether you run ``west update`` with the ``--rebase`` option or without it:
210 .. code-block::
212 # without --rebase, e.g. "west update":
213 git submodule update --init --checkout --recursive
215 # with --rebase, e.g. "west update --rebase":
216 git submodule update --init --rebase --recursive
218 Otherwise, the project has ``submodules: <list-of-submodules>``. In this
219 case, west synchronizes the project's submodules with:
221 .. code-block::
223 git submodule sync --recursive -- <submodule-path>
226 run ``west update`` with the ``--rebase`` option or without it:
228 .. code-block::
230 # without --rebase, e.g. "west update":
231 git submodule update --init --checkout --recursive <submodule-path>
233 # with --rebase, e.g. "west update --rebase":
234 git submodule update --init --rebase --recursive <submodule-path>
236 The ``git submodule sync`` commands are skipped if the
237 ``update.sync-submodules`` :ref:`west-config` option is false.
239 .. _west-built-in-misc:
241 Other project commands
244 West has a few more commands for managing the projects in the
245 workspace, which are summarized here. Run ``west <command> -h`` for
248 - ``west list``: print a line of information about each project in the
250 - ``west manifest``: manage the manifest file. See :ref:`west-manifest-cmd`.
251 - ``west diff``: run ``git diff`` in local project repositories
252 - ``west status``: run ``git status`` in local project repositories
253 - ``west forall``: run an arbitrary command in local project repositories
255 Other built-in commands
258 Finally, here is a summary of other built-in commands.
260 - ``west config``: get or set :ref:`configuration options <west-config>`
261 - ``west topdir``: print the top level directory of the west workspace
262 - ``west help``: get help about a command, or print information about all
263 commands in the workspace, including :ref:`west-extensions`
269 West may fetch all refs from the Git server when given a SHA as a revision.