# Sparse clones

A **sparse clone** checks out only part of a repository — Perforce-style. Pass one or more path prefixes, and only files under them are downloaded and written to disk:

```bash
oak clone acme/monorepo --path services/api --path libs/shared
# or: --path services/api,libs/shared
```

The set of prefixes is the **cone**.

## How it behaves

- **The directory structure still comes down.** Oak's trees are content-addressed and verified on the client, so the full listing arrives; files outside the cone are listed but their content is never fetched.
- **Commits carry out-of-cone files forward untouched.** Narrowing a checkout never deletes what it leaves out, and `oak status` never reports those files as missing.
- **Everything else is normal.** Commit, push, pull, and merge work exactly as in a full clone — including `oak merge`, which a [mount](/docs/mounts) can't do.

## Change the cone

```bash
oak sparse                       # show the current cone (--json for machines)
oak sparse set services/web      # replace the cone and re-sync the working tree
oak sparse add docs/             # widen it
oak sparse disable               # back to a full checkout
```

After widening, files that were never downloaded are listed; run `oak pull` to fetch them.

## Sparse clone or mount?

For a very large repo, a [lazy mount](/docs/mounts) is usually the better default: it fetches any path on demand, with no cone to manage. Reach for a sparse clone when you want a plain on-disk checkout of a subtree — for builds, for tools that dislike virtual filesystems, for merging from — without the per-machine setup a mount needs.

Sparse clones and [path permissions](/docs/path-permissions) share a mechanism: both withhold file content while keeping the tree intact. The difference is who decides — a sparse clone is a bandwidth choice you make; path permissions are access control set by the repo's admins.

## Other ways to clone less

| Flag | Effect |
|---|---|
| `oak clone --shallow` | Only the latest commit on `main`, no history. |
| `oak clone --from ../other-checkout` | Reuse content already in another local checkout of the same repo instead of downloading it again. |
| `oak clone --detached` | Check out `main`'s head without creating a personal branch — for read-only tooling. |

## Recovery switch

If a server is ever in a broken state and a normal clone or pull fails on a missing file, `OAK_ALLOW_PARTIAL_CLONE=1` skips each missing file (and reports it) instead of failing. It's for recovery only — use `--path` when you want part of a repo on purpose.