summaryrefslogtreecommitdiff
path: root/Documentation/git-update-index.txt
diff options
context:
space:
mode:
authorElijah Newren <newren@gmail.com>2022-01-14 15:59:42 (GMT)
committerJunio C Hamano <gitster@pobox.com>2022-01-14 22:44:07 (GMT)
commit9023535bd3953df265f30a3d53b1fda2107bb690 (patch)
tree0fb14d70bd11928a6c4a253a1def9f959548ebf3 /Documentation/git-update-index.txt
parentaf6a51875a44c0bd16a21329456aadde615a2f46 (diff)
downloadgit-9023535bd3953df265f30a3d53b1fda2107bb690.zip
git-9023535bd3953df265f30a3d53b1fda2107bb690.tar.gz
git-9023535bd3953df265f30a3d53b1fda2107bb690.tar.bz2
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>
Diffstat (limited to 'Documentation/git-update-index.txt')
-rw-r--r--Documentation/git-update-index.txt57
1 files changed, 43 insertions, 14 deletions
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 2853f16..568dbfe 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -351,6 +351,10 @@ unchanged". Note that "assume unchanged" bit is *not* set if
the index (use `git update-index --really-refresh` if you want
to mark them as "assume unchanged").
+Sometimes users confuse the assume-unchanged bit with the
+skip-worktree bit. See the final paragraph in the "Skip-worktree bit"
+section below for an explanation of the differences.
+
EXAMPLES
--------
@@ -392,22 +396,47 @@ M foo.c
SKIP-WORKTREE BIT
-----------------
-Skip-worktree bit can be defined in one (long) sentence: When reading
-an entry, if it is marked as skip-worktree, then Git pretends its
-working directory version is up to date and read the index version
-instead.
-
-To elaborate, "reading" means checking for file existence, reading
-file attributes or file content. The working directory version may be
-present or absent. If present, its content may match against the index
-version or not. Writing is not affected by this bit, content safety
-is still first priority. Note that Git _can_ update working directory
-file, that is marked skip-worktree, if it is safe to do so (i.e.
-working directory version matches index version)
+Skip-worktree bit can be defined in one (long) sentence: Tell git to
+avoid writing the file to the working directory when reasonably
+possible, and treat the file as unchanged when it is not
+present in the working directory.
+
+Note that not all git commands will pay attention to this bit, and
+some only partially support it.
+
+The update-index flags and the read-tree capabilities relating to the
+skip-worktree bit predated the introduction of the
+linkgit:git-sparse-checkout[1] command, which provides a much easier
+way to configure and handle the skip-worktree bits. If you want to
+reduce your working tree to only deal with a subset of the files in
+the repository, we strongly encourage the use of
+linkgit:git-sparse-checkout[1] in preference to the low-level
+update-index and read-tree primitives.
+
+The primary purpose of the skip-worktree bit is to enable sparse
+checkouts, i.e. to have working directories with only a subset of
+paths present. When the skip-worktree bit is set, Git commands (such
+as `switch`, `pull`, `merge`) will avoid writing these files.
+However, these commands will sometimes write these files anyway in
+important cases such as conflicts during a merge or rebase. Git
+commands will also avoid treating the lack of such files as an
+intentional deletion; for example `git add -u` will not not stage a
+deletion for these files and `git commit -a` will not make a commit
+deleting them either.
Although this bit looks similar to assume-unchanged bit, its goal is
-different from assume-unchanged bit's. Skip-worktree also takes
-precedence over assume-unchanged bit when both are set.
+different. The assume-unchanged bit is for leaving the file in the
+working tree but having Git omit checking it for changes and presuming
+that the file has not been changed (though if it can determine without
+stat'ing the file that it has changed, it is free to record the
+changes). skip-worktree tells Git to ignore the absence of the file,
+avoid updating it when possible with commands that normally update
+much of the working directory (e.g. `checkout`, `switch`, `pull`,
+etc.), and not have its absence be recorded in commits. Note that in
+sparse checkouts (setup by `git sparse-checkout` or by configuring
+core.sparseCheckout to true), if a file is marked as skip-worktree in
+the index but is found in the working tree, Git will clear the
+skip-worktree bit for that file.
SPLIT INDEX
-----------