71ceb816b3
The 'init' subcommand of sparse-checkout was deprecated in ba2f3f58ac
("git-sparse-checkout.txt: update to document init/set/reapply changes",
2021-12-14), but a couple places in the manual still assumed it was the
primary way to use sparse-checkout. Correct them.
Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
299 lines
12 KiB
Plaintext
299 lines
12 KiB
Plaintext
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 (the default), 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,
|
|
populate the sparse-checkout file from the list of arguments
|
|
following the 'set' subcommand, and update the working directory to
|
|
match.
|
|
+
|
|
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.
|
|
+
|
|
By default, the input list is considered a list of directories, matching
|
|
the output of `git ls-tree -d --name-only`. This includes interpreting
|
|
pathnames that begin with a double quote (") as C-style quoted strings.
|
|
Note that all files under the specified directories (at any depth) will
|
|
be included in the sparse checkout, as well as files that are siblings
|
|
of either the given directory or any of its ancestors (see 'CONE PATTERN
|
|
SET' below for more details). In the past, this was not the default,
|
|
and `--cone` needed to be specified or `core.sparseCheckoutCone` needed
|
|
to be enabled.
|
|
+
|
|
When `--no-cone` is passed, 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 set` with no directories
|
|
specified, 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. 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.
|
|
|
|
Unless `core.sparseCheckoutCone` is explicitly set to `false`, 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
|