git-sparse-checkout.txt: add a new EXAMPLES section

Since many users like to learn from examples, provide a section in the
manual with example commands that would be used and a brief explanation
of what each does.

Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-sparse-checkout.txt b/Documentation/git-sparse-checkout.txt
index 2083e6df356ef5ad1b5705f6557e4e4c7c3e56f7..c54437428bbcf39d9e975b8af044aef08000299b 100644 (file)
--- a/Documentation/git-sparse-checkout.txt
+++ b/Documentation/git-sparse-checkout.txt
@@ -136,6 +136,43 @@ paths to pass to a subsequent 'set' or 'add' command.  However,
 the disable command, so the easy restore of calling a plain `init`
 decreased in utility.
 
+EXAMPLES
+--------
+`git sparse-checkout set MY/DIR1 SUB/DIR2`::
+
+       Change to a sparse checkout with all files (at any depth) under
+       MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all
+       files immediately under MY/ and SUB/ and the toplevel
+       directory).  If already in a sparse checkout, change which files
+       are present in the working copy to this new selection.  Note
+       that this command will also delete all ignored files in any
+       directory that no longer has either tracked or
+       non-ignored-untracked files present.
+
+`git sparse-checkout disable`::
+
+       Repopulate the working directory with all files, disabling sparse
+       checkouts.
+
+`git sparse-checkout add SOME/DIR/ECTORY`::
+
+       Add all files under SOME/DIR/ECTORY/ (at any depth) to the
+       sparse checkout, as well as all files immediately under
+       SOME/DIR/ and immediately under SOME/.  Must already be in a
+       sparse checkout before using this command.
+
+`git sparse-checkout reapply`::
+
+       It is possible for commands to update the working tree in a
+       way that does not respect the selected sparsity directories.
+       This can come from tools external to Git writing files, or
+       even affect Git commands because of either special cases (such
+       as hitting conflicts when merging/rebasing), or because some
+       commands didn't fully support sparse checkouts (e.g. the old
+       `recursive` merge backend had only limited support).  This
+       command reapplies the existing sparse directory specifications
+       to make the working directory match.
+
 INTERNALS -- SPARSE CHECKOUT
 ----------------------------
 
@@ -154,12 +191,6 @@ directory, it updates the skip-worktree bits in the index based
 on this file. The files matching the patterns in the file will
 appear in the working directory, and the rest will not.
 
-To enable the sparse-checkout feature, run `git sparse-checkout set` to
-set the patterns you want to use.
-
-To repopulate the working directory with all files, use the
-`git sparse-checkout disable` command.
-
 
 INTERNALS -- CONE PATTERN SET
 -----------------------------