Validates <DST> (rejects reserved names like list, clone, …).
Refuses a self-clone: the same name, or two names for one directory
(Web and web on a case-insensitive filesystem).
Refuses an existing <DST> unless --force.
Resolves <SRC>’s recorded Python version from its metadata; surfaces a
clear CorruptedEnvironment error when metadata is missing so you know
recreate-from-scratch is the right next step.
Unless --no-packages, lists the source’s installed packages with
uv pip list and reads where each came from (its PEP 610
direct_url.json, through the source’s own Python 3.8+; see
scuv export). A failed listing, or a package whose
origin cannot be read or matched (PACKAGE_ORIGINS_UNREADABLE), stops
the clone instead of copying a guess.
Checks that every package can be put back: each local source path
exists (a directory being that package’s project), none lies inside
<DST> or is reached through it when --force
would delete it, and a hashed archive has a uv (0.11.29+) that checks
the hash. See scuv import for the error codes.
When a project has moved since it was installed, reinstall it into
<SRC> from its new place first
(uv pip install --python <SRC python> [-e] <new path>).
Only now does --force remove the existing <DST>, so a source that
cannot be cloned leaves it in place.
Creates <DST> at the same Python version and installs the packages in
one uv pip install, each from where it came: name==version from the
registry, --editable <path> for an editable project (the same working
tree, shared with the source), name @ <url> for a local directory or
archive, name @ git+<url>@<commit> for a git checkout. If the install
fails, scuv removes the <DST> it just created (best effort) and
reports the install error.
--force is not transactional: once step 7 has removed the old <DST>, a
failure in step 8 does not bring it back.
Invalid dst name, self-clone, src missing, dst exists without --force, a package origin that cannot be read or put back, or a uv failure (listing, creating, installing)