skip to content

In DVC, after `git checkout` of last spring's tag, why are the workspace photos still this month's, and what restores the spring version?

level: middleimportance: must knowfreq 18%

answer

  1. Git only swapped the pointer
  2. the photos are Git-ignored
  3. rebuild the workspace from the cache
  4. dvc checkout, and when it refuses
  5. a post-checkout hook automates it

basics

~20 s

git checkout only swaps the small .dvc pointer files; Git never tracked the photos. Running dvc checkout reads the restored pointers and rebuilds the workspace from the local cache, and dvc install adds a Git hook that runs it after every git checkout.

solid answer

~40 s

Git changed `data/camera-traps.dvc` back to spring's hash, but the photos are Git-ignored, so Git left them alone and the workspace now disagrees with the pointer. `dvc checkout` compares each pointer's hashes with the workspace, restores missing or differing files from the cache using the configured link type, and removes tracked files the spring version does not contain. It can only restore versions whose objects are in the local cache: missing ones are reported with a warning and have to be brought in from remote storage first. Before deleting workspace content that was never saved to the cache, it stops and asks for `--force`. `dvc install` adds a `post-checkout` Git hook so the checkout happens on its own.

code

bash · 9 lines
bash
git checkout spring-2026
dvc checkout --summary

# Or restore only the dataset, keeping today's code
git checkout spring-2026 -- data/camera-traps.dvc
dvc checkout data/camera-traps.dvc

# Let Git run dvc checkout after every git checkout
dvc install

go deeper

for a junior

Recall that switching versions takes two steps, git checkout for the pointers and dvc checkout for the data, and that skipping the second leaves stale files.

for a middle

Explain how dvc checkout compares pointer hashes with the workspace, restores from the local cache, removes extra tracked files, and what the post-checkout hook automates.

for a senior

Show the failure modes: objects missing from the cache, unsaved edits that block the checkout, and a training job that silently read the wrong version because nobody ran the second checkout.

for a principal

Argue for or against installing the hooks across a team: consistency on every branch switch versus long silent restores on large datasets and surprise hook conflicts.

## Two version-control systems, two checkouts A DVC project is an ordinary Git repository with one extra rule: large data is **not** in Git. After `dvc add data/camera-traps`, Git tracks only the small pointer file `data/camera-traps.dvc` and an entry in `data/.gitignore`; the photos live in DVC's local **cache** (`.dvc/cache`) and are linked or copied into the **workspace**, the directory you work in. So when a data scientist runs `git checkout spring-2026` to rebuild last spring's model: - Git rewrites every tracked file to its spring state, including `data/camera-traps.dvc`, which now names spring's directory hash. - Git does nothing to `data/camera-traps/` itself, because it is ignored. The workspace still holds this month's 1.4 million photos. - The project is now inconsistent: the pointer says one version, the files on disk are another. `dvc status` would report the directory as modified. Training at this point silently uses the wrong data — the classic failure this question probes. ## What `dvc checkout` does `dvc checkout` is the second half of switching versions. Run with no targets, it: 1. Reads every `.dvc` file and `dvc.lock` in the project and compares their recorded hashes with what is in the workspace (much like `dvc status`). 2. Restores missing or differing files and directories **from the local cache**, using the link type set by `cache.type` (by default a reflink where the file system supports one, otherwise a copy). 3. Removes tracked files that do not match the pointers — for example photos added to the folder after spring. 4. Prints each path it changed with a marker such as `M` for modified, or a short summary with `--summary`. 5. Restores execute permissions recorded in the pointer (`isexec`), so scripts tracked by DVC stay runnable. Targets narrow the work: `dvc checkout data/camera-traps.dvc` restores just that dataset, and a path inside a tracked directory restores a single photo. A common pattern for pulling back one old dataset while keeping current code is `git checkout spring-2026 -- data/camera-traps.dvc` followed by `dvc checkout data/camera-traps.dvc`. ## When it cannot finish | Situation | What `dvc checkout` does | What to do | |---|---|---| | Spring's objects are not in the local cache (fresh clone, or removed by garbage collection) | Warns that files are missing and lists partial progress | Bring them in from remote storage, or regenerate them; `--allow-missing` lets the command succeed meanwhile | | A workspace file holds edits that were never saved to the cache | Stops and asks for confirmation before discarding them | Save them first, or pass `-f` / `--force` to discard | | You changed `cache.type` and want every file relinked | Leaves already-correct files alone | Run `dvc checkout --relink` | The first row matters most: `dvc checkout` does not download missing data. It works from what is already cached on this machine. ## Automating the second step Remembering to run two checkouts is error-prone, so DVC ships Git hooks: - `dvc install` installs a **`post-checkout`** hook that runs `dvc checkout` after every `git checkout`. - The same command adds a `pre-commit` hook that runs `dvc status` before `git commit`, and a `pre-push` hook for uploading data before `git push`. - The hooks stay inactive on a commit that has no `.dvc/` directory, and `dvc install` refuses to overwrite a hook that already exists. With the hook in place, `git checkout spring-2026` leaves the workspace consistent on its own — provided spring's objects are still cached. ## A habit that catches the silent case File names in a photo folder rarely change between versions; contents do. A workspace that looks right to `ls` can still hold the wrong version, so before a training run that must reproduce a past result: - run `dvc status` — if it prints `Data and pipelines are up to date.`, the workspace matches the checked-out pointers; - otherwise run `dvc checkout`, then check again. ## Mistakes interviewers listen for - Assuming `git checkout` restores the data along with the code. - Expecting `dvc checkout` to fetch missing versions from remote storage; it only reads the local cache. - Believing `dvc checkout` only adds files. It also removes tracked files that the checked-out pointers do not list. - Forgetting that the pointer, not the folder on disk, is the record of which data a commit used.

  • `dvc checkout` warns that spring's photos are missing. What happened, and what fixes it?
    Their objects are not in the local cache — typical of a fresh clone, or after garbage collection removed them. `dvc checkout` never downloads, so the objects have to be fetched from remote storage (or the data regenerated) and then checked out. `--allow-missing` lets the command succeed in the meantime.
  • Why can a workspace look right to `ls` but still be the wrong version, and how do you check?
    File names in a tracked directory rarely change between versions; contents do. Only the hashes tell, so run `dvc status`: if the workspace disagrees with the checked-out pointers, the directory is listed as modified. `dvc data status --granular` narrows it to individual files inside the directory.
  • How do you restore only last spring's photo set while keeping current code?
    Check out just the pointer from the tag — `git checkout spring-2026 -- data/camera-traps.dvc` — and then run `dvc checkout data/camera-traps.dvc`. Only that dataset is rebuilt from the cache; the rest of the workspace stays on the current commit.

  • git checkout restores DVC-tracked data along with the code.
  • dvc checkout downloads missing versions from remote storage on its own.
  • dvc checkout only adds files and never removes workspace data.
  • The folder on disk, not the .dvc file, records which data a commit used.
  • dvc checkout --relink is needed after every git checkout.