Skip to content

Account for Upstream Clones in the Repo Layout Convention #725

Description

@ptr727

The repo-worktree skill's layout convention specifies a flat ~/repos/<Repo> with no owner segment. Its reasoning in #699 is that a repo name is unique within one GitHub owner, and every repo on a fleet machine is under one owner.

That assumption does not hold on a machine that also keeps upstream clones. Migrating this Windows host to the convention today found 27 ptr727 repos alongside 9 clones from 8 other owners. Those include read-only upstream references such as home-assistant/core, ludeeus/integration_blueprint, and mixelpixx/KiCAD-MCP-Server.

Flattening those produces a direct collision. The upstream clone home-assistant/core and the fork ptr727/home-assistant-core both flatten to home-assistant-core. The fork naming convention is what creates the collision, because a fork already encodes <upstream-owner>-<repo> in its own name.

Flattening without a prefix is no better. home-assistant/core lands as a bare core, and home-assistant/example-custom-config as example-custom-config. Neither name identifies its project.

This host resolved it with an upstream/ segment:

~/repos/<Repo>                          base clone, own repos and forks, flat
~/repos/worktrees/<Repo>-<task-slug>    one worktree per in-flight task, own branch
~/repos/upstream/<owner>/<repo>         third-party clone, not a fork

The upstream/ name states the relationship rather than the owner. A reader tells a working repo from a reference checkout without a git remote check. The owner segment inside it is safe, because it never competes with the flat namespace above it.

Proposal: state the upstream/ segment in the repo-worktree skill's layout block. Drop or qualify the "every repo here is under one owner" reasoning carried from #699.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions