From patchwork Thu Jul  6 19:36:32 2017
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: [06,of,13,sparse,V2] sparse: document config file format
From: Gregory Szorc <gregory.szorc@gmail.com>
X-Patchwork-Id: 22035
Message-Id: <9d59302d25b9d53a8e72.1499369792@ubuntu-vm-main>
To: mercurial-devel@mercurial-scm.org
Date: Thu, 06 Jul 2017 12:36:32 -0700

# HG changeset patch
# User Gregory Szorc <gregory.szorc@gmail.com>
# Date 1499363846 25200
#      Thu Jul 06 10:57:26 2017 -0700
# Node ID 9d59302d25b9d53a8e72fbd110fb12d4aa52cf3f
# Parent  a772c2781b074d61f518ccf415291ab2091b0048
sparse: document config file format

This was previously undocumented. Seems useful to have.

diff --git a/hgext/sparse.py b/hgext/sparse.py
--- a/hgext/sparse.py
+++ b/hgext/sparse.py
@@ -17,6 +17,59 @@ directories to be explicitly included or
 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