cli(add) Accept a repository URL (#563)

`vcspull add` now takes a repository URL in place of a filesystem path, so a
repository can be recorded before it is cloned; the entry lands in the
configuration and `vcspull sync` clones it on the next run. An existing
directory still takes precedence, so adding a checkout by path is unchanged.

The name comes from the URL, with `--name` required when a URL has no path
segment to name. A pip-style revision on a `git+` URL is recorded as
`options.rev` rather than left in the URL, and passing `--pin` as well is an
error. This restores declaring an un-cloned repository, which the path-based
rework in v1.43.0 removed.

Verification:
- uv run ruff format . --check; uv run ruff check .; uv run mypy; uv run py.test; just build-docs;
- every documented `vcspull add` invocation executed in an isolated HOME;
- add-by-URL through to `vcspull sync` cloning and checking out the pinned tag.

Author: tony

CHANGES

@@ -38,6 +38,31 @@ $ uvx --from 'vcspull' --prerelease allow vcspull
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### Add a repository by URL (#563)
+
+{ref}`cli-add` now accepts a repository URL in place of a filesystem path, so you
+can record a repository you have not cloned yet: the entry lands in your
+configuration and {ref}`vcspull sync <cli-sync>` clones it on the next run. The
+name comes from the URL — `--name` supplies one when the URL has no path segment
+to name — and because there is no parent directory to infer a workspace from,
+vcspull offers the workspace roots your configuration already declares, with
+`--workspace` to name one outright. An existing directory still takes
+precedence, so adding a checkout by path is unchanged.
+
+A pip-style revision on a `git+` URL is recorded as `options.rev` rather than
+left in the URL, so `git+https://github.com/pallets/flask.git@v1.0` stores
+`flask` pinned to `v1.0`. Passing `--pin` as well is an error, and a URL shape
+that cannot carry a revision asks you to use `--pin` instead.
+
+### Fixes
+
+- Declaring a repository you have not cloned works again. From v1.43.0 the
+  migration documented for `vcspull import <name> <url>` failed with
+  `Repository path ... does not exist` unless you created an empty directory
+  first. (#563)
+
 ## vcspull v1.65.0 (2026-07-05)
 
 vcspull v1.65.0 sharpens the feedback you get when a sync cannot check out

docs/cli/add.md

@@ -2,11 +2,12 @@
 
 # vcspull add
 
-The `vcspull add` command registers a repository in your
-{ref}`configuration <configuration>` by pointing vcspull at a checkout on
-disk. The command inspects the directory,
-merges duplicate workspace roots by default, and prompts before writing unless
-you pass `--yes`.
+The `vcspull add` command registers a single repository in your
+{ref}`configuration <configuration>`. Point it at a checkout on disk and it
+reads the details out of the directory; give it a repository URL and it records
+the entry without cloning anything, leaving the working tree to
+{ref}`vcspull sync <cli-sync>`. Either way it merges duplicate workspace roots
+by default and prompts before writing unless you pass `--yes`.
 
 ```{note}
 This command replaces the old `vcspull import <name> <url>` from v1.36--v1.39.
@@ -43,6 +44,56 @@ The parent directory (`~/study/python/` in this example) becomes the workspace
 root. vcspull shortens paths under `$HOME` to `~/...` in its log output so the
 preview stays readable.
 
+## Declaring a repository you have not cloned
+
+Pass a repository URL instead of a path when you want the entry in your
+configuration but do not have the code yet:
+
+```vcspull-console
+$ vcspull add https://github.com/pallets/flask.git
+Found new repository to import:
+  + flask (https://github.com/pallets/flask.git)
+  • workspace roots in ~/.vcspull.yaml:
+      1) ~/code/ (default)
+      2) ~/study/python/
+? Import this repository? [y/N/1-2]: y
+  • workspace: ~/code/
+  ↳ path: ~/code/flask
+✓ Successfully added 'flask' (git+https://github.com/pallets/flask.git) to ~/.vcspull.yaml under '~/code/'.
+```
+
+The repository name comes from the URL — `flask` here — unless you pass
+`--name`. A URL with no path to name, such as `https://host/.git`, stops with an
+error asking for `--name`. Nothing is fetched: the entry lands in your
+configuration and {ref}`vcspull sync <cli-sync>` clones it the next time you run
+it.
+
+Because there is no parent directory to infer a workspace from, vcspull offers
+the workspace roots your configuration already declares. Answering `y` accepts
+the default, answering with a number picks a different root, and `--workspace`
+names one outright and skips the list. When the configuration declares no roots
+yet, the current directory becomes the workspace. The workspace and path are
+reported once your answer settles them, so what you see named is the section the
+entry is written under.
+
+### Pinning a revision from the URL
+
+A [pip-style][pip vcs url] revision on a `git+` URL is recorded as
+`options.rev` rather than kept in the URL:
+
+```console
+$ vcspull add git+https://github.com/pallets/flask.git@v1.0
+```
+
+That stores `flask` with `rev: v1.0`. Because `--pin` records the same field,
+passing both is an error. Only `git+` URLs carry a revision this way — on a
+plain `https://` or scp-style URL the revision cannot be told apart from the
+path, so vcspull asks you to pass `--pin` instead of recording a URL that will
+not clone.
+
+A directory on disk always wins. If the argument names something that exists,
+vcspull treats it as a path even when the same text would also parse as a URL.
+
 ## Overriding detected information
 
 ### Choose a different name
@@ -54,6 +105,13 @@ isn't the label you want stored in the configuration:
 $ vcspull add ~/study/python/pytest-docker --name docker-pytest
 ```
 
+`--name` is required, rather than optional, when a URL carries no path segment
+to name — vcspull stops instead of writing an entry you could not address:
+
+```console
+$ vcspull add https://git.example.com/.git --name internal-tools
+```
+
 ### Override the remote URL
 
 vcspull reads the [Git](https://git-scm.com/) `origin` remote automatically. Supply `--url` when you
@@ -63,20 +121,61 @@ need to register a different remote or when the checkout does not have one yet:
 $ vcspull add ~/study/python/example --url https://github.com/org/example
 ```
 
+`--url` accompanies a path. When the argument is already a URL, pass it once and
+leave `--url` off — supplying both is ambiguous, so vcspull stops rather than
+guessing which one you meant.
+
 URLs follow [pip's VCS format][pip vcs url]; vcspull inserts the `git+` prefix
 for HTTPS URLs so the resulting configuration matches
 {ref}`vcspull fmt <cli-fmt>` output.
 
 ### Select a workspace explicitly
 
-The workspace defaults to the checkout's parent directory. Pass
+The workspace defaults to the checkout's parent directory, or — when you add by
+URL — to the first workspace root your configuration declares. Pass
 `--workspace`/`--workspace-root` to store the repository under a different
 section:
 
 ```console
 $ vcspull add ~/scratch/tmp-project --workspace ~/projects/python/
 ```
 
+Naming a workspace also skips the list of declared roots you would otherwise be
+offered when adding by URL:
+
+```console
+$ vcspull add https://github.com/pallets/flask.git --workspace ~/code/
+```
+
+### Record a revision or clone depth
+
+By default an entry tracks its remote's default branch and clones with full
+history. Three flags change that, and each one costs you something in exchange.
+
+Pin the entry to a fixed commit, tag, or branch with `--pin`, which records
+{ref}`options.rev <config-pin>`. The repository stops following its branch until
+you change the pin:
+
+```console
+$ vcspull add ~/study/python/flask --pin v3.0.0
+```
+
+`--shallow` records `options.shallow: true`, so {ref}`vcspull sync <cli-sync>`
+clones with `--depth 1`. That trades git history for disk and time — useful
+across many repositories, awkward if you later need `git log` or `git bisect`.
+An already-shallow checkout is detected without the flag; this forces it on:
+
+```console
+$ vcspull add ~/study/python/django --shallow
+```
+
+When depth 1 is too little, `--depth N` keeps a window of history instead.
+It overrides `--shallow` when both are given:
+
+```console
+$ vcspull add ~/study/python/django --depth 50
+```
+
 ## Confirmation and dry runs
 
 `vcspull add` asks for confirmation before writing. Use `--yes` to skip the
@@ -90,6 +189,15 @@ $ vcspull add ~/study/python/pytest-docker --dry-run
 Dry runs still show duplicate merge diagnostics so you can see what would
 change.
 
+`--yes` answers both prompts for you — the confirmation and, when adding by URL,
+the workspace-root list — which is what you want from a script:
+
+```console
+$ vcspull add https://github.com/pallets/flask.git \
+    --workspace ~/code/ \
+    --yes
+```
+
 ## Choosing configuration files
 
 vcspull searches for configuration files in this order:
@@ -110,7 +218,14 @@ $ vcspull add ~/study/python/pytest-docker \
 vcspull merges duplicate workspace sections before writing so existing
 repositories stay intact. When it collapses multiple sections, the command logs
 a summary of the merge. Prefer to inspect duplicates yourself? Add
-`--no-merge` to keep every section untouched.
+`--no-merge` to keep every section untouched:
+
+```console
+$ vcspull add ~/study/python/pytest-docker --no-merge
+```
+
+The entry is still written; only the merging of repeated workspace roots is
+skipped, and each duplicate is reported as a warning instead.
 
 ## Pinned entries
 
@@ -126,14 +241,22 @@ Repositories whose configuration includes a {ref}`pin <config-pin>` on the
       pin_reason: "pinned to company fork — update manually"
 ```
 
-Attempting to add a repo that matches an existing pinned entry produces a
-warning and leaves the entry untouched:
+Attempting to add a repo that matches an existing pinned entry previews it as
+usual, then warns and leaves the entry untouched:
 
 ```vcspull-console
 $ vcspull add ~/code/internal-fork
-⚠ Repository 'internal-fork' is pinned (pinned to company fork — update manually) — skipping
+Found new repository to import:
+  + internal-fork (git@github.com:myorg/internal-fork.git)
+  • workspace: ~/code/
+  ↳ path: ~/code/internal-fork
+? Import this repository? [y/N]: y
+Repository 'internal-fork' is pinned (pinned to company fork — update manually) — skipping
 ```
 
+The pin is checked when the entry is written, not when the preview is built, so
+confirming still reaches the warning rather than skipping the prompt.
+
 Both `options.pin: true` (global) and `options.pin.add: true` (per-operation)
 block the `add` command. The `pin_reason` (if set) is included in the warning.
 See {ref}`config-pin` for full pin configuration.
@@ -152,15 +275,22 @@ by `vcspull add`:
 
 ```diff
 - $ vcspull import flask https://github.com/pallets/flask.git -c ~/.vcspull.yaml
-+ $ vcspull add ~/code/flask --url https://github.com/pallets/flask.git --file ~/.vcspull.yaml
++ $ vcspull add https://github.com/pallets/flask.git --file ~/.vcspull.yaml
 ```
 
 Key differences:
 
-- `vcspull add` derives the name from the filesystem unless you pass `--name`.
-- The parent directory becomes the workspace automatically; use `--workspace`
-  to override.
-- Use `--url` to record a remote when the checkout does not have one.
+- `vcspull add` derives the name from the URL, or from the directory when you
+  add a checkout, unless you pass `--name`.
+- The workspace comes from the checkout's parent directory, or from the
+  workspace roots your configuration declares when you add by URL; use
+  `--workspace` to override either.
+- Use `--url` to record a remote when a checkout does not have one.
+
+If you tried this migration between v1.43.0 and v1.65.0, it did not work: `add`
+required the repository to be checked out already, so a URL — or a path you had
+not cloned — stopped with `Repository path ... does not exist`. Passing the URL
+straight to `add`, as above, now does what the old command did.
 
 ```{note}
 Starting with v1.55, `vcspull import` is a *different* command that bulk-imports

docs/conf.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import pathlib
+import re
 import sys
 import typing as t
 
@@ -54,10 +55,82 @@
 
 _gp_setup = conf.pop("setup")
 
+_NUMPY_UNDERLINE = re.compile(r"^\s*-{2,}\s*$")
+
+
+def _numpy_attribute_names(doc: str | None) -> frozenset[str]:
+    """Return field names a NumPy ``Attributes`` section of *doc* documents."""
+    if not doc:
+        return frozenset()
+
+    lines = doc.expandtabs().splitlines()
+    names: set[str] = set()
+    index = 0
+    while index + 1 < len(lines):
+        heading = lines[index].strip() == "Attributes"
+        if not (heading and _NUMPY_UNDERLINE.match(lines[index + 1])):
+            index += 1
+            continue
+
+        indent = len(lines[index]) - len(lines[index].lstrip())
+        cursor = index + 2
+        while cursor < len(lines):
+            entry = lines[cursor]
+            if not entry.strip():
+                cursor += 1
+                continue
+            entry_indent = len(entry) - len(entry.lstrip())
+            if entry_indent < indent:
+                break
+            if entry_indent == indent:
+                # The next NumPy section header is underlined; stop before it.
+                if cursor + 1 < len(lines) and _NUMPY_UNDERLINE.match(
+                    lines[cursor + 1]
+                ):
+                    break
+                names.add(entry.split(":", 1)[0].strip())
+            cursor += 1
+        index = cursor
+
+    return frozenset(names)
+
+
+def _skip_documented_namedtuple_fields(
+    app: Sphinx,
+    what: str,
+    name: str,
+    obj: object,
+    skip: bool,
+    options: object,
+) -> bool | None:
+    """Drop NamedTuple field stubs the class docstring already documents.
+
+    ``typing.NamedTuple`` fields are descriptors whose ``__doc__`` is
+    ``"Alias for field number N"``. Autodoc counts that boilerplate as a real
+    docstring, so the field is documented no matter how ``undoc-members`` is
+    set. When the class docstring carries a NumPy ``Attributes`` section, the
+    docstring preprocessor has already emitted an ``.. attribute::`` block for
+    the same dotted name, and the Python domain warns about the duplicate.
+    """
+    if skip or what != "class":
+        return None
+
+    current = app.env.current_document
+    module = sys.modules.get(getattr(current, "autodoc_module", "") or "")
+    owner_name = (getattr(current, "autodoc_class", "") or "").partition(".")[0]
+    owner = getattr(module, owner_name, None)
+
+    fields = getattr(owner, "_fields", None)
+    if not isinstance(fields, tuple) or name not in fields:
+        return None
+
+    return name in _numpy_attribute_names(owner.__doc__)
+
 
 def setup(app: Sphinx) -> None:
     """Configure Sphinx app hooks and register vcspull-specific lexers."""
     _gp_setup(app)
+    app.connect("autodoc-skip-member", _skip_documented_namedtuple_fields)
 
     from vcspull_console_lexer import VcspullConsoleLexer
     from vcspull_output_lexer import VcspullOutputLexer

src/vcspull/cli/__init__.py

@@ -203,11 +203,28 @@ def build_description(
             None,
             [
                 "vcspull add ~/code/mylib",
+                "vcspull add https://github.com/example/mylib.git",
                 "vcspull add ~/src/mylib --workspace ~/code",
-                (
-                    "vcspull add ~/code/mylib "
-                    "--url https://github.com/example/mylib.git --dry-run"
-                ),
+                "vcspull add https://git.example.com/.git --name mylib",
+                ("vcspull add ~/code/mylib --url https://github.com/example/mylib.git"),
+            ],
+        ),
+        (
+            "Pinning",
+            [
+                "vcspull add ~/code/mylib --pin v1.0",
+                "vcspull add git+https://github.com/example/mylib.git@v1.0",
+                "vcspull add ~/code/mylib --shallow",
+                "vcspull add ~/code/mylib --depth 50",
+            ],
+        ),
+        (
+            "Automation",
+            [
+                "vcspull add ~/code/mylib --dry-run",
+                "vcspull add https://github.com/example/mylib.git --yes",
+                "vcspull add ~/code/mylib --file ~/configs/python.yaml",
+                "vcspull add ~/code/mylib --no-merge",
             ],
         ),
     ),