(This extension is not yet protected by backwards compatibility guarantees. Any aspect may break in future releases until this notice is removed.)

This extension allows the working directory to only consist of a subset of files for the revision. This allows specific files or directories to be explicitly included or excluded. Many repository operations have performance proportional to the number of files in the working directory. So only realizing a subset of files in the working directory can improve performance.

Sparse Config Files

The set of files that are part of a sparse checkout are defined by a sparse config file. The file defines 3 things: includes (files to include in the sparse checkout), excludes (files to exclude from the sparse checkout), and profiles (links to other config files).

The file format is newline delimited. Empty lines and lines beginning with # are ignored.

Lines beginning with %include `` denote another sparse config file to include. e.g. ``%include tests.sparse. The filename is relative to the repository root.

The special lines [include] and [exclude] denote the section for includes and excludes that follow, respectively. It is illegal to have [include] after [exclude].

Non-special lines resemble file patterns to be added to either includes or excludes. The syntax of these lines is documented by hg help patterns. Patterns are interpreted as glob: by default and match against the root of the repository.

Exclusion patterns take precedence over inclusion patterns. So even if a file is explicitly included, an [exclude] entry can remove it.

For example, say you have a repository with 3 directories, frontend/, backend/, and tools/. frontend/ and backend/ correspond to different projects and it is uncommon for someone working on one to need the files for the other. But tools/ contains files shared between both projects. Your sparse config files may resemble:

# frontend.sparse

# backend.sparse

Say the backend grows in size. Or there's a directory with thousands of files you wish to exclude. You can modify the profile to exclude certain files: