---
name: x-cmd/repo
source: https://app.decimal.ai/s/x-cmd-repo@1/SKILL.md
source_sha256: b883338ae37e
---

# repo

## Why

All clones converge at `~/.x-repo/<provider>/<owner>/<name>`. Same path for every agent, human, CI — mountable into containers or agent sandboxes so they share without re-cloning. One root to back up; discoverable via `x repo ls`. Layout mirrors github paths so `../<sibling>` from any worktree resolves to that sibling's default worktree — configs and scripts that reference siblings work uniformly across wts and agents.

## Path layout

- bare: `~/.x-repo/.bare/<provider>/<owner>/<name>.git`
- default wt: `~/.x-repo/<provider>/<owner>/<name>`
- designed wt: `~/.x-repo/<provider>/<owner>/<name>@<wtname>`

`@<wtname>` — wtname is any identifier for this workspace: agent/worker name, branch name, tag, short SHA, issue id, free-form string. `/` in wtname encodes to `~`.

By default, repos are bare with linked worktrees — the bare in `.bare/`, a separate directory from the worktrees, so `rm -rf` of one wt can't reach it. Plain `git clone` is also accepted (`x repo ls/which/update` see it) but without geometric protection. Please be careful in that case: don't `rm -rf`, prefer `git worktree remove`, and avoid cleanup heuristics that target `.git/`. Mid-task work lost this way can't be realigned with the original repo.

## Commands

```bash
x repo <id>                      # cd to default wt (auto-clones if missing)
x repo wt <id> <wtname>          # attach to existing branch, or create new from HEAD
x repo wt ls <id>                # list wts
x repo wt rm <id> <wtname>       # graceful remove (use this, not rm -rf)
x repo update <id>               # refresh default wt after upstream changes
x repo ls [--raw|--tsv]          # discover what's cloned
x repo which <id>[@<wtname>]     # resolve id to absolute path
```

## Don't

- `rm -rf` a designed worktree. It leaves stale entries in the bare's `worktrees/` registry. Use `x repo wt rm`. If you must, run `git -C <bare> worktree prune` afterwards.

## Related

- [doc/path-layout.md](doc/path-layout.md) — full path grammar and worktree naming
- [doc/workflow.md](doc/workflow.md) — operating procedure and cleanup-non-deletion principles
- [doc/design.md](doc/design.md) — why the layout is shaped this way