1GIT-SPARSE-CHECKOU(1) Git Manual GIT-SPARSE-CHECKOU(1)
2
6 git-sparse-checkout - Initialize and modify the sparse-checkout
7 configuration, which reduces the checkout to a set of paths given by a
8 list of patterns.
9
11 git sparse-checkout <subcommand> [options]
12
14 Initialize and modify the sparse-checkout configuration, which reduces
15 the checkout to a set of paths given by a list of patterns.
16 THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
18 COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN THE
19 FUTURE.
20
22 list
23 Describe the patterns in the sparse-checkout file.
24 init
26 Enable the core.sparseCheckout setting. If the sparse-checkout file
27 does not exist, then populate it with patterns that match every
28 file in the root directory and no other directories, then will
29 remove all directories tracked by Git. Add patterns to the
30 sparse-checkout file to repopulate the working directory.
31 To avoid interfering with other worktrees, it first enables the
33 extensions.worktreeConfig setting and makes sure to set the
34 core.sparseCheckout setting in the worktree-specific config file.
35 When --cone is provided, the core.sparseCheckoutCone setting is
37 also set, allowing for better performance with a limited set of
38 patterns (see CONE PATTERN SET below).
39 Use the --[no-]sparse-index option to toggle the use of the sparse
41 index format. This reduces the size of the index to be more closely
42 aligned with your sparse-checkout definition. This can have
43 significant performance advantages for commands such as git status
44 or git add. This feature is still experimental. Some commands might
45 be slower with a sparse index until they are properly integrated
46 with the feature.
47 WARNING: Using a sparse index requires modifying the index in a way
49 that is not completely understood by external tools. If you have
50 trouble with this compatibility, then run git sparse-checkout init
51 --no-sparse-index to rewrite your index to not be sparse. Older
52 versions of Git will not understand the sparse directory entries
53 index extension and may fail to interact with your repository until
54 it is disabled.
55 set
57 Write a set of patterns to the sparse-checkout file, as given as a
58 list of arguments following the set subcommand. Update the working
59 directory to match the new patterns. Enable the core.sparseCheckout
60 config setting if it is not already enabled.
61 When the --stdin option is provided, the patterns are read from
63 standard in as a newline-delimited list instead of from the
64 arguments.
65 When core.sparseCheckoutCone is enabled, the input list is
67 considered a list of directories instead of sparse-checkout
68 patterns. The command writes patterns to the sparse-checkout file
69 to include all files contained in those directories (recursively)
70 as well as files that are siblings of ancestor directories. The
71 input format matches the output of git ls-tree --name-only. This
72 includes interpreting pathnames that begin with a double quote (")
73 as C-style quoted strings.
74 add
76 Update the sparse-checkout file to include additional patterns. By
77 default, these patterns are read from the command-line arguments,
78 but they can be read from stdin using the --stdin option. When
79 core.sparseCheckoutCone is enabled, the given patterns are
80 interpreted as directory names as in the set subcommand.
81 reapply
83 Reapply the sparsity pattern rules to paths in the working tree.
84 Commands like merge or rebase can materialize paths to do their
85 work (e.g. in order to show you a conflict), and other
86 sparse-checkout commands might fail to sparsify an individual file
87 (e.g. because it has unstaged changes or conflicts). In such cases,
88 it can make sense to run git sparse-checkout reapply later after
89 cleaning up affected paths (e.g. resolving conflicts, undoing or
90 committing changes, etc.).
91 disable
93 Disable the core.sparseCheckout config setting, and restore the
94 working directory to include all files. Leaves the sparse-checkout
95 file intact so a later git sparse-checkout init command may return
96 the working directory to the same state.
97
99 "Sparse checkout" allows populating the working directory sparsely. It
100 uses the skip-worktree bit (see git-update-index(1)) to tell Git
101 whether a file in the working directory is worth looking at. If the
102 skip-worktree bit is set, then the file is ignored in the working
103 directory. Git will not populate the contents of those files, which
104 makes a sparse checkout helpful when working in a repository with many
105 files, but only a few are important to the current user.
106 The $GIT_DIR/info/sparse-checkout file is used to define the
108 skip-worktree reference bitmap. When Git updates the working directory,
109 it updates the skip-worktree bits in the index based on this file. The
110 files matching the patterns in the file will appear in the working
111 directory, and the rest will not.
112 To enable the sparse-checkout feature, run git sparse-checkout init to
114 initialize a simple sparse-checkout file and enable the
115 core.sparseCheckout config setting. Then, run git sparse-checkout set
116 to modify the patterns in the sparse-checkout file.
117 To repopulate the working directory with all files, use the git
119 sparse-checkout disable command.
120
122 By default, the sparse-checkout file uses the same syntax as .gitignore
123 files.
124 While $GIT_DIR/info/sparse-checkout is usually used to specify what
126 files are included, you can also specify what files are not included,
127 using negative patterns. For example, to remove the file unwanted:
128 /*
130 !unwanted
131
133 The full pattern set allows for arbitrary pattern matches and
134 complicated inclusion/exclusion rules. These can result in O(N*M)
135 pattern matches when updating the index, where N is the number of
136 patterns and M is the number of paths in the index. To combat this
137 performance issue, a more restricted pattern set is allowed when
138 core.sparseCheckoutCone is enabled.
139 The accepted patterns in the cone pattern set are:
141 1. Recursive: All paths inside a directory are included.
143 2. Parent: All files immediately inside a directory are included.
145 In addition to the above two patterns, we also expect that all files in
147 the root directory are included. If a recursive pattern is added, then
148 all leading directories are added as parent patterns.
149 By default, when running git sparse-checkout init, the root directory
151 is added as a parent pattern. At this point, the sparse-checkout file
152 contains the following patterns:
153 /*
155 !/*/
156 This says "include everything in root, but nothing two levels below
158 root."
159 When in cone mode, the git sparse-checkout set subcommand takes a list
161 of directories instead of a list of sparse-checkout patterns. In this
162 mode, the command git sparse-checkout set A/B/C sets the directory
163 A/B/C as a recursive pattern, the directories A and A/B are added as
164 parent patterns. The resulting sparse-checkout file is now
165 /*
167 !/*/
168 /A/
169 !/A/*/
170 /A/B/
171 !/A/B/*/
172 /A/B/C/
173 Here, order matters, so the negative patterns are overridden by the
175 positive patterns that appear lower in the file.
176 If core.sparseCheckoutCone=true, then Git will parse the
178 sparse-checkout file expecting patterns of these types. Git will warn
179 if the patterns do not match. If the patterns do match the expected
180 format, then Git will use faster hash- based algorithms to compute
181 inclusion in the sparse-checkout.
182 In the cone mode case, the git sparse-checkout list subcommand will
184 list the directories that define the recursive patterns. For the
185 example sparse-checkout file above, the output is as follows:
186 $ git sparse-checkout list
188 A/B/C
189 If core.ignoreCase=true, then the pattern-matching algorithm will use a
191 case-insensitive check. This corrects for case mismatched filenames in
192 the git sparse-checkout set command to reflect the expected cone in the
193 working directory.
194
196 If your repository contains one or more submodules, then submodules are
197 populated based on interactions with the git submodule command.
198 Specifically, git submodule init -- <path> will ensure the submodule at
199 <path> is present, while git submodule deinit [-f] -- <path> will
200 remove the files for the submodule at <path> (including any untracked
201 files, uncommitted changes, and unpushed history). Similar to how
202 sparse-checkout removes files from the working tree but still leaves
203 entries in the index, deinitialized submodules are removed from the
204 working directory but still have an entry in the index.
205 Since submodules may have unpushed changes or untracked files, removing
207 them could result in data loss. Thus, changing sparse
208 inclusion/exclusion rules will not cause an already checked out
209 submodule to be removed from the working copy. Said another way, just
210 as checkout will not cause submodules to be automatically removed or
211 initialized even when switching between branches that remove or add
212 submodules, using sparse-checkout to reduce or expand the scope of
213 "interesting" files will not cause submodules to be automatically
214 deinitialized or initialized either.
215 Further, the above facts mean that there are multiple reasons that
217 "tracked" files might not be present in the working copy: sparsity
218 pattern application from sparse-checkout, and submodule initialization
219 state. Thus, commands like git grep that work on tracked files in the
220 working copy may return results that are limited by either or both of
221 these restrictions.
222
224 git-read-tree(1) gitignore(5)
225
227 Part of the git(1) suite
228Git 2.33.1 2021-10-12 GIT-SPARSE-CHECKOU(1)