Re: [PATCH v2 4/5] Update documentation related to sparsity and the skip-worktree bit

> From: Elijah Newren <newren@gmail.com>
>
> Make several small updates, to address a few documentation issues
> I spotted:
>   * sparse-checkout focused on "patterns" even though the inputs (and
>     outputs in the case of `list`) are directories in cone-mode
>   * The description section of the sparse-checkout documentation
>     was a bit sparse (no pun intended), and focused more on internal
>     mechanics rather than end user usage.  This made sense in the
>     early days when the command was even more experimental, but let's
>     adjust a bit to try to make it more approachable to end users who
>     may want to consider using it.  Keep the scary backward
>     compatibility warning, though; we're still hard at work trying to
>     fix up commands to behave reasonably in sparse checkouts.
>   * both read-tree and update-index tried to describe how to use the
>     skip-worktree bit, but both predated the sparse-checkout command.
>     The sparse-checkout command is a far easier mechanism to use and
>     for users trying to reduce the size of their working tree, we
>     should recommend users to look at it instead.
>   * The update-index documentation pointed out that assume-unchanged
>     and skip-worktree sounded similar but had different purposes.
>     However, it made no attempt to explain the differences, only to
>     point out that they were different.  Explain the differences.
>   * The update-index documentation focused much more on (internal?)
>     implementation details than on end-user usage.  Try to explain
>     its purpose better for users of update-index, rather than
>     fellow developers trying to work with the SKIP_WORKTREE bit.
>   * Clarify that when core.sparseCheckout=true, we treat a file's
>     presence in the working tree as being an override to the
>     SKIP_WORKTREE bit (i.e. in sparse checkouts when the file is
>     present we ignore the SKIP_WORKTREE bit).
>
> Note that this commit, like many touching documentation, is best viewed
> with the `--color-words` option to diff/log.
>
> Signed-off-by: Elijah Newren <newren@gmail.com>
> ---
>  Documentation/git-read-tree.txt       | 12 +++--
>  Documentation/git-sparse-checkout.txt | 76 ++++++++++++++++-----------
>  Documentation/git-update-index.txt    | 57 +++++++++++++++-----
>  3 files changed, 98 insertions(+), 47 deletions(-)
>
> diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt
> index 8c3aceb8324..99bb387134d 100644
> --- a/Documentation/git-read-tree.txt
> +++ b/Documentation/git-read-tree.txt
> @@ -375,9 +375,14 @@ have finished your work-in-progress), attempt the merge again.
>  SPARSE CHECKOUT
>  ---------------
>  
> +Note: The `update-index` and `read-tree` primitives for supporting the
> +skip-worktree bit predated the introduction of
> +linkgit:git-sparse-checkout[1].  Users are encouraged to use
> +`sparse-checkout` in preference to these low-level primitives.

> -Initialize and modify the sparse-checkout configuration, which reduces
> -the checkout to a set of paths given by a list of patterns.
> +This command is used to create sparse checkouts, which means that it
> +changes the working tree from having all tracked files present, to only
> +have a subset of them.  It can also switch which subset of files are
> +present, or undo and go back to having all tracked files present in the
> +working copy.