Documentation/git-sparse-checkout.txt

   1 git-sparse-checkout(1)
   2 ======================
   3
   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.
   9
  10
  11 SYNOPSIS
  12 --------
  13 [verse]
  14 'git sparse-checkout <subcommand> [<options>]'
  15
  16
  17 DESCRIPTION
  18 -----------
  19
  20 Initialize and modify the sparse-checkout configuration, which reduces
  21 the checkout to a set of paths given by a list of patterns.
  22
  23 THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER
  24 COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN
  25 THE FUTURE.
  26
  27
  28 COMMANDS
  29 --------
  30 'list'::
  31         Describe the patterns in the sparse-checkout file.
  32
  33 'set'::
  34         Enable the necessary config settings
  35         (extensions.worktreeConfig, core.sparseCheckout,
  36         core.sparseCheckoutCone) if they are not already enabled, and
  37         write a set of patterns to the sparse-checkout file from the
  38         list of arguments following the 'set' subcommand. Update the
  39         working directory to match the new patterns.
  40 +
  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.
  43 +
  44 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.
  55 +
  56 Use the `--[no-]sparse-index` option to use a sparse index (the
  57 default is to not use it).  A sparse index reduces the size of the
  58 index to be more closely aligned with your sparse-checkout
  59 definition. This can have significant performance advantages for
  60 commands such as `git status` or `git add`.  This feature is still
  61 experimental. Some commands might be slower with a sparse index until
  62 they are properly integrated with the feature.
  63 +
  64 **WARNING:** Using a sparse index requires modifying the index in a way
  65 that is not completely understood by external tools. If you have trouble
  66 with this compatibility, then run `git sparse-checkout init --no-sparse-index`
  67 to rewrite your index to not be sparse. Older versions of Git will not
  68 understand the sparse directory entries index extension and may fail to
  69 interact with your repository until it is disabled.
  70
  71 '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.
  77
  78 'reapply'::
  79         Reapply the sparsity pattern rules to paths in the working tree.
  80         Commands like merge or rebase can materialize paths to do their
  81         work (e.g. in order to show you a conflict), and other
  82         sparse-checkout commands might fail to sparsify an individual file
  83         (e.g. because it has unstaged changes or conflicts).  In such
  84         cases, it can make sense to run `git sparse-checkout reapply` later
  85         after cleaning up affected paths (e.g. resolving conflicts, undoing
  86         or committing changes, etc.).
  87 +
  88 The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index`
  89 flags, with the same meaning as the flags from the `set` command, in order
  90 to change which sparsity mode you are using without needing to also respecify
  91 all sparsity paths.
  92
  93 'disable'::
  94         Disable the `core.sparseCheckout` config setting, and restore the
  95         working directory to include all files.
  96
  97 'init'::
  98         Deprecated command that behaves like `set` with no specified paths.
  99         May be removed in the future.
 100 +
 101 Historically, `set` did not handle all the necessary config settings,
 102 which meant that both `init` and `set` had to be called.  Invoking
 103 both meant the `init` step would first remove nearly all tracked files
 104 (and in cone mode, ignored files too), then the `set` step would add
 105 many of the tracked files (but not ignored files) back.  In addition
 106 to the lost files, the performance and UI of this combination was
 107 poor.
 108 +
 109 Also, historically, `init` would not actually initialize the
 110 sparse-checkout file if it already existed.  This meant it was
 111 possible to return to a sparse-checkout without remembering which
 112 paths to pass to a subsequent 'set' or 'add' command.  However,
 113 `--cone` and `--sparse-index` options would not be remembered across
 114 the disable command, so the easy restore of calling a plain `init`
 115 decreased in utility.
 116
 117 SPARSE CHECKOUT
 118 ---------------
 119
 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.
 127
 128 The `$GIT_DIR/info/sparse-checkout` file is used to define the
 129 skip-worktree reference bitmap. When Git updates the working
 130 directory, it updates the skip-worktree bits in the index based
 131 on this file. The files matching the patterns in the file will
 132 appear in the working directory, and the rest will not.
 133
 134 To enable the sparse-checkout feature, run `git sparse-checkout set` to
 135 set the patterns you want to use.
 136
 137 To repopulate the working directory with all files, use the
 138 `git sparse-checkout disable` command.
 139
 140
 141 FULL PATTERN SET
 142 ----------------
 143
 144 By default, the sparse-checkout file uses the same syntax as `.gitignore`
 145 files.
 146
 147 While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
 148 files are included, you can also specify what files are _not_ included,
 149 using negative patterns. For example, to remove the file `unwanted`:
 150
 151 ----------------
 152 /*
 153 !unwanted
 154 ----------------
 155
 156
 157 CONE PATTERN SET
 158 ----------------
 159
 160 The full pattern set allows for arbitrary pattern matches and complicated
 161 inclusion/exclusion rules. These can result in O(N*M) pattern matches when
 162 updating the index, where N is the number of patterns and M is the number
 163 of paths in the index. To combat this performance issue, a more restricted
 164 pattern set is allowed when `core.sparseCheckoutCone` is enabled.
 165
 166 The accepted patterns in the cone pattern set are:
 167
 168 1. *Recursive:* All paths inside a directory are included.
 169
 170 2. *Parent:* All files immediately inside a directory are included.
 171
 172 In addition to the above two patterns, we also expect that all files in the
 173 root directory are included. If a recursive pattern is added, then all
 174 leading directories are added as parent patterns.
 175
 176 By default, when running `git sparse-checkout init`, the root directory is
 177 added as a parent pattern. At this point, the sparse-checkout file contains
 178 the following patterns:
 179
 180 ----------------
 181 /*
 182 !/*/
 183 ----------------
 184
 185 This says "include everything in root, but nothing two levels below root."
 186
 187 When in cone mode, the `git sparse-checkout set` subcommand takes a list of
 188 directories instead of a list of sparse-checkout patterns. In this mode,
 189 the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as
 190 a recursive pattern, the directories `A` and `A/B` are added as parent
 191 patterns. The resulting sparse-checkout file is now
 192
 193 ----------------
 194 /*
 195 !/*/
 196 /A/
 197 !/A/*/
 198 /A/B/
 199 !/A/B/*/
 200 /A/B/C/
 201 ----------------
 202
 203 Here, order matters, so the negative patterns are overridden by the positive
 204 patterns that appear lower in the file.
 205
 206 If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file
 207 expecting patterns of these types. Git will warn if the patterns do not match.
 208 If the patterns do match the expected format, then Git will use faster hash-
 209 based algorithms to compute inclusion in the sparse-checkout.
 210
 211 In the cone mode case, the `git sparse-checkout list` subcommand will list the
 212 directories that define the recursive patterns. For the example sparse-checkout
 213 file above, the output is as follows:
 214
 215 --------------------------
 216 $ git sparse-checkout list
 217 A/B/C
 218 --------------------------
 219
 220 If `core.ignoreCase=true`, then the pattern-matching algorithm will use a
 221 case-insensitive check. This corrects for case mismatched filenames in the
 222 'git sparse-checkout set' command to reflect the expected cone in the working
 223 directory.
 224
 225 When changing the sparse-checkout patterns in cone mode, Git will inspect each
 226 tracked directory that is not within the sparse-checkout cone to see if it
 227 contains any untracked files. If all of those files are ignored due to the
 228 `.gitignore` patterns, then the directory will be deleted. If any of the
 229 untracked files within that directory is not ignored, then no deletions will
 230 occur within that directory and a warning message will appear. If these files
 231 are important, then reset your sparse-checkout definition so they are included,
 232 use `git add` and `git commit` to store them, then remove any remaining files
 233 manually to ensure Git can behave optimally.
 234
 235
 236 SUBMODULES
 237 ----------
 238
 239 If your repository contains one or more submodules, then submodules
 240 are populated based on interactions with the `git submodule` command.
 241 Specifically, `git submodule init -- <path>` will ensure the submodule
 242 at `<path>` is present, while `git submodule deinit [-f] -- <path>`
 243 will remove the files for the submodule at `<path>` (including any
 244 untracked files, uncommitted changes, and unpushed history).  Similar
 245 to how sparse-checkout removes files from the working tree but still
 246 leaves entries in the index, deinitialized submodules are removed from
 247 the working directory but still have an entry in the index.
 248
 249 Since submodules may have unpushed changes or untracked files,
 250 removing them could result in data loss.  Thus, changing sparse
 251 inclusion/exclusion rules will not cause an already checked out
 252 submodule to be removed from the working copy.  Said another way, just
 253 as `checkout` will not cause submodules to be automatically removed or
 254 initialized even when switching between branches that remove or add
 255 submodules, using `sparse-checkout` to reduce or expand the scope of
 256 "interesting" files will not cause submodules to be automatically
 257 deinitialized or initialized either.
 258
 259 Further, the above facts mean that there are multiple reasons that
 260 "tracked" files might not be present in the working copy: sparsity
 261 pattern application from sparse-checkout, and submodule initialization
 262 state.  Thus, commands like `git grep` that work on tracked files in
 263 the working copy may return results that are limited by either or both
 264 of these restrictions.
 265
 266
 267 SEE ALSO
 268 --------
 269
 270 linkgit:git-read-tree[1]
 271 linkgit:gitignore[5]
 272
 273 GIT
 274 ---
 275 Part of the linkgit:git[1] suite