Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CHANGES
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,25 @@ $ pipx install --suffix=@next 'vcspull' --pip-args '\--pre' --force

<!-- Maintainers, insert changes / features for the next release here -->

### Breaking changes

- Rename the import CLI flag `--base-dir-key`/`--dir` and the related internal
argument names to `--workspace-root`, aligning both user-facing options and
implementation terminology with the workspace-root concept (#470).

### Bug fixes

- Normalize workspace roots during imports so equivalent labels (for example
`~/foo`, `~/foo/`, `/home/user/foo`) collapse into a single canonical entry;
avoids duplicate "already added" prompts (#470).
- Have `vcspull fmt` apply the same normalization before formatting and writing
configs, so duplicate workspace-root sections are removed automatically (#470).

### Development

- Expand CLI tests to cover mixed workspace-root scenarios and the formatter’s
normalization behavior (#470).

_Notes on upcoming releases will be added here_

## vcspull v1.36.0 (2025-10-18)
Expand Down
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
- 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.

Expand All @@ -115,7 +115,7 @@ $ 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
`--workspace-root ~/code/` to pin the resulting workspace root or `--config` to
write somewhere other than the default `~/.vcspull.yaml`.

### Normalize configuration files
Expand Down
16 changes: 9 additions & 7 deletions docs/cli/import.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -36,18 +38,18 @@ 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.
- `--yes`/`-y` accepts every suggestion, which is useful for unattended
migrations.

Expand Down
4 changes: 2 additions & 2 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,8 +114,8 @@ 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. 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
Expand Down
4 changes: 2 additions & 2 deletions src/vcspull/cli/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
Loading