git.oblomov.eu Git - git/blob - 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 atterns.
   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 'init'::
  34         Enable the `core.sparseCheckout` setting. If the
  35         sparse-checkout file does not exist, then populate it with
  36         patterns that match every file in the root directory and
  37         no other directories, then will remove all directories tracked
  38         by Git. Add patterns to the sparse-checkout file to
  39         repopulate the working directory.
  40 +
  41 To avoid interfering with other worktrees, it first enables the
  42 `extensions.worktreeConfig` setting and makes sure to set the
  43 `core.sparseCheckout` setting in the worktree-specific config file.
  44
  45 'set'::
  46         Write a set of patterns to the sparse-checkout file, as given as
  47         a list of arguments following the 'set' subcommand. Update the
  48         working directory to match the new patterns. Enable the
  49         core.sparseCheckout config setting if it is not already enabled.
  50 +
  51 When the `--stdin` option is provided, the patterns are read from
  52 standard in as a newline-delimited list instead of from the arguments.
  53 +
  54 When `core.sparseCheckoutCone` is enabled, the input list is considered a
  55 list of directories instead of sparse-checkout patterns. The command writes
  56 patterns to the sparse-checkout file to include all files contained in those
  57 directories (recursively) as well as files that are siblings of ancestor
  58 directories. The input format matches the output of `git ls-tree --name-only`.
  59 This includes interpreting pathnames that begin with a double quote (") as
  60 C-style quoted strings.
  61
  62 'disable'::
  63         Disable the `core.sparseCheckout` config setting, and restore the
  64         working directory to include all files. Leaves the sparse-checkout
  65         file intact so a later 'git sparse-checkout init' command may
  66         return the working directory to the same state.
  67
  68 SPARSE CHECKOUT
  69 ---------------
  70
  71 "Sparse checkout" allows populating the working directory sparsely.
  72 It uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell
  73 Git whether a file in the working directory is worth looking at. If
  74 the skip-worktree bit is set, then the file is ignored in the working
  75 directory. Git will not populate the contents of those files, which
  76 makes a sparse checkout helpful when working in a repository with many
  77 files, but only a few are important to the current user.
  78
  79 The `$GIT_DIR/info/sparse-checkout` file is used to define the
  80 skip-worktree reference bitmap. When Git updates the working
  81 directory, it updates the skip-worktree bits in the index based
  82 on this file. The files matching the patterns in the file will
  83 appear in the working directory, and the rest will not.
  84
  85 To enable the sparse-checkout feature, run `git sparse-checkout init` to
  86 initialize a simple sparse-checkout file and enable the `core.sparseCheckout`
  87 config setting. Then, run `git sparse-checkout set` to modify the patterns in
  88 the sparse-checkout file.
  89
  90 To repopulate the working directory with all files, use the
  91 `git sparse-checkout disable` command.
  92
  93
  94 FULL PATTERN SET
  95 ----------------
  96
  97 By default, the sparse-checkout file uses the same syntax as `.gitignore`
  98 files.
  99
 100 While `$GIT_DIR/info/sparse-checkout` is usually used to specify what
 101 files are included, you can also specify what files are _not_ included,
 102 using negative patterns. For example, to remove the file `unwanted`:
 103
 104 ----------------
 105 /*
 106 !unwanted
 107 ----------------
 108
 109
 110 CONE PATTERN SET
 111 ----------------
 112
 113 The full pattern set allows for arbitrary pattern matches and complicated
 114 inclusion/exclusion rules. These can result in O(N*M) pattern matches when
 115 updating the index, where N is the number of patterns and M is the number
 116 of paths in the index. To combat this performance issue, a more restricted
 117 pattern set is allowed when `core.sparseCheckoutCone` is enabled.
 118
 119 The accepted patterns in the cone pattern set are:
 120
 121 1. *Recursive:* All paths inside a directory are included.
 122
 123 2. *Parent:* All files immediately inside a directory are included.
 124
 125 In addition to the above two patterns, we also expect that all files in the
 126 root directory are included. If a recursive pattern is added, then all
 127 leading directories are added as parent patterns.
 128
 129 By default, when running `git sparse-checkout init`, the root directory is
 130 added as a parent pattern. At this point, the sparse-checkout file contains
 131 the following patterns:
 132
 133 ----------------
 134 /*
 135 !/*/
 136 ----------------
 137
 138 This says "include everything in root, but nothing two levels below root."
 139
 140 When in cone mode, the `git sparse-checkout set` subcommand takes a list of
 141 directories instead of a list of sparse-checkout patterns. In this mode,
 142 the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as
 143 a recursive pattern, the directories `A` and `A/B` are added as parent
 144 patterns. The resulting sparse-checkout file is now
 145
 146 ----------------
 147 /*
 148 !/*/
 149 /A/
 150 !/A/*/
 151 /A/B/
 152 !/A/B/*/
 153 /A/B/C/
 154 ----------------
 155
 156 Here, order matters, so the negative patterns are overridden by the positive
 157 patterns that appear lower in the file.
 158
 159 If `core.sparseCheckoutCone=true`, then Git will parse the sparse-checkout file
 160 expecting patterns of these types. Git will warn if the patterns do not match.
 161 If the patterns do match the expected format, then Git will use faster hash-
 162 based algorithms to compute inclusion in the sparse-checkout.
 163
 164 In the cone mode case, the `git sparse-checkout list` subcommand will list the
 165 directories that define the recursive patterns. For the example sparse-checkout
 166 file above, the output is as follows:
 167
 168 --------------------------
 169 $ git sparse-checkout list
 170 A/B/C
 171 --------------------------
 172
 173 If `core.ignoreCase=true`, then the pattern-matching algorithm will use a
 174 case-insensitive check. This corrects for case mismatched filenames in the
 175 'git sparse-checkout set' command to reflect the expected cone in the working
 176 directory.
 177
 178
 179 SUBMODULES
 180 ----------
 181
 182 If your repository contains one or more submodules, then those submodules will
 183 appear based on which you initialized with the `git submodule` command. If
 184 your sparse-checkout patterns exclude an initialized submodule, then that
 185 submodule will still appear in your working directory.
 186
 187
 188 SEE ALSO
 189 --------
 190
 191 linkgit:git-read-tree[1]
 192 linkgit:gitignore[5]
 193
 194 GIT
 195 ---
 196 Part of the linkgit:git[1] suite