Skip to content

Commit 692ee06

Browse files
committed
docs(import[prune-untracked]) Add --prune-untracked section and expand flags table
why: The --prune-untracked flag implementation is complete but the import docs didn't document it yet. what: - Add "Pruning untracked entries" section between stale pruning and pin docs - Expand the flags table with a "Prune untracked" column and two new rows - Document safety rails, dry-run preview, and --sync/--prune requirement
1 parent f7c60c3 commit 692ee06

File tree

1 file changed

+46
-6
lines changed

1 file changed

+46
-6
lines changed

docs/cli/import/index.md

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -322,12 +322,52 @@ $ vcspull import gh myorg \
322322
`--sync` and `--prune` can be combined — `--sync` alone already includes
323323
pruning, so `--sync --prune` behaves identically to `--sync`.
324324

325-
| Flags | Add new | Update URLs | Prune stale |
326-
|-------|---------|-------------|-------------|
327-
| (none) | yes | no | no |
328-
| `--sync` | yes | yes | yes |
329-
| `--prune` | yes | no | yes |
330-
| `--sync --prune` | yes | yes | yes |
325+
| Flags | Add new | Update URLs | Prune stale | Prune untracked |
326+
|-------|---------|-------------|-------------|-----------------|
327+
| (none) | yes | no | no | no |
328+
| `--sync` | yes | yes | yes | no |
329+
| `--prune` | yes | no | yes | no |
330+
| `--sync --prune` | yes | yes | yes | no |
331+
| `--sync --prune-untracked` | yes | yes | yes | yes |
332+
| `--prune --prune-untracked` | yes | no | yes | yes |
333+
334+
### Pruning untracked entries
335+
336+
Standard `--sync` / `--prune` only removes entries tagged with the current
337+
import source. Manually added repos — entries without any
338+
`metadata.imported_from` tag — are left untouched. To also remove these
339+
"untracked" entries, add `--prune-untracked`:
340+
341+
```console
342+
$ vcspull import gh myorg \
343+
--mode org \
344+
--workspace ~/code/ \
345+
--sync \
346+
--prune-untracked
347+
```
348+
349+
`--prune-untracked` requires `--sync` or `--prune` — it cannot be used alone.
350+
351+
Safety rails:
352+
353+
- **Pinned entries** are always preserved (regardless of provenance)
354+
- **Entries tagged from a different source** (e.g. `"gitlab:other"`) are
355+
preserved — they are "tracked" by that other import
356+
- **Only workspaces the import targets** are scanned — entries in other
357+
workspaces are untouched
358+
- A **confirmation prompt** lists exactly what would be removed before
359+
proceeding (use `--yes` to skip, `--dry-run` to preview)
360+
361+
Preview with dry-run:
362+
363+
```console
364+
$ vcspull import gh myorg \
365+
--mode org \
366+
--workspace ~/code/ \
367+
--prune \
368+
--prune-untracked \
369+
--dry-run
370+
```
331371

332372
### Pin-aware behavior
333373

0 commit comments

Comments
 (0)