]> git.ipfire.org Git - thirdparty/git.git/commit
Update documentation related to sparsity and the skip-worktree bit
authorElijah Newren <newren@gmail.com>
Fri, 14 Jan 2022 15:59:42 +0000 (15:59 +0000)
committerJunio C Hamano <gitster@pobox.com>
Fri, 14 Jan 2022 22:44:07 +0000 (14:44 -0800)
commit9023535bd3953df265f30a3d53b1fda2107bb690
tree0fb14d70bd11928a6c4a253a1def9f959548ebf3
parentaf6a51875a44c0bd16a21329456aadde615a2f46
Update documentation related to sparsity and the skip-worktree bit

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>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/git-read-tree.txt
Documentation/git-sparse-checkout.txt
Documentation/git-update-index.txt