docs(cli[flags]) Use longform flags and split multi-flag commands

why: Shortform flags (-w, -f, -S, -v) are cryptic in user-facing docs;
multi-flag one-liners are hard to scan and copy-paste.
what:
- Replace -w with --workspace in all doc code blocks
- Replace -f with --file in all doc code blocks
- Replace -S with --smart-case and -v with --invert-match in search docs
- Split multi-flag commands onto \-continuation lines
- Update prose references to prefer longform names
- Remove redundant "Short form" examples from fmt.md

Author: tony

CHANGES

@@ -44,23 +44,23 @@ Import a user's repositories:
 
 ```console
 $ vcspull import github torvalds \
-    -w ~/repos/linux \
+    --workspace ~/repos/linux \
     --mode user
 ```
 
 Import an organization's repositories:
 
 ```console
 $ vcspull import github django \
-    -w ~/study/python \
+    --workspace ~/study/python \
     --mode org
 ```
 
 Search and import repositories:
 
 ```console
 $ vcspull import github "machine learning" \
-    -w ~/ml-repos \
+    --workspace ~/ml-repos \
     --mode search \
     --min-stars 1000
 ```
@@ -69,23 +69,23 @@ Use with self-hosted GitLab:
 
 ```console
 $ vcspull import gitlab myuser \
-    -w ~/work \
+    --workspace ~/work \
     --url https://gitlab.company.com
 ```
 
 Import from AWS CodeCommit:
 
 ```console
 $ vcspull import codecommit \
-    -w ~/work/aws \
+    --workspace ~/work/aws \
     --region us-east-1
 ```
 
 Preview without writing (dry run):
 
 ```console
 $ vcspull import codeberg user \
-    -w ~/oss \
+    --workspace ~/oss \
     --dry-run
 ```
 
@@ -107,15 +107,15 @@ SSH (default):
 
 ```console
 $ vcspull import github torvalds \
-    -w ~/repos/linux \
+    --workspace ~/repos/linux \
     --mode user
 ```
 
 Use `--https` for HTTPS clone URLs:
 
 ```console
 $ vcspull import github torvalds \
-    -w ~/repos/linux \
+    --workspace ~/repos/linux \
     --mode user \
     --https
 ```
@@ -127,7 +127,7 @@ under the workspace root by default:
 
 ```console
 $ vcspull import gitlab vcs-python-group-test \
-    -w ~/projects/python \
+    --workspace ~/projects/python \
     --mode org
 ```
 
@@ -142,7 +142,7 @@ workspace root:
 
 ```console
 $ vcspull import gitlab vcs-python-group-test \
-    -w ~/projects/python \
+    --workspace ~/projects/python \
     --mode org \
     --flatten-groups
 ```

README.md

@@ -119,7 +119,7 @@ $ vcspull discover ~/code --recursive
 ```
 
 The scan shows each repository before import unless you opt into `--yes`. Add
-`-w ~/code/` to pin the resulting workspace root or `-f` to write somewhere other
+`--workspace ~/code/` to pin the resulting workspace root or `-f/--file` to write somewhere other
 than the default `~/.vcspull.yaml`. Duplicate workspace roots are merged by
 default; include `--no-merge` to keep them separate while you review the log.
 
@@ -129,11 +129,15 @@ Pull repository lists from GitHub, GitLab, Codeberg, Gitea, Forgejo, or AWS
 CodeCommit directly into your configuration:
 
 ```console
-$ vcspull import github myuser -w ~/code/ --mode user
+$ vcspull import github myuser \
+    --workspace ~/code/ \
+    --mode user
 ```
 
 ```console
-$ vcspull import gitlab my-group -w ~/work/ --mode org
+$ vcspull import gitlab my-group \
+    --workspace ~/work/ \
+    --mode org
 ```
 
 Use `--dry-run` to preview changes, `--https` for HTTPS clone URLs, and
@@ -182,7 +186,9 @@ After importing or editing by hand, run the formatter to tidy up keys, merge
 duplicate workspace sections, and keep entries sorted:
 
 ```console
-$ vcspull fmt -f ~/.vcspull.yaml --write
+$ vcspull fmt \
+    --file ~/.vcspull.yaml \
+    --write
 ```
 
 Use `vcspull fmt --all --write` to format every YAML file that vcspull can
@@ -223,7 +229,7 @@ or svn project with a git dependency:
 Clone / update repos via config file:
 
 ```console
-$ vcspull sync -f external_deps.yaml '*'
+$ vcspull sync --file external_deps.yaml '*'
 ```
 
 See the [Quickstart](https://vcspull.git-pull.com/quickstart.html) for

docs/cli/add.md

@@ -98,7 +98,8 @@ vcspull searches for configuration files in this order:
 Specify a file explicitly with `-f/--file`:
 
 ```console
-$ vcspull add ~/study/python/pytest-docker -f ~/configs/python.yaml
+$ vcspull add ~/study/python/pytest-docker \
+    --file ~/configs/python.yaml
 ```
 
 ## Handling duplicates
@@ -122,7 +123,7 @@ 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 -f ~/.vcspull.yaml
++ $ vcspull add ~/code/flask --url https://github.com/pallets/flask.git --file ~/.vcspull.yaml
 ```
 
 Key differences:

docs/cli/discover.md

@@ -129,7 +129,9 @@ $ vcspull discover ~ --recursive --workspace-root ~/code/ --yes
 Specify a custom config file with `-f/--file`:
 
 ```console
-$ vcspull discover ~/company --recursive -f ~/company/.vcspull.yaml
+$ vcspull discover ~/company \
+    --recursive \
+    --file ~/company/.vcspull.yaml
 ```
 
 If the config file doesn't exist, it will be created.
@@ -195,7 +197,7 @@ Scan to specific config:
 $ vcspull discover ~/company/repos \
     --recursive \
     --yes \
-    -f ~/company/.vcspull.yaml
+    --file ~/company/.vcspull.yaml
 ```
 
 ## After discovering repositories
@@ -229,7 +231,7 @@ If you previously used `vcspull import --scan`:
 
 ```diff
 - $ vcspull import --scan ~/code --recursive -c ~/.vcspull.yaml --yes
-+ $ vcspull discover ~/code --recursive -f ~/.vcspull.yaml --yes
++ $ vcspull discover ~/code --recursive --file ~/.vcspull.yaml --yes
 ```
 
 Changes:
@@ -273,7 +275,7 @@ $ vcspull discover ~/projects --recursive --yes
 ```console
 $ vcspull discover ~/company \
     --recursive \
-    -f ~/company/.vcspull.yaml \
+    --file ~/company/.vcspull.yaml \
     --workspace-root ~/work/ \
     --yes
 ```

docs/cli/fmt.md

@@ -59,22 +59,12 @@ Run the formatter in dry-run mode first to preview the adjustments:
 $ vcspull fmt --file ~/.vcspull.yaml
 ```
 
-Then add `--write` (or `-w`) to persist them back to disk:
+Then add `--write` to persist them back to disk:
 
 ```console
-$ vcspull fmt --file ~/.vcspull.yaml --write
-```
-
-Short form for preview:
-
-```console
-$ vcspull fmt -f ~/.vcspull.yaml
-```
-
-Short form to apply:
-
-```console
-$ vcspull fmt -f ~/.vcspull.yaml -w
+$ vcspull fmt \
+    --file ~/.vcspull.yaml \
+    --write
 ```
 
 Use `--all` to iterate over the default search locations: the current working

docs/cli/import/codeberg.md

@@ -30,5 +30,5 @@ $ export CODEBERG_TOKEN=...
 Then import:
 
 ```console
-$ vcspull import codeberg myuser -w ~/code/
+$ vcspull import codeberg myuser --workspace ~/code/
 ```

docs/cli/import/codecommit.md

@@ -20,7 +20,10 @@ CodeCommit does not require a target argument. Use `--region` and `--profile`
 to select the AWS environment:
 
 ```console
-$ vcspull import codecommit -w ~/code/ --region us-east-1 --profile work
+$ vcspull import codecommit \
+    --workspace ~/code/ \
+    --region us-east-1 \
+    --profile work
 ```
 
 ## Authentication
@@ -41,5 +44,7 @@ $ aws configure
 Then import:
 
 ```console
-$ vcspull import codecommit -w ~/code/ --region us-east-1
+$ vcspull import codecommit \
+    --workspace ~/code/ \
+    --region us-east-1
 ```

docs/cli/import/forgejo.md

@@ -31,5 +31,7 @@ $ export FORGEJO_TOKEN=...
 Then import:
 
 ```console
-$ vcspull import forgejo myuser -w ~/code/ --url https://forgejo.example.com
+$ vcspull import forgejo myuser \
+    --workspace ~/code/ \
+    --url https://forgejo.example.com
 ```

docs/cli/import/gitea.md

@@ -30,5 +30,7 @@ $ export GITEA_TOKEN=...
 Then import:
 
 ```console
-$ vcspull import gitea myuser -w ~/code/ --url https://git.example.com
+$ vcspull import gitea myuser \
+    --workspace ~/code/ \
+    --url https://git.example.com
 ```

docs/cli/import/github.md

@@ -34,5 +34,5 @@ $ export GITHUB_TOKEN=ghp_...
 Then import:
 
 ```console
-$ vcspull import gh myuser -w ~/code/
+$ vcspull import gh myuser --workspace ~/code/
 ```