A sparse clone checks out only part of a repository — Perforce-style. Pass one or more directories, and only those come down:
oak clone acme/monorepo --path services/api --path libs/shared
# or: --path services/api,libs/shared
Large repositories#
Without --path, a repository of 100,000 files or more is cloned with only its top-level files checked out, and oak clone lists its top-level directories. Add the ones you work on with oak sparse add. To check out everything anyway, clone with --path /. (OAK_PATH_CHECKOUT_MIN_FILES changes the threshold.)
oak clone acme/monorepo # top-level files only
cd monorepo
oak sparse add services/api # brings in services/api
oak status and oak commit read only what's checked out, so they stay quick however big the repository is.
How it behaves#
- Other directories aren't there at all. The server sends each commit rebuilt over just those directories (a view), so the rest are left out of the tree, not only out of your disk.
AGENTS.mdandCLAUDE.mdin the directories on the way down are kept. - Your commits leave the rest alone. When you push, the server puts your changes back into the full tree; everything outside your directories stays as it was.
- Everything else is normal. Commit, push, pull, and merge work exactly as in a full clone.
Change the directories#
oak sparse # show the directories you have (--json for machines)
oak sparse add docs/ # add one
oak sparse remove docs/ # drop one
oak sparse set services/web # exactly these
A change fetches the checkout again for the new set of directories, at the same history depth, so it needs a clean working tree and nothing unpushed: commit and push first. Directories you already have aren't sent again (the new checkout copies them from the old one), and files already on disk are left as they are. oak sparse disable is refused; clone again with --path / for a full checkout.
Sparse clones and path rules#
Sparse clones and path rules share a mechanism: a directory you can't read is left out of your tree the same way. The difference is who decides — a sparse clone is a choice you make; path rules are access control set by the repo's admins.
Other ways to clone less#
| Flag | Effect |
|---|---|
oak clone --shallow | Only the newest commit on main (or on --branch NAME), 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.