diff hgext/sparse.py @ 33294:a5921ad2eb99

sparse: document config file format

This was previously undocumented. Seems useful to have.

--- a/hgext/sparse.py	Sat Jul 01 10:29:27 2017 -0700
+++ b/hgext/sparse.py	Thu Jul 06 10:57:26 2017 -0700
@@ -17,6 +17,59 @@
 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]``. If no sections are defined,
+entries are assumed to be in the ``[include]`` section.
+
+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
+  frontend/**
+  tools/**
+
+  # backend.sparse
+  backend/**
+  tools/**
+
+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::
+
+  [include]
+  backend/**
+  tools/**
+
+  [exclude]
+  tools/tests/**
 """
 
 from __future__ import absolute_import