Sparse clones

Check out only part of a monorepo, Perforce-style, with `oak clone --path`.

Markdown

All pages

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#

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#

FlagEffect
oak clone --shallowOnly the newest commit on main (or on --branch NAME), no history.
oak clone --from ../other-checkoutReuse content already in another local checkout of the same repo instead of downloading it again.
oak clone --detachedCheck 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.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].