| '\" t |
| .\" Title: git-sparse-checkout |
| .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
| .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> |
| .\" Date: 03/07/2022 |
| .\" Manual: Git Manual |
| .\" Source: Git 2.35.1.415.gc2162907e9 |
| .\" Language: English |
| .\" |
| .TH "GIT\-SPARSE\-CHECKOU" "1" "03/07/2022" "Git 2\&.35\&.1\&.415\&.gc21629" "Git Manual" |
| .\" ----------------------------------------------------------------- |
| .\" * Define some portability stuff |
| .\" ----------------------------------------------------------------- |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .\" http://bugs.debian.org/507673 |
| .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" ----------------------------------------------------------------- |
| .\" * set default formatting |
| .\" ----------------------------------------------------------------- |
| .\" disable hyphenation |
| .nh |
| .\" disable justification (adjust text to left margin only) |
| .ad l |
| .\" ----------------------------------------------------------------- |
| .\" * MAIN CONTENT STARTS HERE * |
| .\" ----------------------------------------------------------------- |
| .SH "NAME" |
| git-sparse-checkout \- Initialize and modify the sparse\-checkout configuration, which reduces the checkout to a set of paths given by a list of patterns\&. |
| .SH "SYNOPSIS" |
| .sp |
| .nf |
| \fIgit sparse\-checkout <subcommand> [<options>]\fR |
| .fi |
| .sp |
| .SH "DESCRIPTION" |
| .sp |
| Initialize and modify the sparse\-checkout configuration, which reduces the checkout to a set of paths given by a list of patterns\&. |
| .sp |
| THIS COMMAND IS EXPERIMENTAL\&. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER COMMANDS IN THE PRESENCE OF SPARSE\-CHECKOUTS, WILL LIKELY CHANGE IN THE FUTURE\&. |
| .SH "COMMANDS" |
| .PP |
| \fIlist\fR |
| .RS 4 |
| Describe the patterns in the sparse\-checkout file\&. |
| .RE |
| .PP |
| \fIset\fR |
| .RS 4 |
| Enable the necessary sparse\-checkout config settings (\fBcore\&.sparseCheckout\fR, |
| \fBcore\&.sparseCheckoutCone\fR, and |
| \fBindex\&.sparse\fR) if they are not already set to the desired values, and write a set of patterns to the sparse\-checkout file from the list of arguments following the |
| \fIset\fR |
| subcommand\&. Update the working directory to match the new patterns\&. |
| .sp |
| To ensure that adjusting the sparse\-checkout settings within a worktree does not alter the sparse\-checkout settings in other worktrees, the |
| \fIset\fR |
| subcommand will upgrade your repository config to use worktree\-specific config if not already present\&. The sparsity defined by the arguments to the |
| \fIset\fR |
| subcommand are stored in the worktree\-specific sparse\-checkout file\&. See |
| \fBgit-worktree\fR(1) |
| and the documentation of |
| \fBextensions\&.worktreeConfig\fR |
| in |
| \fBgit-config\fR(1) |
| for more details\&. |
| .sp |
| When the |
| \fB\-\-stdin\fR |
| option is provided, the patterns are read from standard in as a newline\-delimited list instead of from the arguments\&. |
| .sp |
| When |
| \fB\-\-cone\fR |
| is passed or |
| \fBcore\&.sparseCheckoutCone\fR |
| is enabled, the input list is considered a list of directories instead of sparse\-checkout patterns\&. This allows for better performance with a limited set of patterns (see |
| \fICONE PATTERN SET\fR |
| below)\&. Note that the set command will write patterns to the sparse\-checkout file to include all files contained in those directories (recursively) as well as files that are siblings of ancestor directories\&. The input format matches the output of |
| \fBgit ls\-tree \-\-name\-only\fR\&. This includes interpreting pathnames that begin with a double quote (") as C\-style quoted strings\&. This may become the default in the future; \-\-no\-cone can be passed to request non\-cone mode\&. |
| .sp |
| Use the |
| \fB\-\-[no\-]sparse\-index\fR |
| option to use a sparse index (the default is to not use it)\&. A sparse index reduces the size of the index to be more closely aligned with your sparse\-checkout definition\&. This can have significant performance advantages for commands such as |
| \fBgit status\fR |
| or |
| \fBgit add\fR\&. This feature is still experimental\&. Some commands might be slower with a sparse index until they are properly integrated with the feature\&. |
| .sp |
| \fBWARNING:\fR |
| Using a sparse index requires modifying the index in a way that is not completely understood by external tools\&. If you have trouble with this compatibility, then run |
| \fBgit sparse\-checkout init \-\-no\-sparse\-index\fR |
| to rewrite your index to not be sparse\&. Older versions of Git will not understand the sparse directory entries index extension and may fail to interact with your repository until it is disabled\&. |
| .RE |
| .PP |
| \fIadd\fR |
| .RS 4 |
| Update the sparse\-checkout file to include additional patterns\&. By default, these patterns are read from the command\-line arguments, but they can be read from stdin using the |
| \fB\-\-stdin\fR |
| option\&. When |
| \fBcore\&.sparseCheckoutCone\fR |
| is enabled, the given patterns are interpreted as directory names as in the |
| \fIset\fR |
| subcommand\&. |
| .RE |
| .PP |
| \fIreapply\fR |
| .RS 4 |
| Reapply the sparsity pattern rules to paths in the working tree\&. Commands like merge or rebase can materialize paths to do their work (e\&.g\&. in order to show you a conflict), and other sparse\-checkout commands might fail to sparsify an individual file (e\&.g\&. because it has unstaged changes or conflicts)\&. In such cases, it can make sense to run |
| \fBgit sparse\-checkout reapply\fR |
| later after cleaning up affected paths (e\&.g\&. resolving conflicts, undoing or committing changes, etc\&.)\&. |
| .sp |
| The |
| \fBreapply\fR |
| command can also take |
| \fB\-\-[no\-]cone\fR |
| and |
| \fB\-\-[no\-]sparse\-index\fR |
| flags, with the same meaning as the flags from the |
| \fBset\fR |
| command, in order to change which sparsity mode you are using without needing to also respecify all sparsity paths\&. |
| .RE |
| .PP |
| \fIdisable\fR |
| .RS 4 |
| Disable the |
| \fBcore\&.sparseCheckout\fR |
| config setting, and restore the working directory to include all files\&. |
| .RE |
| .PP |
| \fIinit\fR |
| .RS 4 |
| Deprecated command that behaves like |
| \fBset\fR |
| with no specified paths\&. May be removed in the future\&. |
| .sp |
| Historically, |
| \fBset\fR |
| did not handle all the necessary config settings, which meant that both |
| \fBinit\fR |
| and |
| \fBset\fR |
| had to be called\&. Invoking both meant the |
| \fBinit\fR |
| step would first remove nearly all tracked files (and in cone mode, ignored files too), then the |
| \fBset\fR |
| step would add many of the tracked files (but not ignored files) back\&. In addition to the lost files, the performance and UI of this combination was poor\&. |
| .sp |
| Also, historically, |
| \fBinit\fR |
| would not actually initialize the sparse\-checkout file if it already existed\&. This meant it was possible to return to a sparse\-checkout without remembering which paths to pass to a subsequent |
| \fIset\fR |
| or |
| \fIadd\fR |
| command\&. However, |
| \fB\-\-cone\fR |
| and |
| \fB\-\-sparse\-index\fR |
| options would not be remembered across the disable command, so the easy restore of calling a plain |
| \fBinit\fR |
| decreased in utility\&. |
| .RE |
| .SH "SPARSE CHECKOUT" |
| .sp |
| "Sparse checkout" allows populating the working directory sparsely\&. It uses the skip\-worktree bit (see \fBgit-update-index\fR(1)) to tell Git whether a file in the working directory is worth looking at\&. If the skip\-worktree bit is set, then the file is ignored in the working directory\&. Git will avoid populating the contents of those files, which makes a sparse checkout helpful when working in a repository with many files, but only a few are important to the current user\&. |
| .sp |
| The \fB$GIT_DIR/info/sparse\-checkout\fR file is used to define the skip\-worktree reference bitmap\&. When Git updates the working directory, it updates the skip\-worktree bits in the index based on this file\&. The files matching the patterns in the file will appear in the working directory, and the rest will not\&. |
| .sp |
| To enable the sparse\-checkout feature, run \fBgit sparse\-checkout set\fR to set the patterns you want to use\&. |
| .sp |
| To repopulate the working directory with all files, use the \fBgit sparse\-checkout disable\fR command\&. |
| .SH "FULL PATTERN SET" |
| .sp |
| By default, the sparse\-checkout file uses the same syntax as \fB\&.gitignore\fR files\&. |
| .sp |
| While \fB$GIT_DIR/info/sparse\-checkout\fR is usually used to specify what files are included, you can also specify what files are \fInot\fR included, using negative patterns\&. For example, to remove the file \fBunwanted\fR: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| /* |
| !unwanted |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .SH "CONE PATTERN SET" |
| .sp |
| The full pattern set allows for arbitrary pattern matches and complicated inclusion/exclusion rules\&. These can result in O(N*M) pattern matches when updating the index, where N is the number of patterns and M is the number of paths in the index\&. To combat this performance issue, a more restricted pattern set is allowed when \fBcore\&.sparseCheckoutCone\fR is enabled\&. |
| .sp |
| The accepted patterns in the cone pattern set are: |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 1.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 1." 4.2 |
| .\} |
| \fBRecursive:\fR |
| All paths inside a directory are included\&. |
| .RE |
| .sp |
| .RS 4 |
| .ie n \{\ |
| \h'-04' 2.\h'+01'\c |
| .\} |
| .el \{\ |
| .sp -1 |
| .IP " 2." 4.2 |
| .\} |
| \fBParent:\fR |
| All files immediately inside a directory are included\&. |
| .RE |
| .sp |
| In addition to the above two patterns, we also expect that all files in the root directory are included\&. If a recursive pattern is added, then all leading directories are added as parent patterns\&. |
| .sp |
| By default, when running \fBgit sparse\-checkout init\fR, the root directory is added as a parent pattern\&. At this point, the sparse\-checkout file contains the following patterns: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| /* |
| !/*/ |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| This says "include everything in root, but nothing two levels below root\&." |
| .sp |
| When in cone mode, the \fBgit sparse\-checkout set\fR subcommand takes a list of directories instead of a list of sparse\-checkout patterns\&. In this mode, the command \fBgit sparse\-checkout set A/B/C\fR sets the directory \fBA/B/C\fR as a recursive pattern, the directories \fBA\fR and \fBA/B\fR are added as parent patterns\&. The resulting sparse\-checkout file is now |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| /* |
| !/*/ |
| /A/ |
| !/A/*/ |
| /A/B/ |
| !/A/B/*/ |
| /A/B/C/ |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| Here, order matters, so the negative patterns are overridden by the positive patterns that appear lower in the file\&. |
| .sp |
| If \fBcore\&.sparseCheckoutCone=true\fR, then Git will parse the sparse\-checkout file expecting patterns of these types\&. Git will warn if the patterns do not match\&. If the patterns do match the expected format, then Git will use faster hash\- based algorithms to compute inclusion in the sparse\-checkout\&. |
| .sp |
| In the cone mode case, the \fBgit sparse\-checkout list\fR subcommand will list the directories that define the recursive patterns\&. For the example sparse\-checkout file above, the output is as follows: |
| .sp |
| .if n \{\ |
| .RS 4 |
| .\} |
| .nf |
| $ git sparse\-checkout list |
| A/B/C |
| .fi |
| .if n \{\ |
| .RE |
| .\} |
| .sp |
| .sp |
| If \fBcore\&.ignoreCase=true\fR, then the pattern\-matching algorithm will use a case\-insensitive check\&. This corrects for case mismatched filenames in the \fIgit sparse\-checkout set\fR command to reflect the expected cone in the working directory\&. |
| .sp |
| When changing the sparse\-checkout patterns in cone mode, Git will inspect each tracked directory that is not within the sparse\-checkout cone to see if it contains any untracked files\&. If all of those files are ignored due to the \fB\&.gitignore\fR patterns, then the directory will be deleted\&. If any of the untracked files within that directory is not ignored, then no deletions will occur within that directory and a warning message will appear\&. If these files are important, then reset your sparse\-checkout definition so they are included, use \fBgit add\fR and \fBgit commit\fR to store them, then remove any remaining files manually to ensure Git can behave optimally\&. |
| .SH "SUBMODULES" |
| .sp |
| If your repository contains one or more submodules, then submodules are populated based on interactions with the \fBgit submodule\fR command\&. Specifically, \fBgit submodule init \-\- <path>\fR will ensure the submodule at \fB<path>\fR is present, while \fBgit submodule deinit [\-f] \-\- <path>\fR will remove the files for the submodule at \fB<path>\fR (including any untracked files, uncommitted changes, and unpushed history)\&. Similar to how sparse\-checkout removes files from the working tree but still leaves entries in the index, deinitialized submodules are removed from the working directory but still have an entry in the index\&. |
| .sp |
| Since submodules may have unpushed changes or untracked files, removing them could result in data loss\&. Thus, changing sparse inclusion/exclusion rules will not cause an already checked out submodule to be removed from the working copy\&. Said another way, just as \fBcheckout\fR will not cause submodules to be automatically removed or initialized even when switching between branches that remove or add submodules, using \fBsparse\-checkout\fR to reduce or expand the scope of "interesting" files will not cause submodules to be automatically deinitialized or initialized either\&. |
| .sp |
| Further, the above facts mean that there are multiple reasons that "tracked" files might not be present in the working copy: sparsity pattern application from sparse\-checkout, and submodule initialization state\&. Thus, commands like \fBgit grep\fR that work on tracked files in the working copy may return results that are limited by either or both of these restrictions\&. |
| .SH "SEE ALSO" |
| .sp |
| \fBgit-read-tree\fR(1) \fBgitignore\fR(5) |
| .SH "GIT" |
| .sp |
| Part of the \fBgit\fR(1) suite |