From b19ad6558167451b1bbc96c34874754eecc10f1a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=81lvaro=20Tejero-Cantero?=
 <807608+alvorithm@users.noreply.github.com>
Date: Tue, 3 Nov 2026 16:06:44 +0100
Subject: [PATCH] :wrench: Store devenv workspace clones in the XDG data
 directory (#11986)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

manage.sh has kept the ws1+ workspace clones in
~/.penpot/penpot_workspaces since parallel instances landed (#9906).
That directory sits outside the XDG base directory layout. The default
is now $XDG_DATA_HOME/penpot-devenv/workspaces, with ~/.local/share
standing in when the variable is unset or empty. It is the data
directory and not the cache, because a clone can hold commits that
exist nowhere else.

A directory that already exists at the former default keeps being
used, so existing clones are neither orphaned nor seeded again. An
exported PENPOT_WORKSPACES_DIR still overrides both.

AI-assisted-by: claude-opus-5-5

Signed-off-by: Álvaro Tejero Cantero <alvorithm@teje.ro>
---
 .serena/memories/devenv/core.md          |  2 +-
 docs/technical-guide/developer/devenv.md |  5 +++--
 manage.sh                                | 13 ++++++++++++-
 3 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/.serena/memories/devenv/core.md b/.serena/memories/devenv/core.md
index 415a69342e..3507a5d6e0 100644
--- a/.serena/memories/devenv/core.md
+++ b/.serena/memories/devenv/core.md
@@ -5,7 +5,7 @@ Compose-based dev environment under `docker/devenv/`, driven by `manage.sh`. Par
 ## Compose project layout
 
 - `penpotdev-infra`: shared `postgres`, `rustfs`, `valkey`, `mailer`, `ldap`. File: `docker-compose.infra.yml`.
-- `penpotdev-wsN` (N=0,1,…): per-instance `main` + `redis` (Valkey). File: `docker-compose.main.yml`. ws0 (a.k.a. `main`) binds `$PWD`; ws1+ bind clones at `${PENPOT_WORKSPACES_DIR}/wsN/` (default `~/.penpot/penpot_workspaces/`), maintained by the developer.
+- `penpotdev-wsN` (N=0,1,…): per-instance `main` + `redis` (Valkey). File: `docker-compose.main.yml`. ws0 (a.k.a. `main`) binds `$PWD`; ws1+ bind clones at `${PENPOT_WORKSPACES_DIR}/wsN/` (default `${XDG_DATA_HOME:-~/.local/share}/penpot-devenv/workspaces/`, or the former `~/.penpot/penpot_workspaces/` when it already exists), maintained by the developer.
 - Optional overlay `docker-compose.opencode.yml`: added by `instance-compose` as an extra `-f` only when `PENPOT_OPENCODE_CONFIG_DIR` is set (i.e. `run-devenv --opencode-config-dir DIR` ran in this process). Bind-mounts the host dir at `/home/penpot/.config/opencode` (`:z`). Flag-only, per-call; not read from ambient env. Parser `parse-opencode-config-dir` absolutizes (`~`, realpath) because compose resolves relative bind sources against the compose file's dir. Only instances brought up with the flag get the mount.
 - All projects join external network `penpot_shared`. Created idempotently by `ensure-devenv-network`, never removed by lifecycle commands.
 
diff --git a/docs/technical-guide/developer/devenv.md b/docs/technical-guide/developer/devenv.md
index 6ec4c8fc25..697d119b1c 100644
--- a/docs/technical-guide/developer/devenv.md
+++ b/docs/technical-guide/developer/devenv.md
@@ -66,8 +66,9 @@ The devenv runs as separate compose projects:
   * `penpotdev-wsN` project per runtime instance.
      - `ws0` (a.k.a. `main`) is the current state of your repo;
      - `ws1` and up are clones that you maintain explicitly under `${PENPOT_WORKSPACES_DIR}/wsN/`
-       (default `~/.penpot/penpot_workspaces/`). You can explicitly sync them
-       with the `--sync` flag (automatic on first start).
+       (default `${XDG_DATA_HOME:-~/.local/share}/penpot-devenv/workspaces/`, or
+       `~/.penpot/penpot_workspaces/` when that directory already exists). You
+       can explicitly sync them with the `--sync` flag (automatic on first start).
 
 Each call to `run-devenv` brings up one instance. Workspaces are independent
 and can be started and stopped in any order:
diff --git a/manage.sh b/manage.sh
index 950c184001..2696b9eefe 100755
--- a/manage.sh
+++ b/manage.sh
@@ -40,7 +40,18 @@ export PENPOT_SOURCE_PATH="${PENPOT_SOURCE_PATH:-$PWD}"
 
 # Base directory under which non-main workspace clones live (one subdir per
 # wsN, N>=1). Documented in defaults.env; default lives here so $HOME expands.
-export PENPOT_WORKSPACES_DIR="${PENPOT_WORKSPACES_DIR:-$HOME/.penpot/penpot_workspaces}"
+# The default follows the XDG base directory spec, in the data directory
+# because a clone can hold commits that exist nowhere else. A directory that
+# already exists at the former default, ~/.penpot/penpot_workspaces, keeps
+# being used, so existing clones are neither orphaned nor seeded again.
+if [[ -z "${PENPOT_WORKSPACES_DIR:-}" ]]; then
+    if [[ -d "$HOME/.penpot/penpot_workspaces" ]]; then
+        PENPOT_WORKSPACES_DIR="$HOME/.penpot/penpot_workspaces"
+    else
+        PENPOT_WORKSPACES_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/penpot-devenv/workspaces"
+    fi
+fi
+export PENPOT_WORKSPACES_DIR
 
 # Port allocation for parallel instances. Each wsN reserves a stride-wide port
 # block starting at N*stride; ws0 sits at offset 0, so a per-service base port