You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
299 lines
12 KiB
299 lines
12 KiB
git-sparse-checkout(1) |
|
====================== |
|
|
|
NAME |
|
---- |
|
git-sparse-checkout - Reduce your working tree to a subset of tracked files |
|
|
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git sparse-checkout <subcommand> [<options>]' |
|
|
|
|
|
DESCRIPTION |
|
----------- |
|
|
|
This command is used to create sparse checkouts, which means that it |
|
changes the working tree from having all tracked files present, to only |
|
have a subset of them. It can also switch which subset of files are |
|
present, or undo and go back to having all tracked files present in the |
|
working copy. |
|
|
|
The subset of files is chosen by providing a list of directories in |
|
cone mode (which is recommended), or by providing a list of patterns |
|
in non-cone mode. |
|
|
|
When in a sparse-checkout, other Git commands behave a bit differently. |
|
For example, switching branches will not update paths outside the |
|
sparse-checkout directories/patterns, and `git commit -a` will not record |
|
paths outside the sparse-checkout directories/patterns as deleted. |
|
|
|
THIS COMMAND IS EXPERIMENTAL. ITS BEHAVIOR, AND THE BEHAVIOR OF OTHER |
|
COMMANDS IN THE PRESENCE OF SPARSE-CHECKOUTS, WILL LIKELY CHANGE IN |
|
THE FUTURE. |
|
|
|
|
|
COMMANDS |
|
-------- |
|
'list':: |
|
Describe the directories or patterns in the sparse-checkout file. |
|
|
|
'set':: |
|
Enable the necessary sparse-checkout config settings |
|
(`core.sparseCheckout`, `core.sparseCheckoutCone`, and |
|
`index.sparse`) 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 'set' subcommand. Update the |
|
working directory to match the new patterns. |
|
+ |
|
To ensure that adjusting the sparse-checkout settings within a worktree |
|
does not alter the sparse-checkout settings in other worktrees, the 'set' |
|
subcommand will upgrade your repository config to use worktree-specific |
|
config if not already present. The sparsity defined by the arguments to |
|
the 'set' subcommand are stored in the worktree-specific sparse-checkout |
|
file. See linkgit:git-worktree[1] and the documentation of |
|
`extensions.worktreeConfig` in linkgit:git-config[1] for more details. |
|
+ |
|
When the `--stdin` option is provided, the directories or patterns are |
|
read from standard in as a newline-delimited list instead of from the |
|
arguments. |
|
+ |
|
When `--cone` is passed or `core.sparseCheckoutCone` is enabled, the |
|
input list is considered a list of directories. This allows for |
|
better performance with a limited set of patterns (see 'CONE PATTERN |
|
SET' below). The input format matches the output of `git ls-tree |
|
--name-only`. This includes interpreting pathnames that begin with a |
|
double quote (") as C-style quoted strings. 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. This may become the default in the |
|
future; --no-cone can be passed to request non-cone mode. |
|
+ |
|
When `--no-cone` is passed or `core.sparseCheckoutCone` is not enabled, |
|
the input list is considered a list of patterns. This mode is harder |
|
to use and less performant, and is thus not recommended. See the |
|
"Sparse Checkout" section of linkgit:git-read-tree[1] and the "Pattern |
|
Set" sections below for more details. |
|
+ |
|
Use the `--[no-]sparse-index` 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 `git status` or `git add`. This feature is still |
|
experimental. Some commands might be slower with a sparse index until |
|
they are properly integrated with the feature. |
|
+ |
|
**WARNING:** 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 `git sparse-checkout init --no-sparse-index` |
|
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. |
|
|
|
'add':: |
|
Update the sparse-checkout file to include additional directories |
|
(in cone mode) or patterns (in non-cone mode). By default, these |
|
directories or patterns are read from the command-line arguments, |
|
but they can be read from stdin using the `--stdin` option. |
|
|
|
'reapply':: |
|
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 `git sparse-checkout reapply` later |
|
after cleaning up affected paths (e.g. resolving conflicts, undoing |
|
or committing changes, etc.). |
|
+ |
|
The `reapply` command can also take `--[no-]cone` and `--[no-]sparse-index` |
|
flags, with the same meaning as the flags from the `set` command, in order |
|
to change which sparsity mode you are using without needing to also respecify |
|
all sparsity paths. |
|
|
|
'disable':: |
|
Disable the `core.sparseCheckout` config setting, and restore the |
|
working directory to include all files. |
|
|
|
'init':: |
|
Deprecated command that behaves like `set` with no specified paths. |
|
May be removed in the future. |
|
+ |
|
Historically, `set` did not handle all the necessary config settings, |
|
which meant that both `init` and `set` had to be called. Invoking |
|
both meant the `init` step would first remove nearly all tracked files |
|
(and in cone mode, ignored files too), then the `set` 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. |
|
+ |
|
Also, historically, `init` 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 'set' or 'add' command. However, |
|
`--cone` and `--sparse-index` options would not be remembered across |
|
the disable command, so the easy restore of calling a plain `init` |
|
decreased in utility. |
|
|
|
SPARSE CHECKOUT |
|
--------------- |
|
|
|
"Sparse checkout" allows populating the working directory sparsely. It |
|
uses the skip-worktree bit (see linkgit:git-update-index[1]) to tell Git |
|
whether a file in the working directory is worth looking at. If the |
|
skip-worktree bit is set, and the file is not present in the working tree, |
|
then its absence is ignored. 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. |
|
|
|
The `$GIT_DIR/info/sparse-checkout` 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. |
|
|
|
To enable the sparse-checkout feature, run `git sparse-checkout set` to |
|
set the patterns you want to use. |
|
|
|
To repopulate the working directory with all files, use the |
|
`git sparse-checkout disable` command. |
|
|
|
|
|
FULL PATTERN SET |
|
---------------- |
|
|
|
By default, the sparse-checkout file uses the same syntax as `.gitignore` |
|
files. |
|
|
|
While `$GIT_DIR/info/sparse-checkout` is usually used to specify what |
|
files are included, you can also specify what files are _not_ included, |
|
using negative patterns. For example, to remove the file `unwanted`: |
|
|
|
---------------- |
|
/* |
|
!unwanted |
|
---------------- |
|
|
|
|
|
CONE PATTERN SET |
|
---------------- |
|
|
|
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 `core.sparseCheckoutCone` is enabled. |
|
|
|
The accepted patterns in the cone pattern set are: |
|
|
|
1. *Recursive:* All paths inside a directory are included. |
|
|
|
2. *Parent:* All files immediately inside a directory are included. |
|
|
|
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. |
|
|
|
By default, when running `git sparse-checkout init`, the root directory is |
|
added as a parent pattern. At this point, the sparse-checkout file contains |
|
the following patterns: |
|
|
|
---------------- |
|
/* |
|
!/*/ |
|
---------------- |
|
|
|
This says "include everything in root, but nothing two levels below root." |
|
|
|
When in cone mode, the `git sparse-checkout set` subcommand takes a list of |
|
directories instead of a list of sparse-checkout patterns. In this mode, |
|
the command `git sparse-checkout set A/B/C` sets the directory `A/B/C` as |
|
a recursive pattern, the directories `A` and `A/B` are added as parent |
|
patterns. The resulting sparse-checkout file is now |
|
|
|
---------------- |
|
/* |
|
!/*/ |
|
/A/ |
|
!/A/*/ |
|
/A/B/ |
|
!/A/B/*/ |
|
/A/B/C/ |
|
---------------- |
|
|
|
Here, order matters, so the negative patterns are overridden by the positive |
|
patterns that appear lower in the file. |
|
|
|
If `core.sparseCheckoutCone=true`, 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. |
|
|
|
In the cone mode case, the `git sparse-checkout list` subcommand will list the |
|
directories that define the recursive patterns. For the example sparse-checkout |
|
file above, the output is as follows: |
|
|
|
-------------------------- |
|
$ git sparse-checkout list |
|
A/B/C |
|
-------------------------- |
|
|
|
If `core.ignoreCase=true`, then the pattern-matching algorithm will use a |
|
case-insensitive check. This corrects for case mismatched filenames in the |
|
'git sparse-checkout set' command to reflect the expected cone in the working |
|
directory. |
|
|
|
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 |
|
`.gitignore` 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 `git add` and `git commit` to store them, then remove any remaining files |
|
manually to ensure Git can behave optimally. |
|
|
|
|
|
SUBMODULES |
|
---------- |
|
|
|
If your repository contains one or more submodules, then submodules |
|
are populated based on interactions with the `git submodule` command. |
|
Specifically, `git submodule init -- <path>` will ensure the submodule |
|
at `<path>` is present, while `git submodule deinit [-f] -- <path>` |
|
will remove the files for the submodule at `<path>` (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. |
|
|
|
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 `checkout` will not cause submodules to be automatically removed or |
|
initialized even when switching between branches that remove or add |
|
submodules, using `sparse-checkout` to reduce or expand the scope of |
|
"interesting" files will not cause submodules to be automatically |
|
deinitialized or initialized either. |
|
|
|
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 `git grep` that work on tracked files in |
|
the working copy may return results that are limited by either or both |
|
of these restrictions. |
|
|
|
|
|
SEE ALSO |
|
-------- |
|
|
|
linkgit:git-read-tree[1] |
|
linkgit:gitignore[5] |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[1] suite
|
|
|