From 7d40091fbfedfc51596447212b408a06cefd702b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mart=C3=AD=20Bol=C3=ADvar?= Date: Tue, 21 Jan 2025 09:52:46 -0800 Subject: [PATCH] doc: the west workspace topdir is not a git repository MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It's a design decision that the west workspace "topdir" (that is, the top level directory containing the .west directory), is not itself a git repository. This exists to give us some breathing room to make changes to the workspace which would otherwise potentially cause breakage if the entire workspace is in .git. While this has always been the case, I'm documenting this now because I reviewed a PR today that flipped my bit from "this is a question to answer on a case by case basis" to "this is a frequently enough asked question that I want to be able to link people to the answer": https://github.com/zephyrproject-rtos/zephyr/pull/84305 We can debate the wisdom of this design decision (and, informally, I've always tried to avoid breaking these setups), but IMO it's too late to try to change this in west. Make it explicit in the docs that you're on your own if you try this. Signed-off-by: Martí Bolívar --- doc/develop/west/workspaces.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/develop/west/workspaces.rst b/doc/develop/west/workspaces.rst index 5c182658df9..d3dadc2b369 100644 --- a/doc/develop/west/workspaces.rst +++ b/doc/develop/west/workspaces.rst @@ -321,3 +321,25 @@ v2.5.0 and its modules, then add the ``app1`` and ``app2`` projects: You can also do this "by hand" by copy/pasting :file:`zephyr/west.yml` as shown :ref:`above ` for the T2 topology, with the same caveats. + +.. _workspace-as-git-repo: + +Not supported: workspace topdir as .git repository +************************************************** + +Some users have asked for support making the workspace :ref:`topdir +` a git repository, like this example: + +.. code-block:: none + + my-workspace/ # workspace topdir + ├── .git/ # puts the entire workspace in a git repository + ├── .west/ # marks the location of the topdir + └── [ ... other projects ...] + +This is **not** an officially supported topology. As a design decision, west +assumes that the workspace topdir itself is not a git repository. + +You may be able to make something like this "work" for yourself and your own +goals. However, future versions of west might contain changes which can "break" +your setup.