cli(import): standardize workspace root terminology

Author: tony

CHANGES

@@ -28,11 +28,11 @@ _Notes on upcoming releases will be added here_
 #### New command: `vcspull import` (#465)
 
 - **Manual import**: Register a single repository with `vcspull import <name> <url>`
-  - Optional `--dir`/`--path` helpers for base-directory detection
+  - Optional `--workspace-root`/`--path` helpers for workspace-root detection (with legacy `--dir` alias)
 - **Filesystem scan**: Discover and import existing repositories with `vcspull import --scan <dir>`
   - Recursively scan with `--recursive`/`-r`
   - Interactive confirmation prompt or `--yes` for unattended runs
-  - Custom base directory with `--base-dir-key`
+  - Custom workspace root with `--workspace-root` (legacy `--dir`/`--base-dir-key` aliases)
 
 #### New command: `vcspull fmt` (#465)
 

README.md

@@ -100,8 +100,8 @@ $ vcspull import my-lib https://github.com/example/my-lib.git --path ~/code/my-l
 ```
 
 - Omit `--path` to default the entry under `./`.
-- Use `--dir` when you want to force a specific base-directory key, e.g.
-  `--dir ~/projects/libs`.
+- Use `--workspace-root` when you want to force a specific workspace root, e.g.
+  `--workspace-root ~/projects/libs` (the legacy `--dir` alias still works).
 - Pass `-c/--config` to import into an alternate YAML file.
 - Follow with `vcspull sync my-lib` to clone or update the working tree after registration.
 
@@ -115,8 +115,9 @@ $ vcspull import --scan ~/code --recursive
 ```
 
 The scan shows each repository before import unless you opt into `--yes`. Add
-`--base-dir-key ~/code/` to pin the resulting section name or `--config` to
-write somewhere other than the default `~/.vcspull.yaml`.
+`--workspace-root ~/code/` to pin the resulting workspace root or `--config` to
+write somewhere other than the default `~/.vcspull.yaml` (aliases `--dir` and
+`--base-dir-key` remain available for compatibility).
 
 ### Normalize configuration files
 

docs/cli/import.md

@@ -21,11 +21,13 @@ directories for Git repositories that already live on disk.
 
 Provide a repository name and remote URL to append an entry to your
 configuration. Use `--path` when you already have a working tree on disk so the
-configured base directory matches its location. Override the inferred base
-directory with `--dir` when you need a specific configuration key.
+inferred workspace root matches its location. Override the detected workspace
+root with `--workspace-root` when you need to target a specific directory.
 
 ```console
 $ vcspull import my-lib https://github.com/example/my-lib.git --path ~/code/my-lib
+$ vcspull import another-lib https://github.com/example/another-lib.git \
+    --workspace-root ~/code
 ```
 
 With no `-c/--config` flag vcspull looks for the first YAML configuration file
@@ -36,18 +38,19 @@ new `.vcspull.yaml` is created next to where you run the command.
 
 `vcspull import --scan` discovers Git repositories that already exist on disk
 and writes them to your configuration. The command prompts before adding each
-repository, showing the inferred name, directory key, and origin URL (when
+repository, showing the inferred name, workspace root, and origin URL (when
 available).
 
 ```console
 $ vcspull import --scan ~/code --recursive
-? Add ~/code/vcspull (dir: ~/code/)? [y/N]: y
-? Add ~/code/libvcs (dir: ~/code/)? [y/N]: y
+? Add ~/code/vcspull (workspace root: ~/code/)? [y/N]: y
+? Add ~/code/libvcs (workspace root: ~/code/)? [y/N]: y
 ```
 
 - `--recursive`/`-r` searches nested directories.
-- `--base-dir-key` forces all discovered repositories to use the same base
-  directory key, overriding the automatically expanded directory.
+- `--workspace-root` forces all discovered repositories to use the same
+  workspace root, overriding the directory inferred from their location (the
+  legacy `--dir` and `--base-dir-key` aliases still work).
 - `--yes`/`-y` accepts every suggestion, which is useful for unattended
   migrations.
 

docs/quickstart.md

@@ -114,8 +114,9 @@ YAML? Create a `~/.vcspull.yaml` file:
 Already have repositories cloned locally? Use
 `vcspull import --scan ~/code --recursive` to detect existing Git checkouts and
 append them to your configuration. See {ref}`cli-import` for more details and
-options such as `--base-dir-key` and `--yes` for unattended runs. After editing
-or importing, run `vcspull fmt --write` (documented in {ref}`cli-fmt`) to
+options such as `--workspace-root` and `--yes` for unattended runs (the legacy
+`--dir` and `--base-dir-key` aliases continue to work). After editing or
+importing, run `vcspull fmt --write` (documented in {ref}`cli-fmt`) to
 normalize keys and keep your configuration tidy.
 
 The `git+` in front of the repository URL. Mercurial repositories use

src/vcspull/cli/__init__.py

@@ -132,7 +132,7 @@ def cli(_args: list[str] | None = None) -> None:
                 scan_dir_str=args.scan_dir,
                 config_file_path_str=args.config,
                 recursive=args.recursive,
-                base_dir_key_arg=args.base_dir_key,
+                workspace_root_override=args.workspace_root_path,
                 yes=args.yes,
             )
         elif args.name and args.url:
@@ -142,7 +142,7 @@ def cli(_args: list[str] | None = None) -> None:
                 url=args.url,
                 config_file_path_str=args.config,
                 path=args.path,
-                base_dir=args.base_dir,
+                workspace_root_path=args.workspace_root_path,
             )
         else:
             # Error: need either name+url or --scan