skip to content

In DVC, the lab ran `dvc gc --workspace` to free disk space — why can last spring's tagged photo set no longer be checked out, and which flags would have kept it?

level: seniorimportance: should knowfreq 8%

answer

  1. keeps only what the scope names
  2. no scope flag means it refuses
  3. workspace scope drops older versions
  4. branches, tags, all commits, experiments
  5. dry run first; shared caches

basics

~20 s

dvc gc deletes every cached object its scope does not reference; --workspace keeps only what the current pointers name, so older tagged versions vanish unless another copy exists. Scope it with --all-tags, --all-branches or --all-commits, and preview with --dry.

solid answer

~40 s

`dvc gc` reads the DVC files in the commits its scope names and deletes every other object from the cache. It refuses to run without a scope: one of `-w/--workspace`, `-a/--all-branches`, `-T/--all-tags`, `-A/--all-commits`, `--all-experiments`, `--rev` or `--date` must be given. `--workspace` keeps only what the current `.dvc` files and `dvc.lock` reference, so the objects behind last spring's tag were deleted and `dvc checkout` of that tag now reports them missing; they come back only from remote storage or another copy. Scope it to what you mean to keep — `-T` keeps every tag, `-a` every branch tip, `-A` all history — add `--all-experiments` if experiments matter, and run `--dry` first. On a cache shared between projects, name the others with `--projects`, and never add `--cloud` casually: it deletes from remote storage too, irreversibly.

code

bash · 5 lines
bash
dvc gc --all-branches --all-tags --dry   # list what would be removed
dvc gc --all-branches --all-tags --force # remove it without the prompt

# Cache shared with two other projects
dvc gc --all-branches --all-tags --projects ../trap-labels ../trap-detector --dry

go deeper

for a junior

Recall that dvc gc frees disk by deleting cached data, and that it keeps only what its scope flags name.

for a middle

Explain each scope option, why a bare dvc gc refuses to run, and why --workspace alone deletes older versions.

for a senior

Show a safe procedure: a dry run, a scope matched to what must stay restorable, and the extra care a shared cache or --cloud demands.

for a principal

Own the retention policy behind it: which tagged releases must stay restorable, where the durable copy lives, and who may run destructive collections.

## What `dvc gc` decides DVC's **cache** (`.dvc/cache` by default) keeps every version of every tracked file that was ever added on this machine. A two-terabyte camera-trap folder that changed a few times can fill a disk quickly, and `dvc gc` (garbage collection) is the command that reclaims it. It works by **keeping, not deleting, what you name**: it reads the DVC files (`.dvc` pointers and `dvc.lock`) in the set of commits its scope options describe, collects every hash they reference, and deletes every other object. Anything you did not name is garbage. To stop an accidental run from deleting history, `dvc gc` does nothing without a scope. Run bare, it fails with an error asking for one of `-w|--workspace`, `-a|--all-branches`, `-T|--all-tags`, `--all-experiments`, `--all-commits`, `--date` or `--rev`. Unless `-f` / `--force` or `--dry` is given, it also prints what it will keep and asks for confirmation. ## The scope options | Option | Keeps objects referenced by | |---|---| | `-w`, `--workspace` | The current workspace's DVC files only | | `-a`, `--all-branches` | The tip of every Git branch, plus the workspace | | `-T`, `--all-tags` | Every Git tag, plus the workspace | | `-A`, `--all-commits` | Every commit in history (not experiments), plus the workspace | | `--all-experiments` | All DVC experiments, plus the workspace | | `--rev <commit>`, optionally with `-n <num>` | That commit, or the last `num` commits from it, plus the workspace | Every option implies `--workspace`, and they combine: `-aT` keeps branch tips and tags; `-a -n 3` keeps the last three commits on each branch. ## Why spring's tag broke The lab ran `dvc gc --workspace`. The workspace's pointer names this month's photo set, so every object referenced **only** by older commits — including photos that were replaced or removed since spring — was deleted. Git still has the spring tag and its `data/camera-traps.dvc`, so the pointer looks fine, but `dvc checkout` now warns that the objects are missing. Those objects can be fetched back only if they were uploaded to remote storage before the collection; otherwise that version of the dataset is gone from this machine. What the lab should have run: 1. `dvc gc -T --dry` (or `-aT`, or `-A`) to see what would go while keeping every tagged release. 2. The same command without `--dry` once the list looks right. 3. `--all-experiments` added if DVC experiments hold data worth keeping. ## A safe routine 1. Tag every dataset version that must stay restorable, so `-T` can protect it. 2. Run the collection with `--dry` and read the list; the confirmation line names the scope, for example "This will remove all cache except items used in the workspace and all git tags of the current repo." 3. Run it for real, with `-f` only in scripts that have already passed a dry run. 4. In a scratch clone that uses the same cache, check out one old tag and run `dvc checkout` to prove the release still restores. 5. Record the scope used and the date, so the next person knows which versions this machine can still rebuild. ## Two ways to make it worse - **A shared cache.** When several projects point their cache at one shared directory, `dvc gc` in one project knows only that project's commits and deletes objects the others still need. Pass the other projects' paths with `-p` / `--projects` — after making sure every branch and commit they need is present in those clones. - **`-c` / `--cloud`.** It deletes unused objects from the remote storage as well as the local cache, and the DVC docs warn that cloud deletion is irreversible unless another remote or backup holds the data. A scope mistake with `--cloud` destroys the last copy. ## Mistakes interviewers listen for - "`dvc gc` cleans whatever is unused" — unused *relative to the scope you name*, and with no scope it does nothing. - Believing `--workspace` keeps history; it keeps only the current version. - Reading `--all-branches` as all commits on all branches; it keeps branch tips unless `-n` is given. - Running it on a shared cache as if it were private. - Assuming anything collected can be fetched again; that holds only for data already uploaded, and never after `--cloud`.

  • Is `dvc gc --all-commits` always safe?
    It keeps everything any commit references, but not DVC experiments, so add `--all-experiments` if they matter. It also deletes data that was cached but never committed, such as outputs from runs made without committing. On a shared cache it still needs `--projects`.
  • How do you see what `dvc gc` would delete before it deletes anything?
    Add `--dry`: it prints what would be removed without removing it and skips the confirmation prompt. Comparing that list with what the lab expects to keep is the cheapest guard against a wrong scope.

  • dvc gc with no flags cleans up whatever is unused.
  • dvc gc --workspace keeps every version in Git history.
  • --all-branches keeps every commit on every branch.
  • On a shared cache, dvc gc only affects the current project.
  • Anything dvc gc removes can always be fetched again.