Skip to content

Worktree root folder is the project UUID instead of the project name #7169

Closed

Description

@l16i

Where did this happen?

Desktop app (macOS)

Version

1.26

What happened?

Worktrees live under ~/.superset/worktrees/<project-id>/<branch>, and the project id is a UUID:

~/.superset/worktrees/d23fcedd-8180-4bb0-9432-931da5173aab/feat/<branch_slug_name>

On v1 that segment was the project name (~/.superset/worktrees/<my_project_name>/…). Every path I touch outside the app now carries 36 characters of hex I can't recognise — cd, the shell prompt, git worktree list, an editor's recent folders — and with more than one project I can't tell the roots apart without looking ids up.

It also can't be referenced from anywhere outside Superset. Agent skills, shell aliases, scripts that map a ticket to a directory, and project instruction files that document where worktrees live all have to hardcode an opaque id that means nothing to a reader and can't be checked by eye.

A related question I couldn't answer from the outside: is that id stable if I remove a project and add it back? If it's re-minted, every one of those references breaks silently — the paths just stop existing, with nothing to explain why. If it's recovered from the cloud by remote URL, that's worth documenting, because from the filesystem there's no way to tell.

Using the project name for that segment (deduplicated on collision), or letting the project carry an explicit folder alias, would fix both the readability and the referenceability.

Steps to reproduce

  1. Create a workspace in any project.
  2. git worktree list, or look at the terminal's cwd.
  3. The path is ~/.superset/worktrees/<uuid>/<branch> — no project name anywhere in it.

Logs, screenshots, or recordings

The segment comes from one place — packages/host-service/src/trpc/router/workspace-creation/shared/worktree-paths.ts:

projectWorktreesRoot(projectId, base) → resolve(base ?? ~/.superset/worktrees, projectId)
safeResolveWorktreePath(projectId, branch, base) → <base>/<projectId>/<branch>

Only <base> is configurable (Project Settings → Worktree location, or the host-wide worktreeBaseDir); the id segment is always appended, so pointing the base somewhere friendly still gives ~/dev/<my_project_name>/<uuid>/<branch>.

Workaround I'm using: ln -s <uuid> ~/.superset/worktrees/<my_project_name>. Superset never reads the alias and isInsideProjectWorktreesRoot canonicalises with realpath, so nothing breaks — but it's manual, per machine, and points at an id I'd have to re-check if the project were ever re-added.

Activity

  1. added
    bugSomething isn't working
    on Sep 4, 2026
  2. github-actions commented on Sep 4, 2026

    @github-actions
    Contributor

    Confirmed from the code: the UUID segment is real, it's the only thing the path scheme allows, and — to answer the question the report couldn't answer from outside — the id is not stable across remove + re-add on the normal import path. Everything below is read from source; I didn't run anything.

    The segment

    packages/host-service/src/trpc/router/workspace-creation/shared/worktree-paths.ts:43-48 is the whole story:

    export function projectWorktreesRoot(projectId, worktreeBaseDir) {
    	return resolve(worktreeBaseDir ?? defaultWorktreesRoot(), projectId);
    }

    and safeResolveWorktreePath (worktree-paths.ts:91-108) appends the branch to that. The only inputs are projectId and the base dir, so the project-settings override and the host-wide worktreeBaseDir can only relocate the parent — <base>/<uuid>/<branch> is fixed. Call sites: packages/host-service/src/trpc/router/workspaces/workspaces.ts:692 and :965, both passing localProject.id.

    The v1 comparison in the report holds too — apps/desktop/src/lib/trpc/routers/workspaces/utils/resolve-worktree-path.ts:12-21 joins project.name, not the id. So this is a deliberate v1→v2 scheme change, not a regression in a single call site, and the "bug" here is really the readability/referenceability loss that came with it.

    Is the id re-minted on remove + re-add?

    Yes, on the normal path.

    • Ids are host-minted per project row: randomUUID() at packages/host-service/src/trpc/router/project/handlers.ts:61.
    • project.remove (packages/host-service/src/trpc/router/project/project.ts:849-909) deletes the projects row outright (the cascade takes workspaces with it).
    • Re-importing the same folder lands in createFromImportLocal (handlers.ts:136-172), whose idempotency guard matches on projects.repoPath — but only against rows that still exist. After a remove there is no row, so it falls through to persistFromResolved and a fresh UUID.

    Two paths do preserve an id, and neither is the one you'd hit re-adding a local folder:

    • project.findByPath with walkAllRemotes (project.ts:512-558) recovers a cloud id by remote URL — but that flag is set only by the v1→v2 importer, and the comment at project.ts:530-532 says it's the last consumer of the cloud v2_projects table and dies with that importer.
    • project.setup (project.ts:648-676) takes a projectId supplied by the host fan-out, which is what keeps the same UUID across multiple hosts for one project.

    So: any external reference to ~/.superset/worktrees/<uuid>/… survives a rename but not a remove/re-add, and nothing warns you. Worth documenting regardless of whether the naming changes.

    The symlink workaround is safe for the reason given — workspaces.worktree_path is a stored absolute path (packages/host-service/src/db/schema.ts:220), and isInsideProjectWorktreesRoot canonicalises both sides via realpathSync (worktree-paths.ts:57-73).

    Reproduction

    Behavioural, no test needed: create a workspace, read worktreePath; then project.remove and re-import the same folder via Add repository → import local, create another workspace, and compare the first segment. A bun:test unit repro fits next to worktree-paths.test.ts:

    expect(safeResolveWorktreePath(project.id, "feat/x", base))
    	.toContain(slugFor(project.name)); // fails today: contains only the uuid

    Fix direction, and the traps in it

    Name-based segments work, but computing them from the current name at call time is the wrong shape. projectWorktreesRoot is also the security predicate behind isInsideProjectWorktreesRoot, and workspace-cleanup.ts:483-493 and :563-573 re-derive it at delete time to decide whether a direct rm -rf is allowed. If the segment tracked projects.name, a rename via project.update (project.ts:104-124) would move the computed root out from under every existing worktree, and cleanup would silently skip removal with a warning instead of deleting.

    What that suggests:

    1. Add a worktreeDirName column, minted once at project creation from a slug of the name (dirNameForEmpty at handlers.ts:20-32 is the existing slug helper) with a numeric suffix on collision, and never rewritten on rename. That also closes the injection angle — project names are free text (z.string().min(1), project.ts:108), so an unsanitised name joined into resolve() gives projectWorktreesRoot the traversal problem safeResolveWorktreePath currently only guards for branches.
    2. Backfill it to the existing UUID for every current row, so no one's paths move and the symlink workaround stays valid. New projects get readable roots; old ones can opt in by a settings action that moves the folder and rewrites workspaces.worktree_path.
    3. Exposing it as an editable "folder alias" in project settings is then a small addition, and gives the referenceability the report is really after.

    Consumers that parse the layout and should be checked against any change: packages/host-service/src/trpc/router/usage/history/aggregate.ts:146-152 (assumes exactly one segment between worktrees and the workspace name), apps/desktop/src/main/lib/dev-workspace-name.ts:16-39 (segment-count based, likely fine), and the scheme assertions in packages/host-service/test/integration/workspace-create-delete.integration.test.ts:57 and :188.

  3. l16i commented on Sep 25, 2026

    @l16i
    Author

    Fix with PR #7650

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions