freshlybakedca.ke
Git fork
1git-sparse-checkout(1)
2======================
3
4NAME
5----
6git-sparse-checkout - Reduce your working tree to a subset of tracked files
7
8
9SYNOPSIS
10--------
11[verse]
12'git sparse-checkout' (init | list | set | add | reapply | disable | check-rules | clean) [<options>]
13
14
15DESCRIPTION
16-----------
17
18This command is used to create sparse checkouts, which change the
19working tree from having all tracked files present to only having a
20subset of those files. It can also switch which subset of files are
21present, or undo and go back to having all tracked files present in
22the working copy.
23
24The subset of files is chosen by providing a list of directories in
25cone mode (the default), or by providing a list of patterns in
26non-cone mode.
27
28When in a sparse-checkout, other Git commands behave a bit differently.
29For example, switching branches will not update paths outside the
30sparse-checkout directories/patterns, and `git commit -a` will not record
31paths outside the sparse-checkout directories/patterns as deleted.
32
33THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
34COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN
35THE FUTURE.
36
37
38COMMANDS
39--------
40'list'::
41 Describe the directories or patterns in the sparse-checkout file.
42
43'set'::
44 Enable the necessary sparse-checkout config settings
45 (`core.sparseCheckout`, `core.sparseCheckoutCone`, and
46 `index.sparse`) if they are not already set to the desired values,
47 populate the sparse-checkout file from the list of arguments
48 following the 'set' subcommand, and update the working directory to
49 match.
50+
51To ensure that adjusting the sparse-checkout settings within a worktree
52does not alter the sparse-checkout settings in other worktrees, the 'set'
53subcommand will upgrade your repository config to use worktree-specific
54config if not already present. The sparsity defined by the arguments to
55the 'set' subcommand are stored in the worktree-specific sparse-checkout
56file. See linkgit:git-worktree[1] and the documentation of
57`extensions.worktreeConfig` in linkgit:git-config[1] for more details.
58+
59When the `--stdin` option is provided, the directories or patterns are
60read from standard in as a newline-delimited list instead of from the
61arguments.
62+
63By default, the input list is considered a list of directories, matching
64the output of `git ls-tree -d --name-only`. This includes interpreting
65pathnames that begin with a double quote (") as C-style quoted strings.
66Note that all files under the specified directories (at any depth) will
67be included in the sparse checkout, as well as files that are siblings
68of either the given directory or any of its ancestors (see 'CONE PATTERN
69SET' below for more details). In the past, this was not the default,
70and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
71to be enabled.
72+
73When `--no-cone` is passed, the input list is considered a list of
74patterns. This mode has a number of drawbacks, including not working
75with some options like `--sparse-index`. As explained in the
76"Non-cone Problems" section below, we do not recommend using it.
77+
78Use the `--[no-]sparse-index` option to use a sparse index (the
79default is to not use it). A sparse index reduces the size of the
80index to be more closely aligned with your sparse-checkout
81definition. This can have significant performance advantages for
82commands such as `git status` or `git add`. This feature is still
83experimental. Some commands might be slower with a sparse index until
84they are properly integrated with the feature.
85+
86**WARNING:** Using a sparse index requires modifying the index in a way
87that is not completely understood by external tools. If you have trouble
88with this compatibility, then run `git sparse-checkout init --no-sparse-index`
89to rewrite your index to not be sparse. Older versions of Git will not
90understand the sparse directory entries index extension and may fail to
91interact with your repository until it is disabled.
92
93'add'::
94 Update the sparse-checkout file to include additional directories
95 (in cone mode) or patterns (in non-cone mode). By default, these
96 directories or patterns are read from the command-line arguments,
97 but they can be read from stdin using the `--stdin` option.
98
99'reapply'::
100 Reapply the sparsity pattern rules to paths in the working tree.
101 Commands like merge or rebase can materialize paths to do their
102 work (e.g. in order to show you a conflict), and other
103 sparse-checkout commands might fail to sparsify an individual file
104 (e.g. because it has unstaged changes or conflicts). In such
105 cases, it can make sense to run `git sparse-checkout reapply` later
106 after cleaning up affected paths (e.g. resolving conflicts, undoing
107 or committing changes, etc.).
108+
109The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
110flags, with the same meaning as the flags from the `set` command, in order
111to change which sparsity mode you are using without needing to also respecify
112all sparsity paths.
113
114'clean'::
115 Opportunistically remove files outside of the sparse-checkout
116 definition. This command requires cone mode to use recursive
117 directory matches to determine which files should be removed. A
118 file is considered for removal if it is contained within a tracked
119 directory that is outside of the sparse-checkout definition.
120+
121Some special cases, such as merge conflicts or modified files outside of
122the sparse-checkout definition could lead to keeping files that would
123otherwise be removed. Resolve conflicts, stage modifications, and use
124`git sparse-checkout reapply` in conjunction with `git sparse-checkout
125clean` to resolve these cases.
126+
127This command can be used to be sure the sparse index works efficiently,
128though it does not require enabling the sparse index feature via the
129`index.sparse=true` configuration.
130+
131To prevent accidental deletion of worktree files, the `clean` subcommand
132will not delete any files without the `-f` or `--force` option, unless
133the `clean.requireForce` config option is set to `false`.
134+
135The `--dry-run` option will list the directories that would be removed
136without deleting them. Running in this mode can be helpful to predict the
137behavior of the clean comand or to determine which kinds of files are left
138in the sparse directories.
139+
140The `--verbose` option will list every file within the directories that
141are considered for removal. This option is helpful to determine if those
142files are actually important or perhaps to explain why the directory is
143still present despite the current sparse-checkout.
144
145'disable'::
146 Disable the `core.sparseCheckout` config setting, and restore the
147 working directory to include all files.
148
149'init'::
150 Deprecated command that behaves like `set` with no specified paths.
151 May be removed in the future.
152+
153Historically, `set` did not handle all the necessary config settings,
154which meant that both `init` and `set` had to be called. Invoking
155both meant the `init` step would first remove nearly all tracked files
156(and in cone mode, ignored files too), then the `set` step would add
157many of the tracked files (but not ignored files) back. In addition
158to the lost files, the performance and UI of this combination was
159poor.
160+
161Also, historically, `init` would not actually initialize the
162sparse-checkout file if it already existed. This meant it was
163possible to return to a sparse-checkout without remembering which
164paths to pass to a subsequent 'set' or 'add' command. However,
165`--cone` and `--sparse-index` options would not be remembered across
166the disable command, so the easy restore of calling a plain `init`
167decreased in utility.
168
169'check-rules'::
170 Check whether sparsity rules match one or more paths.
171+
172By default `check-rules` reads a list of paths from stdin and outputs only
173the ones that match the current sparsity rules. The input is expected to consist
174of one path per line, matching the output of `git ls-tree --name-only` including
175that pathnames that begin with a double quote (") are interpreted as C-style
176quoted strings.
177+
178When called with the `--rules-file <file>` flag the input files are matched
179against the sparse checkout rules found in `<file>` instead of the current ones.
180The rules in the files are expected to be in the same form as accepted by `git
181sparse-checkout set --stdin` (in particular, they must be newline-delimited).
182+
183By default, the rules passed to the `--rules-file` option are interpreted as
184cone mode directories. To pass non-cone mode patterns with `--rules-file`,
185combine the option with the `--no-cone` option.
186+
187When called with the `-z` flag, the format of the paths input on stdin as well
188as the output paths are \0 terminated and not quoted. Note that this does not
189apply to the format of the rules passed with the `--rules-file` option.
190
191
192EXAMPLES
193--------
194`git sparse-checkout set MY/DIR1 SUB/DIR2`::
195
196 Change to a sparse checkout with all files (at any depth) under
197 MY/DIR1/ and SUB/DIR2/ present in the working copy (plus all
198 files immediately under MY/ and SUB/ and the toplevel
199 directory). If already in a sparse checkout, change which files
200 are present in the working copy to this new selection. Note
201 that this command will also delete all ignored files in any
202 directory that no longer has either tracked or
203 non-ignored-untracked files present.
204
205`git sparse-checkout disable`::
206
207 Repopulate the working directory with all files, disabling sparse
208 checkouts.
209
210`git sparse-checkout add SOME/DIR/ECTORY`::
211
212 Add all files under SOME/DIR/ECTORY/ (at any depth) to the
213 sparse checkout, as well as all files immediately under
214 SOME/DIR/ and immediately under SOME/. Must already be in a
215 sparse checkout before using this command.
216
217`git sparse-checkout reapply`::
218
219 It is possible for commands to update the working tree in a
220 way that does not respect the selected sparsity directories.
221 This can come from tools external to Git writing files, or
222 even affect Git commands because of either special cases (such
223 as hitting conflicts when merging/rebasing), or because some
224 commands didn't fully support sparse checkouts (e.g. the old
225 `recursive` merge backend had only limited support). This
226 command reapplies the existing sparse directory specifications
227 to make the working directory match.
228
229INTERNALS -- SPARSE CHECKOUT
230----------------------------
231
232"Sparse checkout" allows populating the working directory sparsely. It
233uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git
234whether a file in the working directory is worth looking at. If the
235skip-worktree bit is set, and the file is not present in the working tree,
236then its absence is ignored. Git will avoid populating the contents of
237those files, which makes a sparse checkout helpful when working in a
238repository with many files, but only a few are important to the current
239user.
240
241The `$GIT_DIR/info/sparse-checkout` file is used to define the
242skip-worktree reference bitmap. When Git updates the working
243directory, it updates the skip-worktree bits in the index based
244on this file. The files matching the patterns in the file will
245appear in the working directory, and the rest will not.
246
247INTERNALS -- NON-CONE PROBLEMS
248------------------------------
249
250The `$GIT_DIR/info/sparse-checkout` file populated by the `set` and
251`add` subcommands is defined to be a bunch of patterns (one per line)
252using the same syntax as `.gitignore` files. In cone mode, these
253patterns are restricted to matching directories (and users only ever
254need supply or see directory names), while in non-cone mode any
255gitignore-style pattern is permitted. Using the full gitignore-style
256patterns in non-cone mode has a number of shortcomings:
257
258 * Fundamentally, it makes various worktree-updating processes (pull,
259 merge, rebase, switch, reset, checkout, etc.) require O(N*M) pattern
260 matches, where N is the number of patterns and M is the number of
261 paths in the index. This scales poorly.
262
263 * Avoiding the scaling issue has to be done via limiting the number
264 of patterns via specifying leading directory name or glob.
265
266 * Passing globs on the command line is error-prone as users may
267 forget to quote the glob, causing the shell to expand it into all
268 matching files and pass them all individually along to
269 sparse-checkout set/add. While this could also be a problem with
270 e.g. "git grep -- *.c", mistakes with grep/log/status appear in
271 the immediate output. With sparse-checkout, the mistake gets
272 recorded at the time the sparse-checkout command is run and might
273 not be problematic until the user later switches branches or rebases
274 or merges, thus putting a delay between the user's error and when
275 they have a chance to catch/notice it.
276
277 * Related to the previous item, sparse-checkout has an 'add'
278 subcommand but no 'remove' subcommand. Even if a 'remove'
279 subcommand were added, undoing an accidental unquoted glob runs
280 the risk of "removing too much", as it may remove entries that had
281 been included before the accidental add.
282
283 * Non-cone mode uses gitignore-style patterns to select what to
284 *include* (with the exception of negated patterns), while
285 .gitignore files use gitignore-style patterns to select what to
286 *exclude* (with the exception of negated patterns). The
287 documentation on gitignore-style patterns usually does not talk in
288 terms of matching or non-matching, but on what the user wants to
289 "exclude". This can cause confusion for users trying to learn how
290 to specify sparse-checkout patterns to get their desired behavior.
291
292 * Every other git subcommand that wants to provide "special path
293 pattern matching" of some sort uses pathspecs, but non-cone mode
294 for sparse-checkout uses gitignore patterns, which feels
295 inconsistent.
296
297 * It has edge cases where the "right" behavior is unclear. Two examples:
298+
299First, two users are in a subdirectory, and the first runs
300+
301----
302git sparse-checkout set '/toplevel-dir/*.c'
303----
304+
305while the second runs
306+
307----
308git sparse-checkout set relative-dir
309----
310+
311Should those arguments be transliterated into
312+
313----
314current/subdirectory/toplevel-dir/*.c
315----
316+
317and
318+
319----
320current/subdirectory/relative-dir
321----
322+
323before inserting into the sparse-checkout file? The user who typed
324the first command is probably aware that arguments to set/add are
325supposed to be patterns in non-cone mode, and probably would not be
326happy with such a transliteration. However, many gitignore-style
327patterns are just paths, which might be what the user who typed the
328second command was thinking, and they'd be upset if their argument
329wasn't transliterated.
330+
331Second, what should bash-completion complete on for set/add commands
332for non-cone users? If it suggests paths, is it exacerbating the
333problem above? Also, if it suggests paths, what if the user has a
334file or directory that begins with either a '!' or '#' or has a '*',
335'\', '?', '[', or ']' in its name? And if it suggests paths, will
336it complete "/pro" to "/proc" (in the root filesystem) rather than to
337"/progress.txt" in the current directory? (Note that users are
338likely to want to start paths with a leading '/' in non-cone mode,
339for the same reason that .gitignore files often have one.)
340Completing on files or directories might give nasty surprises in
341all these cases.
342
343 * The excessive flexibility made other extensions essentially
344 impractical. `--sparse-index` is likely impossible in non-cone
345 mode; even if it is somehow feasible, it would have been far more
346 work to implement and may have been too slow in practice. Some
347 ideas for adding coupling between partial clones and sparse
348 checkouts are only practical with a more restricted set of paths
349 as well.
350
351For all these reasons, non-cone mode is deprecated. Please switch to
352using cone mode.
353
354
355INTERNALS -- CONE MODE HANDLING
356-------------------------------
357
358The "cone mode", which is the default, lets you specify only what
359directories to include. For any directory specified, all paths below
360that directory will be included, and any paths immediately under
361leading directories (including the toplevel directory) will also be
362included. Thus, if you specified the directory
363 Documentation/technical/
364then your sparse checkout would contain:
365
366 * all files in the toplevel-directory
367 * all files immediately under Documentation/
368 * all files at any depth under Documentation/technical/
369
370Also, in cone mode, even if no directories are specified, then the
371files in the toplevel directory will be included.
372
373When changing the sparse-checkout patterns in cone mode, Git will inspect each
374tracked directory that is not within the sparse-checkout cone to see if it
375contains any untracked files. If all of those files are ignored due to the
376`.gitignore` patterns, then the directory will be deleted. If any of the
377untracked files within that directory is not ignored, then no deletions will
378occur within that directory and a warning message will appear. If these files
379are important, then reset your sparse-checkout definition so they are included,
380use `git add` and `git commit` to store them, then remove any remaining files
381manually to ensure Git can behave optimally.
382
383See also the "Internals -- Cone Pattern Set" section to learn how the
384directories are transformed under the hood into a subset of the
385Full Pattern Set of sparse-checkout.
386
387
388INTERNALS -- FULL PATTERN SET
389-----------------------------
390
391The full pattern set allows for arbitrary pattern matches and complicated
392inclusion/exclusion rules. These can result in O(N*M) pattern matches when
393updating the index, where N is the number of patterns and M is the number
394of paths in the index. To combat this performance issue, a more restricted
395pattern set is allowed when `core.sparseCheckoutCone` is enabled.
396
397The sparse-checkout file uses the same syntax as `.gitignore` files;
398see linkgit:gitignore[5] for details. Here, though, the patterns are
399usually being used to select which files to include rather than which
400files to exclude. (However, it can get a bit confusing since
401gitignore-style patterns have negations defined by patterns which
402begin with a '!', so you can also select files to _not_ include.)
403
404For example, to select everything, and then to remove the file
405`unwanted` (so that every file will appear in your working tree except
406the file named `unwanted`):
407
408 git sparse-checkout set --no-cone '/*' '!unwanted'
409
410These patterns are just placed into the
411`$GIT_DIR/info/sparse-checkout` as-is, so the contents of that file
412at this point would be
413
414----------------
415/*
416!unwanted
417----------------
418
419See also the "Sparse Checkout" section of linkgit:git-read-tree[1] to
420learn more about the gitignore-style patterns used in sparse
421checkouts.
422
423
424INTERNALS -- CONE PATTERN SET
425-----------------------------
426
427In cone mode, only directories are accepted, but they are translated into
428the same gitignore-style patterns used in the full pattern set. We refer
429to the particular patterns used in those mode as being of one of two types:
430
4311. *Recursive:* All paths inside a directory are included.
432
4332. *Parent:* All files immediately inside a directory are included.
434
435Since cone mode always includes files at the toplevel, when running
436`git sparse-checkout set` with no directories specified, the toplevel
437directory is added as a parent pattern. At this point, the
438sparse-checkout file contains the following patterns:
439
440----------------
441/*
442!/*/
443----------------
444
445This says "include everything immediately under the toplevel
446directory, but nothing at any level below that."
447
448When in cone mode, the `git sparse-checkout set` subcommand takes a
449list of directories. The command `git sparse-checkout set A/B/C` sets
450the directory `A/B/C` as a recursive pattern, the directories `A` and
451`A/B` are added as parent patterns. The resulting sparse-checkout file
452is now
453
454----------------
455/*
456!/*/
457/A/
458!/A/*/
459/A/B/
460!/A/B/*/
461/A/B/C/
462----------------
463
464Here, order matters, so the negative patterns are overridden by the positive
465patterns that appear lower in the file.
466
467Unless `core.sparseCheckoutCone` is explicitly set to `false`, Git will
468parse the sparse-checkout file expecting patterns of these types. Git will
469warn if the patterns do not match. If the patterns do match the expected
470format, then Git will use faster hash-based algorithms to compute inclusion
471in the sparse-checkout. If they do not match, git will behave as though
472`core.sparseCheckoutCone` was false, regardless of its setting.
473
474In the cone mode case, despite the fact that full patterns are written
475to the $GIT_DIR/info/sparse-checkout file, the `git sparse-checkout
476list` subcommand will list the directories that define the recursive
477patterns. For the example sparse-checkout file above, the output is as
478follows:
479
480--------------------------
481$ git sparse-checkout list
482A/B/C
483--------------------------
484
485If `core.ignoreCase=true`, then the pattern-matching algorithm will use a
486case-insensitive check. This corrects for case mismatched filenames in the
487'git sparse-checkout set' command to reflect the expected cone in the working
488directory.
489
490
491INTERNALS -- SUBMODULES
492-----------------------
493
494If your repository contains one or more submodules, then submodules
495are populated based on interactions with the `git submodule` command.
496Specifically, `git submodule init -- <path>` will ensure the submodule
497at `<path>` is present, while `git submodule deinit [-f] -- <path>`
498will remove the files for the submodule at `<path>` (including any
499untracked files, uncommitted changes, and unpushed history). Similar
500to how sparse-checkout removes files from the working tree but still
501leaves entries in the index, deinitialized submodules are removed from
502the working directory but still have an entry in the index.
503
504Since submodules may have unpushed changes or untracked files,
505removing them could result in data loss. Thus, changing sparse
506inclusion/exclusion rules will not cause an already checked out
507submodule to be removed from the working copy. Said another way, just
508as `checkout` will not cause submodules to be automatically removed or
509initialized even when switching between branches that remove or add
510submodules, using `sparse-checkout` to reduce or expand the scope of
511"interesting" files will not cause submodules to be automatically
512deinitialized or initialized either.
513
514Further, the above facts mean that there are multiple reasons that
515"tracked" files might not be present in the working copy: sparsity
516pattern application from sparse-checkout, and submodule initialization
517state. Thus, commands like `git grep` that work on tracked files in
518the working copy may return results that are limited by either or both
519of these restrictions.
520
521
522SEE ALSO
523--------
524
525linkgit:git-read-tree[1]
526linkgit:gitignore[5]
527
528GIT
529---
530Part of the linkgit:git[1] suite