@matheusbsbs / matheus-bagliano / commits / 9023535bd3

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>

Elijah Newren committed Jan 14, 2022 at 15:59 UTC 9023535bd3953df265f30a3d53b1fda2107bb690

3 files changed +98 -47

Documentation/git-read-tree.txt

+9 -3

@@ -375,9 +375,14 @@ have finished your work-in-progress), attempt the merge again.

375 SPARSE CHECKOUT

376 ---------------

377

378 +Note: The `update-index` and `read-tree` primitives for supporting the

379 +skip-worktree bit predated the introduction of

380 +linkgit:git-sparse-checkout[1]. Users are encouraged to use

381 +`sparse-checkout` in preference to these low-level primitives.

382 +

383 "Sparse checkout" allows populating the working directory sparsely.

379 -It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell

380 -Git whether a file in the working directory is worth looking at.

384 +It uses the skip-worktree bit (see linkgit:git-update-index[1]) to

385 +tell Git whether a file in the working directory is worth looking at.

386

387 'git read-tree' and other merge-based commands ('git merge', 'git

388 checkout'...) can help maintaining the skip-worktree bitmap and working

@@ -385,7 +390,8 @@ directory update. `$GIT_DIR/info/sparse-checkout` is used to

390 define the skip-worktree reference bitmap. When 'git read-tree' needs

391 to update the working directory, it resets the skip-worktree bit in the index

392 based on this file, which uses the same syntax as .gitignore files.

388 -If an entry matches a pattern in this file, skip-worktree will not be

393 +If an entry matches a pattern in this file, or the entry corresponds to

394 +a file present in the working tree, then skip-worktree will not be

395 set on that entry. Otherwise, skip-worktree will be set.

396

397 Then it compares the new skip-worktree value with the previous one. If

Documentation/git-sparse-checkout.txt

+46 -30

@@ -3,9 +3,7 @@ git-sparse-checkout(1)

4 NAME

5 ----

6 -git-sparse-checkout - Initialize and modify the sparse-checkout

7 -configuration, which reduces the checkout to a set of paths

8 -given by a list of patterns.

6 +git-sparse-checkout - Reduce your working tree to a subset of tracked files

9 SYNOPSIS

@@ -17,8 +15,20 @@ SYNOPSIS

15 DESCRIPTION

16 -----------

20 -Initialize and modify the sparse-checkout configuration, which reduces

21 -the checkout to a set of paths given by a list of patterns.

18 +This command is used to create sparse checkouts, which means that it

19 +changes the working tree from having all tracked files present, to only

20 +have a subset of them. It can also switch which subset of files are

21 +present, or undo and go back to having all tracked files present in the

22 +working copy.

23 +

24 +The subset of files is chosen by providing a list of directories in

25 +cone mode (which is recommended), or by providing a list of patterns

26 +in non-cone mode.

27 +

28 +When in a sparse-checkout, other Git commands behave a bit differently.

29 +For example, switching branches will not update paths outside the

30 +sparse-checkout directories/patterns, and `git commit -a` will not record

31 +paths outside the sparse-checkout directories/patterns as deleted.

33 THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER

34 COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN

@@ -28,7 +38,7 @@ THE FUTURE.

38 COMMANDS

39 --------

40 'list'::

31 - Describe the patterns in the sparse-checkout file.

41 + Describe the directories or patterns in the sparse-checkout file.

43 'set'::

44 Enable the necessary config settings

@@ -38,20 +48,26 @@ COMMANDS

48 list of arguments following the 'set' subcommand. Update the

49 working directory to match the new patterns.

50 +

41 -When the `--stdin` option is provided, the patterns are read from

42 -standard in as a newline-delimited list instead of from the arguments.

51 +When the `--stdin` option is provided, the directories or patterns are

52 +read from standard in as a newline-delimited list instead of from the

53 +arguments.

54 +

55 When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the

45 -input list is considered a list of directories instead of

46 -sparse-checkout patterns. This allows for better performance with a

47 -limited set of patterns (see 'CONE PATTERN SET' below). Note that the

48 -set command will write patterns to the sparse-checkout file to include

49 -all files contained in those directories (recursively) as well as

50 -files that are siblings of ancestor directories. The input format

51 -matches the output of `git ls-tree --name-only`. This includes

52 -interpreting pathnames that begin with a double quote (") as C-style

53 -quoted strings. This may become the default in the future; --no-cone

54 -can be passed to request non-cone mode.

56 +input list is considered a list of directories. This allows for

57 +better performance with a limited set of patterns (see 'CONE PATTERN

58 +SET' below). The input format matches the output of `git ls-tree

59 +--name-only`. This includes interpreting pathnames that begin with a

60 +double quote (") as C-style quoted strings. Note that the set command

61 +will write patterns to the sparse-checkout file to include all files

62 +contained in those directories (recursively) as well as files that are

63 +siblings of ancestor directories. This may become the default in the

64 +future; --no-cone can be passed to request non-cone mode.

65 ++

66 +When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled,

67 +the input list is considered a list of patterns. This mode is harder

68 +to use and less performant, and is thus not recommended. See the

69 +"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern

70 +Set" sections below for more details.

71 +

72 Use the `--[no-]sparse-index` option to use a sparse index (the

73 default is to not use it). A sparse index reduces the size of the

@@ -69,11 +85,10 @@ understand the sparse directory entries index extension and may fail to

85 interact with your repository until it is disabled.

87 'add'::

72 - Update the sparse-checkout file to include additional patterns.

73 - By default, these patterns are read from the command-line arguments,

74 - but they can be read from stdin using the `--stdin` option. When

75 - `core.sparseCheckoutCone` is enabled, the given patterns are interpreted

76 - as directory names as in the 'set' subcommand.

88 + Update the sparse-checkout file to include additional directories

89 + (in cone mode) or patterns (in non-cone mode). By default, these

90 + directories or patterns are read from the command-line arguments,

91 + but they can be read from stdin using the `--stdin` option.

93 'reapply'::

94 Reapply the sparsity pattern rules to paths in the working tree.

@@ -117,13 +132,14 @@ decreased in utility.

132 SPARSE CHECKOUT

133 ---------------

134

120 -"Sparse checkout" allows populating the working directory sparsely.

121 -It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell

122 -Git whether a file in the working directory is worth looking at. If

123 -the skip-worktree bit is set, then the file is ignored in the working

124 -directory. Git will avoid populating the contents of those files, which

125 -makes a sparse checkout helpful when working in a repository with many

126 -files, but only a few are important to the current user.

135 +"Sparse checkout" allows populating the working directory sparsely. It

136 +uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git

137 +whether a file in the working directory is worth looking at. If the

138 +skip-worktree bit is set, and the file is not present in the working tree,

139 +then its absence is ignored. Git will avoid populating the contents of

140 +those files, which makes a sparse checkout helpful when working in a

141 +repository with many files, but only a few are important to the current

142 +user.

143

144 The `$GIT_DIR/info/sparse-checkout` file is used to define the

145 skip-worktree reference bitmap. When Git updates the working

Documentation/git-update-index.txt

+43 -14

@@ -351,6 +351,10 @@ unchanged". Note that "assume unchanged" bit is *not* set if

351 the index (use `git update-index --really-refresh` if you want

352 to mark them as "assume unchanged").

353

354 +Sometimes users confuse the assume-unchanged bit with the

355 +skip-worktree bit. See the final paragraph in the "Skip-worktree bit"

356 +section below for an explanation of the differences.

357 +

358

359 EXAMPLES

360 --------

@@ -392,22 +396,47 @@ M foo.c

396 SKIP-WORKTREE BIT

397 -----------------

398

395 -Skip-worktree bit can be defined in one (long) sentence: When reading

396 -an entry, if it is marked as skip-worktree, then Git pretends its

397 -working directory version is up to date and read the index version

398 -instead.

399 -

400 -To elaborate, "reading" means checking for file existence, reading

401 -file attributes or file content. The working directory version may be

402 -present or absent. If present, its content may match against the index

403 -version or not. Writing is not affected by this bit, content safety

404 -is still first priority. Note that Git _can_ update working directory

405 -file, that is marked skip-worktree, if it is safe to do so (i.e.

406 -working directory version matches index version)

399 +Skip-worktree bit can be defined in one (long) sentence: Tell git to

400 +avoid writing the file to the working directory when reasonably

401 +possible, and treat the file as unchanged when it is not

402 +present in the working directory.

403 +

404 +Note that not all git commands will pay attention to this bit, and

405 +some only partially support it.

406 +

407 +The update-index flags and the read-tree capabilities relating to the

408 +skip-worktree bit predated the introduction of the

409 +linkgit:git-sparse-checkout[1] command, which provides a much easier

410 +way to configure and handle the skip-worktree bits. If you want to

411 +reduce your working tree to only deal with a subset of the files in

412 +the repository, we strongly encourage the use of

413 +linkgit:git-sparse-checkout[1] in preference to the low-level

414 +update-index and read-tree primitives.

415 +

416 +The primary purpose of the skip-worktree bit is to enable sparse

417 +checkouts, i.e. to have working directories with only a subset of

418 +paths present. When the skip-worktree bit is set, Git commands (such

419 +as `switch`, `pull`, `merge`) will avoid writing these files.

420 +However, these commands will sometimes write these files anyway in

421 +important cases such as conflicts during a merge or rebase. Git

422 +commands will also avoid treating the lack of such files as an

423 +intentional deletion; for example `git add -u` will not not stage a

424 +deletion for these files and `git commit -a` will not make a commit

425 +deleting them either.

426

427 Although this bit looks similar to assume-unchanged bit, its goal is

409 -different from assume-unchanged bit's. Skip-worktree also takes

410 -precedence over assume-unchanged bit when both are set.

428 +different. The assume-unchanged bit is for leaving the file in the

429 +working tree but having Git omit checking it for changes and presuming

430 +that the file has not been changed (though if it can determine without

431 +stat'ing the file that it has changed, it is free to record the

432 +changes). skip-worktree tells Git to ignore the absence of the file,

433 +avoid updating it when possible with commands that normally update

434 +much of the working directory (e.g. `checkout`, `switch`, `pull`,

435 +etc.), and not have its absence be recorded in commits. Note that in

436 +sparse checkouts (setup by `git sparse-checkout` or by configuring

437 +core.sparseCheckout to true), if a file is marked as skip-worktree in

438 +the index but is found in the working tree, Git will clear the

439 +skip-worktree bit for that file.

440

441 SPLIT INDEX

442 -----------